# systemd 手册 systemd 手册。内容保持上游原样。 # SD_ELF_NOTE_DLOPEN systemd SD_ELF_NOTE_DLOPEN 3 SD_ELF_NOTE_DLOPEN SD_ELF_NOTE_DLOPEN_VENDOR SD_ELF_NOTE_DLOPEN_TYPE SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED Embed ELF .note.dlopen metadata for shared library dependencies \#include \ SD_ELF_NOTE_DLOPEN( feature , description , priority , soname... ) \#define SD_ELF_NOTE_DLOPEN_VENDOR "FDO" \#define SD_ELF_NOTE_DLOPEN_TYPE UINT32_C(0x407c0c0a) \#define SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED "required" \#define SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED "recommended" \#define SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED "suggested" # Description `SD_ELF_NOTE_DLOPEN()` is a macro that embeds a `.note.dlopen` ELF note section in the compiled binary, declaring a weak dependency on a shared library loaded via `dlopen()`. This implements the [ELF dlopen metadata](https://uapi-group.org/specifications/specs/elf_dlopen_metadata/) specification, allowing package managers and build systems to discover runtime dependencies that are not visible through regular ELF `DT_NEEDED` entries. The macro takes the following parameters: `feature` A short string identifying the feature this library provides (e.g. `XKB`, `PCRE2`). `description` A human-readable description of what the library is used for. `priority` One of `SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED`, `SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED`, or `SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED`, indicating how important the dependency is. `soname...` One or more shared object names (sonames) for the library, e.g. `libfoo.so.1`. Multiple sonames may be specified as separate arguments (up to 5) for libraries that have changed soname across versions. The embedded metadata can be read from a compiled ELF binary using: systemd-analyze dlopen-metadata binary # Examples
Single soname
#include SD_ELF_NOTE_DLOPEN("XKB", "Keyboard layout support", SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED, "libxkbcommon.so.0");
Multiple sonames for different library versions
SD_ELF_NOTE_DLOPEN("crypt", "Support for hashing passwords", SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED, "libcrypt.so.2", "libcrypt.so.1", "libcrypt.so.1.1");
# Notes The macros described here are header-only and do not require runtime linkage against `libsystemd(3)`. Only the installed header and include path (as provided by `pkg-config --cflags libsystemd`) are needed. # History `SD_ELF_NOTE_DLOPEN()`, `SD_ELF_NOTE_DLOPEN_VENDOR`, `SD_ELF_NOTE_DLOPEN_TYPE`, `SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED`, `SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED`, and `SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED` were added in version 261. # See Also `systemd(1)`, `sd-dlopen(3)`, `dlopen(3)` # binfmt.d systemd binfmt.d 5 binfmt.d Configure additional binary formats for executables at boot `/etc/binfmt.d/*.conf`, `/run/binfmt.d/*.conf`, `/usr/local/lib/binfmt.d/*.conf`, `/usr/lib/binfmt.d/*.conf` # Description At boot, `systemd-binfmt.service(8)` reads configuration files from the above directories to register in the kernel additional binary formats for executables. # Configuration Format Each file contains a list of binfmt_misc kernel binary format rules. Consult the kernel's [Kernel Support for miscellaneous Binary Formats (binfmt_misc)](https://docs.kernel.org/admin-guide/binfmt-misc.html) documentation file for more information on registration of additional binary formats and how to write rules. Empty lines and lines beginning with `;` and `#` are ignored. Note that this means you may not use those symbols as the delimiter in binary format rules. # Example
/etc/binfmt.d/wine.conf example:
# Start WINE on Windows executables :DOSWin:M::MZ::/usr/bin/wine:
# See Also `systemd(1)`, `systemd-binfmt.service(8)`, `systemd-delta(1)`, `wine(8)` # bootctl systemd bootctl 1 bootctl Control EFI firmware boot settings and manage boot loader bootctl OPTIONS COMMAND # Description `bootctl` can check the EFI firmware and boot loader status, list and manage available boot loaders and boot loader entries, and install, update, or remove the `systemd-boot(7)` boot loader on the current system. # Generic EFI Firmware/Boot Loader Commands These commands are available on any EFI system, regardless of the boot loader used. `status` Shows brief information about the system firmware, the boot loader that was used to boot the system, the boot loaders currently available in the ESP, the boot loaders listed in the firmware's list of boot loaders and the current default boot loader entry. If no command is specified, this is the implied default. See the example below for details of the output. `reboot-to-firmware` \[\\] Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI firmware. Takes a boolean argument which controls whether to show the firmware setup on next system reboot. If the argument is omitted shows the current status of the flag, or whether the flag is supported. This controls the same flag as `systemctl reboot --firmware-setup`, but is more low-level and allows setting the flag independently from actually requesting a reboot. Hint: use `systemctl reboot --firmware-setup` to reboot into firmware setup once. See `systemctl(1)` for details. # Boot Loader Specification Commands These commands are available for all boot loaders that implement the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification), such as `systemd-boot`. `list` Shows all available boot loader entries implementing the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification), as well as any other entries discovered or automatically generated by a boot loader implementing the [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE). JSON output may be requested with `--json=`. See the example below for details of the output. `unlink` \[\\] Removes a boot loader entry including the files it refers to. Takes an optional boot loader entry ID string or a glob pattern as argument. Referenced files such as the kernel, initrds, system extensions (sysexts), configuration extensions (confexts) or credential files are only removed if no other entry refers to them. If no \ argument is specified, the `--oldest` option must be specified, in which case the boot loader entry with the lowest version is removed (for robustness reasons the currently booted menu entry is never removed, nor is the last existing boot loader entry). `link` \ Creates one or more Type \#1 boot loader entries pointing to the specified UKI. Takes the path to a Unified Kernel Image (UKI) as argument. The UKI is copied into the ESP (or XBOOTLDR partition if present) below the configured entry token directory, and one or more [Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#1 entries are generated referring to it (one per UKI profile, if multiple profiles are embedded). The title, version, commit number and initial try counter of the generated entries may be overridden with `--entry-title=`, `--entry-version=`, `--entry-commit=` and `--tries-left=`. Additional sidecar resources (system extension images, configuration extension images, credential files) to pass to the UKI at boot may be specified with `--extra=`. If the ESP/XBOOTLDR do not have enough free space for the new boot loader entry and its referenced resources the oldest existing boot loader entry matching the selected entry token is removed (along with any resources referenced by it that are no longer referenced by any other entry). This step is repeated until the new boot loader entry fits. For robustness reasons the currently booted boot loader entry is never removed, nor is the last existing boot loader entry. By default, the operation refuses to proceed if the resulting ESP/XBOOTLDR free space would drop below a safety threshold after automatic removal of older entries completes; use `--keep-free=` to adjust. `link-auto` Like `link`, but instead of taking the kernel and sidecar resources as arguments, discovers them automatically. The following directories are searched, in decreasing order of priority: `/etc/systemd/uki/`, `/run/systemd/uki/`, `/var/lib/systemd/uki/` (where `systemd-sysupdate(8)` stages downloaded resources), `/usr/local/lib/systemd/uki/` and `/usr/lib/systemd/uki/`. In each directory the UKI is taken from `kernel.efi`, or — if absent — the newest version in the versioned directory `kernel.efi.v/` (see `systemd.v(7)`); the UKI from the highest-priority directory that has one is used. Sidecar resources are picked up from the `extras.d/` subdirectory of each, matching the suffixes `.sysext.raw`, `.confext.raw` and `.cred`, each either as a plain file or as a versioned `.v/` directory; resources are combined across all directories, with the same resource in a higher-priority directory taking precedence. Any files specified with `--extra=` are linked in addition to the discovered ones. This is used by `systemd-sysupdate(8)` when it completes an update, so a freshly downloaded kernel and its sidecar resources are linked into place without specifying any paths. `cleanup` Removes files from the ESP and XBOOTLDR partitions that belong to the entry token but are not referenced in any boot loader entries. # Boot Loader Interface Commands These commands are available for all boot loaders that implement the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) and the [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE), such as `systemd-boot`. `set-preferred` \; `set-default` \; `set-oneshot` \; `set-sysfail` \ Sets the default boot loader entry. Takes a single boot loader entry ID string or a glob pattern as argument. The `set-oneshot` command will set the default entry only for the next boot, `set-default` will set it persistently for all future boots, `set-preferred` is like `set-default`, but is aware of boot assessment and will skip boot entries that have their tries-left counter set to zero. The `set-sysfail` command will set the boot loader entry to be used in case of a system failure. System failure (SysFail) boot entries can optionally modify the automatic selection order in the event of a failure, such as a boot firmware update failure with the failure status recorded in the EFI system table. `bootctl list` can be used to list available boot loader entries and their IDs. In addition, the boot loader entry ID may be specified as one of: `@default`, `@oneshot` or `@current`, which correspond to the current default boot loader entry for all future boots, the current default boot loader entry for the next boot, and the currently booted boot loader entry. These special IDs are resolved to the current values of the EFI variables `LoaderEntryDefault`, `LoaderEntrySysFail`, `LoaderEntryOneShot` and `LoaderEntrySelected`, see [ UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) for details. These special IDs are primarily useful as a quick way to persistently make the currently booted boot loader entry the default choice, or to upgrade the default boot loader entry for the next boot to the default boot loader entry for all future boots, but may be used for other operations too. If set to `@saved` the chosen entry will be saved as an EFI variable on every boot and automatically selected the next time the boot loader starts. When an empty string ("") is specified as the ID, then the corresponding EFI variable will be unset. Hint: use `systemctl reboot --boot-loader-entry=ID` to reboot into a specific boot entry and `systemctl reboot --boot-loader-menu=timeout` to reboot into the boot loader menu once. See `systemctl(1)` for details. `set-timeout` \; `set-timeout-oneshot` \ Sets the boot loader menu timeout in seconds. The `set-timeout-oneshot` command will set the timeout only for the next boot. See `systemd.time(7)` for details about the syntax of time spans. If this is set to `menu-disabled` or `menu-hidden` or `0`, no menu is shown and the default entry will be booted immediately, while setting this to `menu-force` disables the timeout while always showing the menu. When an empty string ("") is specified the bootloader will revert to its default menu timeout. # `systemd-boot` Commands These commands manage the `systemd-boot` EFI boot loader, and do not work in conjunction with other boot loaders. `install` Installs `systemd-boot` into the EFI system partition. A copy of `systemd-boot` will be stored as the EFI default/fallback loader at `ESP/EFI/BOOT/BOOT*.EFI`. The boot loader is then added to the top of the firmware's boot loader list. `update` Updates all installed versions of `systemd-boot(7)`, if the available version is newer than the version installed in the EFI system partition. This also includes the EFI default/fallback loader at `ESP/EFI/BOOT/BOOT*.EFI`. The boot loader is then added to end of the firmware's boot loader list if missing. `remove` Removes all installed versions of `systemd-boot` from the EFI system partition and the firmware's boot loader list. `is-installed` Checks whether `systemd-boot` is installed in the ESP. Note that a single ESP might host multiple boot loaders; this hence checks whether `systemd-boot` is one (of possibly many) installed boot loaders — and neither whether it is the default nor whether it is registered in any EFI variables. `random-seed` Generates a random seed and stores it in the EFI System Partition (ESP), for use by the `systemd-boot` boot loader. If a random seed already exists in the ESP it is refreshed. Also generates a random 'system token' and stores it persistently as an EFI variable, if one has not been set before. If the boot loader finds the random seed in the ESP and the system token in the EFI variable it will derive a random seed to pass to the OS and a new seed to store in the ESP from the combination of both. The random seed passed to the OS is credited to the kernel's entropy pool by the system manager during early boot, and permits userspace to boot up with an entropy pool fully initialized very early on. Also see `systemd-boot-random-seed.service(8)`. See [Random Seeds](https://systemd.io/RANDOM_SEEDS) for further information. # Kernel Image Commands `kernel-identify` \ Takes a kernel image as argument. Checks what kind of kernel the image is. Returns one of `uki`, `addon`, `pe`, and `unknown`. `kernel-inspect` \ Takes a kernel image as argument. Prints details about the image. # Options The following options are understood: `--root=root` Takes a directory path as an argument. All paths will be prefixed with the given alternate \ path, including config search paths. `--image=image` Takes a path to a disk image file or block device node. If specified, all operations are applied to file system in the indicated disk image. This option is similar to `--root=`, but operates on file systems stored in disk images or block devices. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). For further information on supported disk images, see `systemd-nspawn(1)`'s switch of the same name. `--install-source=` When installing binaries with `--root=` or `--image=`, selects where to source them from. Takes one of `auto` (the default), `image` or `host`. With `auto` binaries will be picked from the specified directory or image, and if not found they will be picked from the host. With `image` or `host` no fallback search will be performed if the binaries are not found in the selected source. `-p`; `--print-esp-path` This option modifies the behaviour of `status`. Only prints the path to the EFI System Partition (ESP) to standard output and exits. `-x`; `--print-boot-path` This option modifies the behaviour of `status`. Only prints the path to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard output and exit. This command is useful to determine where to place boot loader entries, as they are preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise. Boot Loader Specification Type \#1 entries should generally be placed in the directory `$(bootctl -x)/loader/entries/`. Existence of that directory may also be used as indication that boot loader entry support is available on the system. Similarly, Boot Loader Specification Type \#2 entries should be placed in the directory `$(bootctl -x)/EFI/Linux/`. Note that this option (similarly to the `--print-esp-path` option mentioned above), is available independently from the boot loader used, i.e. also without `systemd-boot` being installed. `--print-loader-path` This option modifies the behaviour of `status`: it shows the absolute path to the boot loader EFI binary used for the current boot if this information is available. Note that no attempt is made to verify whether the binary still exists. `--print-stub-path` This option modifies the behaviour of `status`: it shows the absolute path to the UKI/stub EFI binary used for the current boot if this information is available. Note that no attempt is made to verify whether the binary still exists. `-R`; `--print-root-device` Print the path to the block device node backing the root file system of the local OS. This prints a path such as `/dev/nvme0n1p5`. If the root file system is backed by dm-crypt/LUKS or dm-verity the underlying block device is returned. If the root file system is backed by multiple block devices (as supported by btrfs) the operation will fail. If the switch is specified twice (i.e. `-RR`) and the discovered block device is a partition device the "whole" block device it belongs to is determined and printed (e.g. `/dev/nvme0n1`). If the root file system is `tmpfs` (or a similar in-memory file system), the block device backing `/usr/` is returned if applicable. If the root file system is a network file system (e.g. NFS, CIFS) the operation will fail. `--print-efi-architecture` Print the EFI architecture string of the local firmware. This is useful to generically format filenames such as `bootx64.efi` that include the local firmware architecture in the name. `--variables=yes|no|auto` Controls whether to touch the firmware's boot loader list stored in EFI variables, and other EFI variables. If not specified or set to `auto`, EFI variables will not be modified when execution in a container runtime is detected. `yes` may be used to explicit override the check. `--random-seed=yes|no` By default, the `install` command initializes a random seed file in the ESP. When creating an image it may be desirable to disable that in order to avoid having the same seed in all instances. `--graceful` Ignore failure when the EFI System Partition cannot be found, when EFI variables cannot be written, or a different or newer boot loader is already installed. Currently only applies to `is-installed`, `update`, `random-seed` and `install` verbs. Since version v258, it is implicitly enabled when running inside a chroot. `-q`; `--quiet` Suppress printing of the results of various commands and also the hints about ESP being unavailable. `--make-entry-directory=yes|no` Controls creation and deletion of the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#1 entry directory on the file system containing resources such as kernel and initrd images during `install` and `remove`, respectively. The directory is named after the entry token, as specified with `--entry-token=` parameter described below, and is placed immediately below the `$BOOT` root directory (i.e. beneath the file system returned by the `--print-boot-path` option, see above). Defaults to `no`. `--entry-token=` Controls how to name and identify boot loader entries for this OS installation. Accepted during `install`, and takes one of `auto`, `machine-id`, `os-id`, `os-image-id` or an arbitrary string prefixed by `literal:` as argument. If set to `machine-id` the entries are named after the machine ID of the running system (e.g. `b0e793a9baf14b5fa13ecbe84ff637ac`). See `machine-id(5)` for details about the machine ID concept and file. If set to `os-id` the entries are named after the OS ID of the running system, i.e. the `ID=` field of `os-release(5)` (e.g. `fedora`). Similarly, if set to `os-image-id` the entries are named after the OS image ID of the running system, i.e. the `IMAGE_ID=` field of `os-release` (e.g. `vendorx-cashier-system`). If set to `auto` (the default), the `/etc/kernel/entry-token` file will be read if it exists, and the stored value used. Otherwise, if the local machine ID is initialized it is used. Otherwise, `IMAGE_ID=` from `os-release` will be used, if set. Otherwise, `ID=` from `os-release` will be used, if set. Unless set to `machine-id`, or when `--make-entry-directory=yes` is used the selected token string is written to a file `/etc/kernel/entry-token`, to ensure it will be used for future entries. This file is also read by `kernel-install(8)`, in order to identify under which name to generate boot loader entries for newly installed kernels, or to determine the entry names for removing old ones. Using the machine ID for naming the entries is generally preferable, however there are cases where using the other identifiers is a good option. Specifically: if the identification data that the machine ID entails shall not be stored on the (unencrypted) `$BOOT` partition, or if the ID shall be generated on first boot and is not known when the entries are prepared. Note that using the machine ID has the benefit that multiple parallel installations of the same OS can coexist on the same medium, and they can update their boot loader entries independently. When using another identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to use the same entry name. To support parallel installations, the installer must use a different entry token when adding a second installation. `--all-architectures` Install binaries for all supported EFI architectures (this implies `--variables=no`). `--efi-boot-option-description=` Description of the entry added to the firmware's boot option list. Defaults to `Linux Boot Manager`. Using the default entry name `Linux Boot Manager` is generally preferable as only one bootloader installed to a single ESP partition should be used to boot any number of OS installations found on the various disks installed in the system. Specifically distributions should not use this flag to install a branded entry in the boot option list. However, in situations with multiple disks, each with their own ESP partition, it can be beneficial to make it easier to identify the bootloader being used in the firmware's boot option menu. `--efi-boot-option-description-with-device=` Takes a boolean, defaults to false. Controls whether to append disk model information to the firmware boot option item description (as configured with `--efi-boot-option-description=` above). This is useful when installing multiple operating systems on separate disks on the same system, as it ensures the firmware boot options are discernible and give a hint which disk is booted into. Note that this uses hardware model information, and hence might not be too useful in case multiple disks of an identical model are used. `-n`; `--dry-run` Dry run for `unlink` and `cleanup`. In dry run mode, the unlink and cleanup operations only print the files that would get deleted without actually deleting them. The short option `-n` was added in version 262. `--oldest` When used with `unlink`, selects the oldest installed boot loader entry matching the boot entry token for removal (rather than passing an explicit entry ID). This is useful for pruning older installed boot loader entries. Note that the currently booted entry is never removed, nor is the last remaining one. `--keep-free=BYTES` When used with `link`, controls the minimum amount of free space (in bytes) that must remain on the target partition (ESP or XBOOTLDR) after the new entry has been materialized. The operation fails if installing the entry would drop the free space below this threshold. Accepts the usual size suffixes (K, M, G, …). If empty, the built-in default is restored. If set to zero no minimum amount of free space is kept. `--entry-title=TITLE` When used with `link`, specifies the title of the generated boot loader entry (the `title` field of the Type \#1 entry). If not specified, a title is derived from the UKI's embedded metadata. `--entry-version=VERSION` When used with `link`, specifies the version string of the generated boot loader entry (the `version` field of the Type \#1 entry). If not specified, the version is derived from the UKI's embedded metadata. Used by the boot loader to sort and select entries. `--entry-commit=NR` When used with `link`, specifies the commit number for the generated boot loader entry. `--extra=PATH`; `-X PATH` When used with `link`, registers an additional sidecar resource file that shall be passed to the UKI at boot. This may be a system extension image (`*.sysext.raw`), configuration extension image (`*.confext.raw`), or credential file (`*.cred`). The file is copied into the ESP/XBOOTLDR alongside the UKI and the boot loader will load and pass it to the kernel via initrd. This option may be used multiple times to register more than one extra resource. If passed an empty argument, all previously specified extras are cleared. `--tries-left=NR` When used with `link`, initializes the boot counting `tries-left` counter for the generated entry. If set, the resulting boot entry file is named according to the boot counting scheme described in the [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT) documentation, so that the boot loader decreases the counter on each attempted boot and eventually marks the entry as bad. If not specified, boot counting is not enabled for the generated entry. `--secure-boot-auto-enroll=yes|no`; `--private-key=PATH/URI`; `--private-key-source=TYPE[:NAME]`; `--certificate=PATH`; `--certificate-source=TYPE[:NAME]` Configure the ESP for secure boot auto-enrollment when invoking the `install` command. Takes a boolean argument. Disabled by default. Enabling this option will make `bootctl` populate the ESP with signed `PK`, `KEK` and `db` signature databases, each containing the given certificate in `DER` format as their only entry. These secure boot signature databases will be picked up and enrolled by `systemd-boot` if secure boot is in setup mode and secure boot auto-enrollment is enabled. When specifying this option, a certificate and private key have to be provided as well using the `--certificate=` and `--private-key=` options. The `--certificate=` option takes a path to a PEM encoded X.509 certificate or a URI that's passed to the OpenSSL provider configured with `--certificate-source` which takes one of `file` or `provider`, with the latter being followed by a specific provider identifier, separated with a colon, e.g. `provider:pkcs11`. The `--private-key=` option can take a path or a URI that will be passed to the OpenSSL engine or provider, as specified by `--private-key-source=` as a `type:name` tuple, such as `engine:pkcs11`. The specified OpenSSL signing engine or provider will be used to sign the EFI signature lists. # Signed .efi files `bootctl` `install` and `update` will look for a `systemd-boot` file ending with the `.efi.signed` suffix first, and copy that instead of the normal `.efi` file. This allows distributions or end-users to provide signed images for UEFI SecureBoot. # Exit status On success, 0 is returned, a non-zero failure code otherwise. `bootctl --print-root-device` returns exit status 80 in case the root file system is not backed by single block device, and other non-zero exit statuses on other errors. # Environment If `$SYSTEMD_RELAX_ESP_CHECKS=1` is set the validation checks for the ESP are relaxed, and the path specified with `--esp-path=` may refer to any kind of file system on any kind of partition. Similarly, `$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1` turns off some validation checks for the Extended Boot Loader partition. # Examples
Output from `status` and `list`
$ bootctl status System: Firmware: UEFI 2.40 (firmware-version) ← firmware vendor and version Secure Boot: disabled (setup) ← Secure Boot status TPM2 Support: yes Boot into FW: supported ← does the firmware support booting into itself Current Boot Loader: ← details about systemd-boot or another boot loader Product: systemd-boot version implementing the Boot Loader Interface Features: ✓ Boot counting ✓ Menu timeout control ✓ One-shot menu timeout control ✓ Default entry control ✓ One-shot entry control ✓ Support for XBOOTLDR partition ✓ Support for passing random seed to OS ✓ Load drop-in drivers ✓ Boot loader sets ESP information ✓ Menu can be disabled ESP: /dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000 File: └─/EFI/systemd/systemd-bootx64.efi Random Seed: ← random seed used for entropy in early boot Passed to OS: yes System Token: set Exists: yes Available Boot Loaders on ESP: ESP: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000) File: └─/EFI/systemd/systemd-bootx64.efi (systemd-boot 251 File: └─/EFI/BOOT/BOOTX64.EFI (systemd-boot 251 Boot Loaders Listed in EFI Variables: Title: Linux Boot Manager ID: 0x0001 Status: active, boot-order Partition: /dev/disk/by-partuuid/… File: └─/EFI/systemd/systemd-bootx64.efi Title: Fedora ID: 0x0000 Status: active, boot-order Partition: /dev/disk/by-partuuid/… File: └─/EFI/fedora/shimx64.efi Title: Linux-Firmware-Updater ID: 0x0002 Status: active, boot-order Partition: /dev/disk/by-partuuid/… File: └─/EFI/fedora/fwupdx64.efi Boot Loader Entries: $BOOT: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000) Default Boot Loader Entry: type: Boot Loader Specification Type #1 (.conf) title: Fedora Linux 36 (Workstation Edition) id: … source: /boot/efi/loader/entries/entry-token-kernel-version.conf version: kernel-version machine-id: … linux: /entry-token/kernel-version/linux initrd: /entry-token/kernel-version/initrd options: root=… $ bootctl list Boot Loader Entries: type: Boot Loader Specification Type #1 (.conf) title: Fedora Linux 36 (Workstation Edition) (default) (selected) id: … source: /boot/efi/loader/entries/entry-token-kernel-version.conf version: kernel-version machine-id: … linux: /entry-token/kernel-version/linux initrd: /entry-token/kernel-version/initrd options: root=… type: Boot Loader Specification Type #2 (.efi) title: Fedora Linux 35 (Workstation Edition) id: … source: /boot/efi/EFI/Linux/fedora-kernel-version.efi version: kernel-version machine-id: … linux: /EFI/Linux/fedora-kernel-version.efi options: root=… type: Automatic title: Reboot Into Firmware Interface id: auto-reboot-to-firmware-setup source: /sys/firmware/efi/efivars/LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f In the listing, `(default)` specifies the entry that will be used by default, and `(selected)` specifies the entry that was selected the last time (i.e. is currently running).
# Files `/etc/systemd/uki/`; `/run/systemd/uki/`; `/var/lib/systemd/uki/`; `/usr/local/lib/systemd/uki/`; `/usr/lib/systemd/uki/` The `link-auto` command discovers the UKI to install from these directories (listed in decreasing order of priority). It uses `kernel.efi` or the versioned `kernel.efi.v/` directory from the highest-priority directory that contains one. Additional sidecar resources (system extension images, configuration extension images, credential files) are picked up from the `extras.d/` subdirectory of each, combined across all directories. `/var/lib/systemd/uki/` is the directory where `systemd-sysupdate(8)` is supposed to place downloaded kernels, system extensions, configuration extensions and credentials. # See Also `systemd-boot(7)`, [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification), [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE), `systemd-boot-random-seed.service(8)` # bootup systemd bootup 7 bootup System bootup process # Description A number of different components are involved in the boot of a Linux system. Immediately after power-up, the system firmware will do minimal hardware initialization, and hand control over to a boot loader (e.g. `systemd-boot(7)` or [GRUB](https://www.gnu.org/software/grub/)) stored on a persistent storage device. This boot loader will then invoke an OS kernel from disk (or the network). On systems using EFI or other types of firmware, this firmware may also load the kernel directly. The kernel (optionally) mounts an in-memory file system, which looks for the root file system. Nowadays this is implemented as an "initramfs" — a compressed CPIO archive that the kernel extracts into a tmpfs. In the past normal file systems using an in-memory block device (ramdisk) were used, and the name "initrd" is still used to describe both concepts. It's the boot loader or the firmware that loads both the kernel and initrd/initramfs images into memory, but the kernel which interprets it as a file system. `systemd(1)` may be used to manage services in the initrd, similarly to the real system. After the root file system is found and mounted, the initrd hands over control to the host's system manager (such as `systemd(1)`) stored in the root file system, which is then responsible for probing all remaining hardware, mounting all necessary file systems and spawning all configured services. On shutdown, the system manager stops all services, unmounts all non-busy file systems (detaching the storage technologies backing them), and then (optionally) jumps into the exitrd. The exitrd is backed by tmpfs and unmounts/detaches the remaining file systems, including the real root. As a last step, the system is powered down. Additional information about the system boot process may be found in `boot(7)`. # System Manager Bootup At boot, the system manager on the OS image is responsible for initializing the required file systems, services and drivers that are necessary for operation of the system. On `systemd(1)` systems, this process is split up in various discrete steps which are exposed as target units. (See `systemd.target(5)` for detailed information about target units.) The boot-up process is highly parallelized so that the order in which specific target units are reached is not deterministic, but still adheres to a limited amount of ordering structure. When systemd starts up the system, it will activate all units that are dependencies of `default.target` (as well as recursively all dependencies of these dependencies). Usually, `default.target` is simply an alias of `graphical.target` or `multi-user.target`, depending on whether the system is configured for a graphical UI or only for a text console. To enforce minimal ordering between the units pulled in, a number of well-known target units are available, as listed on `systemd.special(7)`. The following chart is a structural overview of these well-known units and their position in the boot-up logic. The arrows describe which units are pulled in and ordered before which other units. Units near the top are started before units nearer to the bottom of the chart. cryptsetup-pre.target veritysetup-pre.target | (various low-level v API VFS mounts: (various cryptsetup/veritysetup devices...) mqueue, configfs, | | debugfs, ...) v | | cryptsetup.target | | (various swap | | remote-fs-pre.target | devices...) | | | | | | | | | v | v local-fs-pre.target | | | (network file systems) | swap.target | | v v | | | v | remote-cryptsetup.target | | | (various low-level (various mounts and | remote-veritysetup.target | | | services: udevd, fsck services...) | | | | | tmpfiles, random | | | remote-fs.target | | seed, sysctl, ...) v | | | | | | local-fs.target | | _____________/ | | | | | |/ \____|______|_______________ ______|___________/ | \ / | v | sysinit.target | | | ______________________/|\_____________________ | / | | | \ | | | | | | | v v | v | | (various (various | (various | | timers...) paths...) | sockets...) | | | | | | | | v v | v | | timers.target paths.target | sockets.target | | | | | | v | v \_______ | _____/ rescue.service | \|/ | | v v | basic.target rescue.target | | | ________v____________________ | / | \ | | | | | v v v | display- (various system (various system | manager.service services services) | | required for | | | graphical UIs) v v | | multi-user.target emergency.service | | | | \_____________ | _____________/ v \|/ emergency.target v graphical.target Target units that are commonly used as boot targets are *emphasized*. These units are good choices as goal targets, for example by passing them to the `systemd.unit=` kernel command line option (see `systemd(1)`) or by symlinking `default.target` to them. `timers.target` is pulled-in by `basic.target` asynchronously. This allows timers units to depend on services which become only available later in boot. # User manager startup The system manager starts the `user@uid.service` unit for each user, which launches a separate unprivileged instance of `systemd` for each user — the user manager. Similarly to the system manager, the user manager starts units which are pulled in by `default.target`. The following chart is a structural overview of the well-known user units. For non-graphical sessions, `default.target` is used. Whenever the user logs into a graphical session, the login manager will start the `graphical-session.target` target that is used to pull in units required for the graphical session. A number of targets (shown on the right side) are started when specific hardware is available to the user. (various (various (various timers...) paths...) sockets...) (sound devices) | | | | v v v v timers.target paths.target sockets.target sound.target | | | \______________ _|_________________/ (bluetooth devices) \ / | V v basic.target bluetooth.target | __________/ \_______ (smartcard devices) / \ | | | v | v smartcard.target v graphical-session-pre.target (various user services) | (printers) | v | | (services for the graphical session) v | | printer.target v v default.target graphical-session.target # Bootup in the initrd Systemd can be used in the initrd as well. It detects the initrd environment by checking for the `/etc/initrd-release` file. The default target in the initrd is `initrd.target`. The bootup process is identical to the system manager bootup until the target `basic.target`. After that, systemd executes the special target `initrd.target`. Before any file systems are mounted, the manager will determine whether the system shall resume from hibernation or proceed with normal boot. This is accomplished by `systemd-hibernate-resume.service` which must be finished before `local-fs-pre.target`, so no filesystems can be mounted before the check is complete. When the root device becomes available, `initrd-root-device.target` is reached. If the root device can be mounted at `/sysroot`, the `sysroot.mount` unit becomes active and `initrd-root-fs.target` is reached. The service `initrd-parse-etc.service` scans `/sysroot/etc/fstab` for a possible `/usr/` mount point and additional entries marked with the *x-initrd.mount* option. All entries found are mounted below `/sysroot`, and `initrd-fs.target` is reached. The service `initrd-cleanup.service` isolates to the `initrd-switch-root.target`, where cleanup services can run. As the very last step, the `initrd-switch-root.service` is activated, which will cause the system to switch its root to `/sysroot`. : (beginning identical to above) : v basic.target | emergency.service ______________________/| | / | v | initrd-root-device.target emergency.target | | | v | sysroot.mount | | | v | initrd-root-fs.target | | | v v initrd-parse-etc.service (custom initrd | services...) v | (sysroot-usr.mount and | various mounts marked | with fstab option | x-initrd.mount...) | | | v | initrd-fs.target \______________________ | \| v initrd.target | v initrd-cleanup.service isolates to initrd-switch-root.target | v ______________________/| / v | initrd-udevadm-cleanup-db.service v | (custom initrd | services...) | \______________________ | \| v initrd-switch-root.target | v initrd-switch-root.service | v Transition to Host OS # System Manager Shutdown System shutdown with systemd also consists of various target units with some minimal ordering structure applied: (conflicts with (conflicts with all system all file system services) mounts, swaps, | cryptsetup/ | veritysetup | devices, ...) | | v v shutdown.target umount.target | | \_______ ______/ \ / v (various low-level services) | v final.target | ___________________________/ \_________________________________ / | | | \ | | | | | v | | | | systemd-reboot.service | | | | | v | | | | systemd-poweroff.service | | | v | v | | reboot.target | systemd-halt.service | | v | v | poweroff.target | systemd-kexec.service | v | | halt.target | systemd-soft-reboot.service v | kexec.target | v soft-reboot.target Commonly used system shutdown targets are *emphasized*. Note that `systemd-halt.service(8)`, `systemd-reboot.service`, `systemd-poweroff.service` and `systemd-kexec.service` will transition the system and server manager (PID 1) into the second phase of system shutdown (implemented in the `systemd-shutdown` binary), which will unmount any remaining file systems, kill any remaining processes and release any other remaining resources, in a simple and robust fashion, without taking any service or unit concept into account anymore. At that point, regular applications and resources are generally terminated and released already, the second phase hence operates only as safety net for everything that could not be stopped or released for some reason during the primary, unit-based shutdown phase described above. # The exitrd The "exitrd" is a concept symmetrical to the initrd. When the system manager is shutting down and `/run/initramfs/shutdown` exists, it will switch root to `/run/initramfs/` and execute `/shutdown`. This program runs from the tmpfs mounted on `/run/`, so it can unmount the old root file system and perform additional steps, for example dismantle complex storage or perform additional logging about the shutdown. # See Also `systemd(1)`, `boot(7)`, `systemd.special(7)`, `systemd.target(5)`, `systemd-halt.service(8)`, `systemd-soft-reboot.service(8)` # busctl systemd busctl 1 busctl Introspect the bus busctl OPTIONS COMMAND NAME # Description `busctl` may be used to introspect and monitor the D-Bus bus. # Commands The following commands are understood: `list` Show all peers on the bus, by their service names. By default, shows both unique and well-known names, but this may be changed with the `--unique` and `--acquired` switches. This is the default operation if no command is specified. `status` \ Show process information and credentials of a bus service (if one is specified by its unique or well-known name), a process (if one is specified by its numeric PID), or the owner of the bus (if no parameter is specified). `monitor` \ Dump messages being exchanged. If \ is specified, show messages to or from this peer, identified by its well-known or unique name. Otherwise, show all messages on the bus. Use Ctrl+C to terminate the dump or limit it with the `--limit-messages=` option. `capture` \ Similar to `monitor` but writes the output in pcapng format (for details, see [ PCAP Next Generation (pcapng) Capture File Format](https://github.com/pcapng/pcapng/)). Make sure to redirect standard output to a file or pipe. Tools like `wireshark(1)` may be used to dissect and view the resulting files. `tree` \ Shows an object tree of one or more services. If \ is specified, show object tree of the specified services only. Otherwise, show all object trees of all services on the bus that acquired at least one well-known name. `introspect` \ \ \ Show interfaces, methods, properties and signals of the specified object (identified by its path) on the specified service. If the interface argument is passed, the output is limited to members of the specified interface. `call` \ \ \ \ \ \ Invoke a method and show the response. Takes a service name, object path, interface name and method name. If parameters shall be passed to the method call, a signature string is required, followed by the arguments, individually formatted as strings. For details on the formatting used, see below. To suppress output of the returned data, use the `--quiet` option. `emit` \ \ \ \ \ Emit a signal. Takes an object path, interface name and method name. If parameters shall be passed, a signature string is required, followed by the arguments, individually formatted as strings. For details on the formatting used, see below. To specify the destination of the signal, use the `--destination=` option. `wait` \ \ \ \ Wait for a signal. Takes an object path, interface name, and signal name. Use the `--limit-messages=` option to wait for more than just one signal before exiting. To suppress output of the returned data, use the `--quiet` option. The service name may be omitted, in which case `busctl` will match signals from any sender. `get-property` \ \ \ \ Retrieve the current value of one or more object properties. Takes a service name, object path, interface name and property name. Multiple properties may be specified at once, in which case their values will be shown one after the other, separated by newlines. The output is, by default, in terse format. Use `--verbose` for a more elaborate output format. `set-property` \ \ \ \ \ \ Set the current value of an object property. Takes a service name, object path, interface name, property name, property signature, followed by a list of parameters formatted as strings. `help` Show command syntax help. # Options The following options are understood: `--address=ADDRESS` Connect to the bus specified by \ instead of using suitable defaults for either the system or user bus (see `--system` and `--user` options). `--show-machine` When showing the list of peers, show a column containing the names of containers they belong to. See `systemd-machined.service(8)`. `--unique` When showing the list of peers, show only "unique" names (of the form `:number.number`). `--acquired` The opposite of `--unique` — only "well-known" names will be shown. `--activatable` When showing the list of peers, show only peers which have actually not been activated yet, but may be started automatically if accessed. `--match=MATCH` When showing messages being exchanged, show only the subset matching \. See `sd_bus_add_match(3)`. `--size=` When used with the `capture` command, specifies the maximum bus message size to capture ("snaplen"). Defaults to 4096 bytes. `--list` When used with the `tree` command, shows a flat list of object paths instead of a tree. `-q`; `--quiet` When used with the `call` command, suppresses display of the response message payload. Note that even if this option is specified, errors returned will still be printed and the tool will indicate success or failure with the process exit code. `--verbose` When used with the `call` or `get-property` command, shows output in a more verbose format. `--xml-interface` When used with the `introspect` call, dump the XML description received from the D-Bus `org.freedesktop.DBus.Introspectable.Introspect` call instead of the normal output. `--expect-reply=BOOL` When used with the `call` command, specifies whether `busctl` shall wait for completion of the method call, output the returned method response data, and return success or failure via the process exit code. If this is set to `no`, the method call will be issued but no response is expected, the tool terminates immediately, and thus no response can be shown, and no success or failure is returned via the exit code. To only suppress output of the reply message payload, use `--quiet` above. Defaults to `yes`. `--auto-start=BOOL` When used with the `call` or `emit` command, specifies whether the method call should implicitly activate the called service, should it not be running yet but is configured to be auto-started. Defaults to `yes`. `--allow-interactive-authorization=BOOL` When used with the `call` command, specifies whether the services may enforce interactive authorization while executing the operation, if the security policy is configured for this. Defaults to `yes`. `--timeout=SECS` When used with the `call` command, specifies the maximum time to wait for method call completion. When used with the `monitor` command, since version v257, specifies the maximum time to wait for messages before automatically exiting. If no time unit is specified, assumes seconds. The usual other units are understood, too (ms, us, s, min, h, d, w, month, y). Note that this timeout does not apply if `--expect-reply=no` is used, when combined with the `call` command, as the tool does not wait for any reply message then. When not specified or when set to 0, the default of `25s` is assumed for the `call` command, and it is disabled for the `monitor` command. `--limit-messages=NUMBER`; `-N NUMBER` When used with the `monitor` command, if enabled will make `busctl` exit when the specified number of messages have been received and printed. This is useful in combination with `--match=`, to wait for the specified number of occurrences of specific D-Bus messages. While if not specified or is set to special value `infinity`, the default is to keep monitoring without limitations. When used with the `wait` command, it will make `busctl` exit when the specified number of DBus signals have been received and printed. Setting it to special value `infinity` will sustain `busctl` to receive and print signals continuously without limitations. When nothing is specified, the default is to exit immediately after receiving and printing the first signal. `--augment-creds=BOOL` Controls whether credential data reported by `list` or `status` shall be augmented with data from `/proc/`. When this is turned on, the data shown is possibly inconsistent, as the data read from `/proc/` might be more recent than the rest of the credential information. Defaults to `yes`. `--watch-bind=BOOL` Controls whether to wait for the specified `AF_UNIX` bus socket to appear in the file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until the socket is created and then connect to it. `--destination=SERVICE` Takes a service name. When used with the `emit` command, a signal is emitted to the specified service. `-l`; `--full` Do not ellipsize the output in `list` command. # Parameter Formatting The `call` and `set-property` commands take a signature string followed by a list of parameters formatted as string (for details on D-Bus signature strings, see the [Type system chapter of the D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system)). For simple types, each parameter following the signature should simply be the parameter's value formatted as string. Positive boolean values may be formatted as `true`, `yes`, `on`, or `1`; negative boolean values may be specified as `false`, `no`, `off`, or `0`. For arrays, a numeric argument for the number of entries followed by the entries shall be specified. For variants, the signature of the contents shall be specified, followed by the contents. For dictionaries and structs, the contents of them shall be directly specified. For example, s jawoll is the formatting of a single string `jawoll`. as 3 hello world foobar is the formatting of a string array with three entries, `hello`, `world` and `foobar`. a{sv} 3 One s Eins Two u 2 Yes b true is the formatting of a dictionary array that maps strings to variants, consisting of three entries. The string `One` is assigned the string `Eins`. The string `Two` is assigned the 32-bit unsigned integer 2. The string `Yes` is assigned a positive boolean. Note that the `call`, `get-property`, `introspect` commands will also generate output in this format for the returned data. Since this format is sometimes too terse to be easily understood, the `call` and `get-property` commands may generate a more verbose, multi-line output when passed the `--verbose` option. # Examples
Write and Read a Property
The following two commands first write a property and then read it back. The property is found on the `/org/freedesktop/systemd1` object of the `org.freedesktop.systemd1` service. The name of the property is `LogLevel` on the `org.freedesktop.systemd1.Manager` interface. The property contains a single string: # busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s "debug"
Terse and Verbose Output
The following two commands read a property that contains an array of strings, and first show it in terse format, followed by verbose format: $ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin" $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment ARRAY "s" { STRING "LANG=en_US.UTF-8"; STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"; };
Invoking a Method
The following command invokes the `StartUnit` method on the `org.freedesktop.systemd1.Manager` interface of the `/org/freedesktop/systemd1` object of the `org.freedesktop.systemd1` service, and passes it two strings `cups.service` and `replace`. As a result of the method call, a single object path parameter is received and shown: # busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace" o "/org/freedesktop/systemd1/job/42684"
# See Also `dbus-daemon(1)`, [D-Bus](https://www.freedesktop.org/wiki/Software/dbus), `sd-bus(3)`, `varlinkctl(1)`, `systemd(1)`, `machinectl(1)`, `wireshark(1)` # capsule@.service systemd capsule@.service 5 capsule@.service System unit for the capsule service manager `capsule@NAME.service` # Description Service managers for capsules run in `capsule@NAME.service` system units, with the capsule name as the instance identifier. Capsules are way to run additional instances of the service manager, under dynamic user IDs, i.e. UIDs that are allocated when the capsule service manager is started, and released when it is stopped. In many ways `capsule@.service` is similar to the per-user `user@.service` service manager, but there are a few important distinctions: - The capsule service manager utilizes `DynamicUser=` (see `systemd.exec(5)`) to allocate a new UID dynamically on invocation. The user name is automatically generated from the capsule name, by prefixing `c-`. The UID is released when the service is terminated. The user service manager on the other hand operates under a statically allocated user ID that must be pre-existing, before the user service manager is invoked. - User service managers register themselves with `pam(8)`, capsule service managers do not. - User service managers typically read their configuration from a `$HOME` directory below `/home/`, capsule service managers from a `$HOME` directory below `/var/lib/capsules/`. - User service managers are collectively contained in the `user.slice` unit, capsule service managers in `capsule.slice`. Also see `systemd.special(7)`. - User service managers start the user unit `default.target` initially. Capsule service managers invoke the user unit `capsule@.target` instead. The capsule service manager and the capsule's bus broker can be reached via the `--capsule=` switch to `systemctl(1)`, `systemd-run(1)` and `busctl(1)`. New capsules can be started via a simple `systemctl start capsule@NAME.service` command, and stopped via `systemctl stop capsule@NAME.service`. Starting a capsule will implicitly create a home directory `/var/lib/capsules/NAME/`, if missing. A runtime directory is created as `/run/capsules/NAME/`. To remove these resources use `systemctl clean capsule@NAME.service`, for example with the `--what=all` switch. The `capsule@.service` unit invokes a `systemd --user` service manager process. This means unit files are looked for according to the same rules as for regular user service managers, for example in `/var/lib/capsules/NAME/.config/systemd/user/`. Capsule names may be chosen freely by the user, however, they must be suitable as UNIX filenames (i.e. 255 characters max, and contain no `/`), and when prefixed with `c-` be suitable as a user name matching strict POSIX rules, see [User/Group Name Syntax](https://systemd.io/USER_NAMES) for details. # Examples
Create a new capsule, invoke two programs in it (one interactively), terminate it, and clean everything up
# systemctl start capsule@tatze.service # systemd-run --capsule=tatze --unit=sleeptest.service sleep 999 # systemctl --capsule=tatze status sleeptest.service # systemd-run -t --capsule=tatze bash # systemctl --capsule=tatze stop sleeptest.service # systemctl stop capsule@tatze.service # systemctl clean --all capsule@tatze.service
# See Also `systemd(1)`, `user@.service(5)`, `systemd.service(5)`, `systemd.slice(5)`, `systemd.exec(5)`, `systemd.special(7)`, `systemctl(1)`, `systemd-run(1)`, `busctl(1)`, `pam(8)` # cgroup-sandboxing # This option cannot be bypassed by prefixing `+` to the executable path in the service unit, as it applies to the whole control group. These options cannot be bypassed by prefixing `+` to the executable path in the service unit, as they apply to the whole control group. # clonetab systemd clonetab 5 clonetab Configuration for dm-clone block devices `/etc/clonetab` # Description The `/etc/clonetab` file describes dm-clone block devices that are set up during system boot. Empty lines and lines starting with the `#` character are ignored. Each of the remaining lines describes one dm-clone device. Fields are delimited by white space. Each line is in the form name source-device destination-device metadata-device [options] The first four fields are mandatory, the fifth is optional. The five fields of `/etc/clonetab` are defined as follows: 1. The first field contains the name of the resulting dm-clone device; its block device is set up below `/dev/mapper/`. 2. The second field contains a path to the read-only source block device. This is the device whose data is cloned to the destination device. Reads to regions not yet hydrated are served directly from this device. 3. The third field contains a path to the writable destination block device. The source device's data is copied here in the background. It must be at least as large as the source device. 4. The fourth field contains a path to the metadata block device. This small device tracks which regions of the destination have been hydrated and is managed exclusively by dm-clone. 5. The fifth field, if present, contains comma-separated `key=value` options. The following option is supported: `region-size=BYTES` Controls the granularity of background hydration copying — how much data is copied at a time. Region size is specified in bytes (standard suffixes like `K`, `M`, `G` are supported), and must correspond to a power of two between 4 KiB and 1 GiB. For example, `region-size=4K` or `region-size=4096` sets a 4 KiB region size. One region is the atomic unit dm-clone tracks: it is either fully hydrated (copied to the destination) or not, never partially. If a copy is interrupted mid-region, that whole region is retried from scratch on next boot. Smaller regions mean finer progress tracking; larger regions reduce metadata overhead. Defaults to `4K`. For background, see [dm-clone kernel documentation](https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/dm-clone.html). If no options are needed, the field may be omitted entirely or `-` may be used as a placeholder. At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by `systemd-clonesetup-generator(8)`. # Examples
Simple clone without options
Clone a source device to a destination, using a separate metadata device: mydevice /dev/sdb /dev/sdc /dev/sdd
Clone with custom region size
Clone a source device to a destination with a custom region size of 8 KiB: mydevice /dev/sdb /dev/sdc /dev/sdd region-size=8K
# See Also `systemd(1)`, `systemd-clonesetup-generator(8)`, `dmsetup(8)` # Environment `$SYSTEMD_LOG_LEVEL` The maximum log level of emitted messages (messages with a higher log level, i.e. less important ones, will be suppressed). Takes a comma-separated list of values. A value may be either one of (in order of decreasing importance) `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, `debug`, or an integer in the range 0…7. See `syslog(3)` for more information. Each value may optionally be prefixed with one of `console`, `syslog`, `kmsg` or `journal` followed by a colon to set the maximum log level for that specific log target (e.g. `SYSTEMD_LOG_LEVEL=debug,console:info` specifies to log at debug level except when logging to the console which should be at info level). Note that the global maximum log level takes priority over any per target maximum log levels. `$SYSTEMD_LOG_COLOR` A boolean. If true, messages written to the tty will be colored according to priority. This setting is only useful when messages are written directly to the terminal, because `journalctl(1)` and other tools that display logs will color messages based on the log level on their own. `$SYSTEMD_LOG_TIME` A boolean. If true, console log messages will be prefixed with a timestamp. This setting is only useful when messages are written directly to the terminal or a file, because `journalctl(1)` and other tools that display logs will attach timestamps based on the entry metadata on their own. `$SYSTEMD_LOG_LOCATION` A boolean. If true, messages will be prefixed with a filename and line number in the source code where the message originates. Note that the log location is often attached as metadata to journal entries anyway. Including it directly in the message text can nevertheless be convenient when debugging programs. `$SYSTEMD_LOG_TID` A boolean. If true, messages will be prefixed with the current numerical thread ID (TID). Note that the this information is attached as metadata to journal entries anyway. Including it directly in the message text can nevertheless be convenient when debugging programs. `$SYSTEMD_LOG_TARGET` The destination for log messages. One of `console` (log to the attached tty), `console-prefixed` (log to the attached tty but with prefixes encoding the log level and "facility", see `syslog(3)`, `kmsg` (log to the kernel circular log buffer), `journal` (log to the journal), `journal-or-kmsg` (log to the journal if available, and to kmsg otherwise), `auto` (determine the appropriate log target automatically, the default), `null` (disable log output). `$SYSTEMD_LOG_RATELIMIT_KMSG` Whether to ratelimit kmsg or not. Takes a boolean. Defaults to `true`. If disabled, systemd will not ratelimit messages written to kmsg. `$SYSTEMD_LOG_EXECUTABLE` A boolean. If true, messages will be prefixed with the current executable name. Note that this information is attached as metadata to journal entries anyway. Including it directly in the message text can nevertheless be convenient when debugging programs. `$SYSTEMD_PAGER`; `$PAGER` Pager to use when `--no-pager` is not given. `$SYSTEMD_PAGER` is used if set; otherwise `$PAGER` is used. If neither `$SYSTEMD_PAGER` nor `$PAGER` are set, a set of well-known pager implementations is tried in turn, including `less(1)` and `more(1)`, until one is found. If no pager implementation is discovered, no pager is invoked. Setting those environment variables to an empty string or the value `cat` is equivalent to passing `--no-pager`. Note: if `$SYSTEMD_PAGERSECURE` is not set, `$SYSTEMD_PAGER` and `$PAGER` can only be used to disable the pager (with `cat` or ``), and are otherwise ignored. `$SYSTEMD_LESS` Override the options passed to `less` (by default `FRSXMK`). Users might want to change two options in particular: `K` This option instructs the pager to exit immediately when Ctrl+C is pressed. To allow `less` to handle Ctrl+C itself to switch back to the pager command prompt, unset this option. If the value of `$SYSTEMD_LESS` does not include `K`, and the pager that is invoked is `less`, Ctrl+C will be ignored by the executable, and needs to be handled by the pager. `X` This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal. It is set by default to allow command output to remain visible in the terminal even after the pager exits. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse. Note that setting the regular `$LESS` environment variable has no effect for `less` invocations by systemd tools. See `less(1)` for more discussion. `$SYSTEMD_LESSCHARSET` Override the charset passed to `less` (by default `utf-8`, if the invoking terminal is determined to be UTF-8 compatible). Note that setting the regular `$LESSCHARSET` environment variable has no effect for `less` invocations by systemd tools. `$SYSTEMD_PAGERSECURE` Common pager commands like `less(1)`, in addition to "paging", i.e. scrolling through the output, support opening of or writing to other files and running arbitrary shell commands. When commands are invoked with elevated privileges, for example under `sudo(8)` or `pkexec(1)`, the pager becomes a security boundary. Care must be taken that only programs with strictly limited functionality are used as pagers, and unintended interactive features like opening or creation of new files or starting of subprocesses are not allowed. "Secure mode" for the pager may be enabled as described below, *if the pager supports that* (most pagers are not written in a way that takes this into consideration). It is recommended to either explicitly enable "secure mode" or to completely disable the pager using `--no-pager` or `PAGER=cat` when allowing untrusted users to execute commands with elevated privileges. This option takes a boolean argument. When set to true, the "secure mode" of the pager is enabled. In "secure mode", `LESSSECURE=1` will be set when invoking the pager, which instructs the pager to disable commands that open or create new files or start new subprocesses. Currently only `less(1)` is known to understand this variable and implement "secure mode". When set to false, no limitation is placed on the pager. Setting `SYSTEMD_PAGERSECURE=0` or not removing it from the inherited environment may allow the user to invoke arbitrary commands. When `$SYSTEMD_PAGERSECURE` is not set, systemd tools attempt to automatically figure out if "secure mode" should be enabled and whether the pager supports it. "Secure mode" is enabled if the effective UID is not the same as the owner of the login session, see `geteuid(2)` and `sd_pid_get_owner_uid(3)`, or when running under `sudo(8)` or similar tools (`$SUDO_UID` is set [^1]). In those cases, `SYSTEMD_PAGERSECURE=1` will be set and pagers which are not known to implement "secure mode" will not be used at all. Note that this autodetection only covers the most common mechanisms to elevate privileges and is intended as convenience. It is recommended to explicitly set `$SYSTEMD_PAGERSECURE` or disable the pager. Note that if the `$SYSTEMD_PAGER` or `$PAGER` variables are to be honoured, other than to disable the pager, `$SYSTEMD_PAGERSECURE` must be set too. `$SYSTEMD_COLORS` Takes a boolean argument, or a special value. By default (unset), `systemd` and related utilities will use colors in their output if possible. If `$COLORTERM` is set to `truecolor` or `24bit`, 24-bit colors will be enabled, 256 colors otherwise, unless `$NO_COLOR` or `$TERM` indicates colors are disabled. `true` Same as unset, except that `$NO_COLOR` is ignored. `false` The output will be monochrome. `16`; `256`; `24bit` Always use the base 16 ANSI colors, 256 colors, or 24 bit color, respectively. `auto-16`; `auto-256`; `auto-24bit` Use the given quantity of colours, subject to `$TERM`, and what the console is connected to. `$SYSTEMD_URLIFY` The value must be a boolean. Controls whether clickable links should be generated in the output for terminal emulators supporting this. This can be specified to override the decision that `systemd` makes based on `$TERM` and other conditions. [^1]: It is recommended for other tools to set and check `$SUDO_UID` as appropriate, treating it is a common interface. # coredump.conf systemd coredump.conf 5 coredump.conf coredump.conf.d Core dump storage configuration files `/etc/systemd/coredump.conf`, `/run/systemd/coredump.conf`, `/usr/local/lib/systemd/coredump.conf`, `/usr/lib/systemd/coredump.conf`, `/etc/systemd/coredump.conf.d/*.conf`, `/run/systemd/coredump.conf.d/*.conf`, `/usr/local/lib/systemd/coredump.conf.d/*.conf`, `/usr/lib/systemd/coredump.conf.d/*.conf` # Description These files configure the behavior of `systemd-coredump(8)`, a handler for core dumps invoked by the kernel. Whether `systemd-coredump` is used is determined by the kernel's `kernel.core_pattern` `sysctl(8)` setting. See `systemd-coredump(8)` and `core(5)` pages for the details. On systems where core dumps are processed by the long-running `systemd-coredumpd.service` (rather than a fresh `systemd-coredump@.service` instance started for every crash, see `systemd-coredump(8)` for details on when each applies), these configuration files are only read once, when the service starts. If `systemd-coredumpd.service` is running, changes to `coredump.conf` or its drop-ins will *not* take effect until the service is reloaded: systemctl reload systemd-coredumpd.service This causes the running service to reparse its configuration without restarting or interrupting any core dump currently being processed. # Options All options are configured in the \[Coredump\] section: `Storage=` Controls where to store cores. One of `none`, `external`, and `journal`. When `none`, the core dumps may be logged (including the backtrace if possible), but not stored permanently. When `external` (the default), cores will be stored in `/var/lib/systemd/coredump/`. When `journal`, cores will be stored in the journal and rotated following normal journal rotation patterns. When cores are stored in the journal, they might be compressed following journal compression settings, see `journald.conf(5)`. When cores are stored externally, they will be compressed by default, see below. Note that in order to process a coredump (i.e. extract a stack trace) the core must be written to disk first. Thus, unless `ProcessSizeMax=` is set to 0 (see below), the core will be written to `/var/lib/systemd/coredump/` either way (under a temporary filename, or even in an unlinked file), `Storage=` thus only controls whether to leave it there even after it was processed. `Compress=` Controls compression for external storage. Takes a boolean argument, which defaults to `yes`. `ProcessSizeMax=` The maximum size in bytes of a core which will be processed. Core dumps exceeding this size may be stored, but the stack trace will not be generated. Like other sizes in this same config file, the usual suffixes to the base of 1024 are allowed (B, K, M, G, T, P, and E). Defaults to 1G on 32-bit systems, 32G on 64-bit systems. Setting `Storage=none` and `ProcessSizeMax=0` disables all coredump handling except for a log entry. `EnterNamespace=` For processes belonging to a PID namespace, controls whether `systemd-coredump(8)` shall attempt to process core dumps on the host, using debug information from the file system hierarchy (i.e. the mount namespace) of the process that crashed. Access to the process' file system hierarchy might be necessary to generate a fully symbolized backtrace. If set to `yes`, `systemd-coredump` will obtain the tree of mounts from the crashing process' mount namespace and will try to generate the stack trace in host context using the debug information of binaries and libraries contained in the crashing process' hierarchy. Defaults to `no`, i.e. no attempt is made to acquire external debug information from the process' mount namespace, in order to maximize security. This option has no effect on processes that are part of the host's PID namespace. Note that the coredump of the namespaced process is still saved in `/var/lib/systemd/coredump/` on the host even if `EnterNamespace=` is set to `no` (subject to `Storage=`). Note that `EnterNamespace=` only has an effect if a core dump is generated by a container whose unit does not have `CoredumpReceive=` enabled. Note that it's typically preferable to let containers and other namespace-based sandboxes process their own coredumps, if possible, for best security. This may be enabled on the container's unit via the `CoredumpReceive=` setting, see `systemd.resource-control(5)` for details. `ExternalSizeMax=`; `JournalSizeMax=` The maximum (compressed or uncompressed) size in bytes of a coredump to be saved in separate files on disk (default: 1G on 32-bit systems, 32G on 64-bit systems) or in the journal (default: 767M). Note that the journal service enforces a hard limit on journal log records of 767M, and will ignore larger submitted log records. Hence, `JournalSizeMax=` may be lowered relative to the default, but not increased. Unit suffixes are allowed just as in `ProcessSizeMax=`. `ExternalSizeMax=infinity` sets the core size to unlimited. `MaxUse=`; `KeepFree=` Enforce limits on the disk space, specified in bytes, taken up by externally stored core dumps. Unit suffixes are allowed just as in `ProcessSizeMax=`. `MaxUse=` makes sure that old core dumps are removed as soon as the total disk space taken up by core dumps grows beyond this limit (defaults to 10% of the total disk size, capped at 4GiB, minimum 1MiB). `KeepFree=` controls how much disk space to keep free at least (defaults to 15% of the total disk size, limited to a maximum of 4GiB). Note that the disk space used by core dumps might temporarily exceed these limits while core dumps are processed. `MaxUse=` takes precedence. Note that old core dumps are also removed based on time via `systemd-tmpfiles(8)`. Set either value to 0 to turn off size-based cleanup. Use systemd-analyze cat-config systemd/coredump.conf to display the full config. # See Also `systemd-journald.service(8)`, `coredumpctl(1)`, `systemd-tmpfiles(8)` # coredumpctl systemd coredumpctl 1 coredumpctl Retrieve and process saved core dumps and metadata coredumpctl OPTIONS COMMAND ID\|PID\|COMM\|EXE\|MATCH # Description `coredumpctl` is a tool that can be used to retrieve and process core dumps and metadata which were saved by `systemd-coredump(8)`. # Commands The following commands are understood: `list` List core dumps captured in the journal matching specified characteristics. If no command is specified, this is the implied default. The output is designed to be human-readable and contains a table with the following columns: ID The UUID of the crash assigned by `systemd-coredump`. TIME The timestamp of the crash, as reported by the kernel. PID The identifier of the process that crashed. UID; GID The user and group identifiers of the process that crashed. SIGNAL The signal that caused the process to crash, when applicable. COREFILE Information whether the coredump was stored, and whether it is still accessible: `none` means the core was not stored, `-` means that it was not available (for example because the process was not terminated by a signal), `present` means that the core file is accessible by the current user, `journal` means that the core was stored in the `journal`, `truncated` is the same as one of the previous two, but the core was too large and was not stored in its entirety, `error` means that the core file cannot be accessed, most likely because of insufficient permissions, and `missing` means that the core was stored in a file, but this file has since been removed. EXE The full path to the executable. For backtraces of scripts this is the name of the interpreter. It's worth noting that different restrictions apply to data saved in the journal and core dump files saved in `/var/lib/systemd/coredump`, see overview in `systemd-coredump(8)`. Thus it may very well happen that a particular core dump is still listed in the journal while its corresponding core dump file has already been removed. `info` Show detailed information about the last core dump or core dumps matching specified characteristics captured in the journal. `dump` Extract the last core dump matching specified characteristics. The core dump will be written on standard output, unless an output file is specified with `--output=`. `debug` Invoke a debugger on the last core dump matching specified characteristics. By default, `gdb(1)` will be used. This may be changed using the `--debugger=` option or the `$SYSTEMD_DEBUGGER` environment variable. Use the `--debugger-arguments=` option to pass extra command line arguments to the debugger. # Options The following options are understood: `-l`; `--full` Do not ellipsize the output. `-1` Show information of the most recent core dump only, instead of listing all known core dumps. Equivalent to `--reverse -n 1`. `-n` \ Show at most the specified number of entries. The specified parameter must be an integer greater or equal to 1. `-S`; `--since` Only print entries which are since the specified date. `-U`; `--until` Only print entries which are until the specified date. `-r`; `--reverse` Reverse output so that the newest entries are displayed first. `-F` \; `--field=FIELD` Print all possible data values the specified field takes in matching core dump entries of the journal. `-o` \; `--output=FILE` Write the core to `FILE`. `--debugger=DEBUGGER` Use the given debugger for the `debug` command. If not given and `$SYSTEMD_DEBUGGER` is unset, then `gdb(1)` will be used. `-A` \; `--debugger-arguments=ARGS` Pass the given \ as extra command line arguments to the debugger. Quote as appropriate when \ contain whitespace. (See Examples.) `--file=GLOB` Takes a file glob as an argument. If specified, coredumpctl will operate on the specified journal files matching \ instead of the default runtime and system journal paths. May be specified multiple times, in which case files will be suitably interleaved. `-D` \; `--directory=DIR` Use the journal files in the specified `DIR`. `--root=ROOT` Use root directory `ROOT` when searching for coredumps. `--image=image` Takes a path to a disk image file or block device node. If specified, all operations are applied to file system in the indicated disk image. This option is similar to `--root=`, but operates on file systems stored in disk images or block devices. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). For further information on supported disk images, see `systemd-nspawn(1)`'s switch of the same name. `-q`; `--quiet` Suppresses informational messages about lack of access to journal files and possible in-flight coredumps. `--all` Look at all available journal files in `/var/log/journal/` (excluding journal namespaces) instead of only local ones. # Matching A match can be: \ Process ID of the process that dumped core. An integer. \ Name of the executable (matches `COREDUMP_COMM=`). Must not contain slashes. \ Path to the executable (matches `COREDUMP_EXE=`). Must contain at least one slash. \ General journalctl match filter, must contain an equals sign (`=`). See `journalctl(1)`. # Exit status On success, 0 is returned; otherwise, a non-zero failure code is returned. Not finding any matching core dumps is treated as failure. # Environment `$SYSTEMD_DEBUGGER` Use the given debugger for the `debug` command. See the `--debugger=` option. # Examples
List all the core dumps of a program
$ coredumpctl list /usr/lib64/firefox/firefox TIME PID UID GID SIG COREFILE EXE SIZE Tue … 8018 1000 1000 SIGSEGV missing /usr/lib64/firefox/firefox - Wed … 251609 1000 1000 SIGTRAP missing /usr/lib64/firefox/firefox - Fri … 552351 1000 1000 SIGSEGV present /usr/lib64/firefox/firefox 28.7M The journal has three entries pertaining to `/usr/lib64/firefox/firefox`, and only the last entry still has an available core file (in external storage on disk). Note that `coredumpctl` needs access to the journal files to retrieve the relevant entries from the journal. Thus, an unprivileged user will normally only see information about crashing programs of this user.
Invoke `gdb` on the last core dump
$ coredumpctl debug
Use `gdb` to display full register info from the last core dump
$ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"
Show information about a core dump matched by PID
$ coredumpctl info 6654 PID: 6654 (bash) UID: 1000 (user) GID: 1000 (user) Signal: 11 (SEGV) Timestamp: Mon 2021-01-01 00:00:01 CET (20s ago) Command Line: bash -c $'kill -SEGV $$' Executable: /usr/bin/bash Control Group: /user.slice/user-1000.slice/… Unit: user@1000.service User Unit: vte-spawn-….scope Slice: user-1000.slice Owner UID: 1000 (user) Boot ID: … Machine ID: … Hostname: … Storage: /var/lib/systemd/coredump/core.bash.1000.….zst (present) Size on Disk: 51.7K Message: Process 130414 (bash) of user 1000 dumped core. Stack trace of thread 130414: #0 0x00007f398142358b kill (libc.so.6 + 0x3d58b) #1 0x0000558c2c7fda09 kill_builtin (bash + 0xb1a09) #2 0x0000558c2c79dc59 execute_builtin.lto_priv.0 (bash + 0x51c59) #3 0x0000558c2c79709c execute_simple_command (bash + 0x4b09c) #4 0x0000558c2c798408 execute_command_internal (bash + 0x4c408) #5 0x0000558c2c7f6bdc parse_and_execute (bash + 0xaabdc) #6 0x0000558c2c85415c run_one_command.isra.0 (bash + 0x10815c) #7 0x0000558c2c77d040 main (bash + 0x31040) #8 0x00007f398140db75 __libc_start_main (libc.so.6 + 0x27b75) #9 0x0000558c2c77dd1e _start (bash + 0x31d1e)
Extract the last core dump of /usr/bin/bar to a file named `bar.coredump`
$ coredumpctl -o bar.coredump dump /usr/bin/bar
# See Also `systemd-coredump(8)`, `coredump.conf(5)`, `systemd-journald.service(8)`, `gdb(1)` # crypttab systemd crypttab 5 crypttab Configuration for encrypted block devices `/etc/crypttab` # Description The `/etc/crypttab` file describes encrypted block devices that are set up during system boot. Empty lines and lines starting with the `#` character are ignored. Each of the remaining lines describes one encrypted block device. Fields are delimited by white space. Each line is in the form volume-name encrypted-device key-file options The first two fields are mandatory, the remaining two are optional. Setting up encrypted block devices using this file supports four encryption modes: LUKS, TrueCrypt, BitLocker and plain. See `cryptsetup(8)` for more information about each mode. When no mode is specified in the options field and the block device contains a LUKS signature, it is opened as a LUKS device; otherwise, it is assumed to be in raw dm-crypt (plain mode) format. The four fields of `/etc/crypttab` are defined as follows: 1. The first field contains the name of the resulting volume with decrypted data; its block device is set up below `/dev/mapper/`. 2. The second field contains a path to the underlying block device or file, or a specification of a block device via `UUID=` followed by the UUID. 3. The third field specifies an absolute path to a file with the encryption key. Optionally, the path may be followed by `:` and an `/etc/fstab` style device specification (e.g. starting with `LABEL=` or similar); in which case the path is taken relative to the specified device's file system root. If the field is not present or is `none` or `-`, a key file named after the volume to unlock (i.e. the first column of the line), suffixed with `.key` is automatically loaded from the `/etc/cryptsetup-keys.d/` and `/run/cryptsetup-keys.d/` directories, if present. Otherwise, the password has to be manually entered during system boot. For swap encryption, `/dev/urandom` may be used as key file, resulting in a randomized key. If the specified key file path refers to an `AF_UNIX` stream socket in the file system, the key is acquired by connecting to the socket and reading it from the connection. This allows the implementation of a service to provide key information dynamically, at the moment when it is needed. For details see below. 4. The fourth field, if present, is a comma-delimited list of options. The supported options are listed below. # Key Acquisition Six different mechanisms for acquiring the decryption key or passphrase unlocking the encrypted volume are supported. Specifically: 1. Most prominently, the user may be queried interactively during volume activation (i.e. typically at boot), asking them to type in the necessary passphrases. 2. The (unencrypted) key may be read from a file on disk, possibly on removable media. The third field of each line encodes the location, for details see above. 3. The (unencrypted) key may be requested from another service, by specifying an `AF_UNIX` file system socket in place of a key file in the third field. For details see above and below. 4. The key may be acquired via a PKCS#11 compatible hardware security token or smartcard. In this case, a saved key used in unlock process is stored on disk/removable media, acquired via `AF_UNIX`, or stored in the LUKS2 JSON token metadata header. For RSA, the saved key is an encrypted volume key. The encrypted volume key is then decrypted by the PKCS#11 token with an RSA private key stored on it, and used to unlock the encrypted volume. For elliptic-curve (EC) cryptography, the saved key is the public key generated in enrollment process. The public key is then used to derive a shared secret with a private key stored in the PKCS#11 token. The derived shared secret is then used to unlock the volume. Use the `pkcs11-uri=` option described below to use this mechanism. 5. Similarly, the key may be acquired via a FIDO2 compatible hardware security token (which must implement the "hmac-secret" extension). In this case, a key generated randomly during enrollment is stored on disk/removable media, acquired via `AF_UNIX`, or stored in the LUKS2 JSON token metadata header. The random key is hashed via a keyed hash function (HMAC) on the FIDO2 token, using a secret key stored on the token that never leaves it. The resulting hash value is then used as key to unlock the encrypted volume. Use the `fido2-device=` option described below to use this mechanism. 6. Similarly, the key may be acquired via a TPM2 security chip. In this case, a (during enrollment) randomly generated key — encrypted by an asymmetric key derived from the TPM2 chip's seed key — is stored on disk/removable media, acquired via `AF_UNIX`, or stored in the LUKS2 JSON token metadata header. Use the `tpm2-device=` option described below to use this mechanism. For the latter five mechanisms the source for the key material used for unlocking the volume is primarily configured in the third field of each `/etc/crypttab` line, but may also be configured in `/etc/cryptsetup-keys.d/` and `/run/cryptsetup-keys.d/` (see above) or in the LUKS2 JSON token header (in case of the latter three). Use the `systemd-cryptenroll(1)` tool to enroll PKCS#11, FIDO2 and TPM2 devices in LUKS2 volumes. # Supported Options The following options may be used in the fourth field of each line: `cipher=` Specifies the cipher to use. See `cryptsetup(8)` for possible values and the default value of this option. A cipher with unpredictable IV values, such as `aes-cbc-essiv:sha256`, is recommended. Embedded commas in the cipher specification need to be escaped by preceding them with a backslash, see example below. `discard` Allow discard requests to be passed through the encrypted block device. This improves performance on SSD storage but has security implications. `hash=` Specifies the hash to use for password hashing. See `cryptsetup(8)` for possible values and the default value of this option. `header=` Use a detached (separated) metadata device or file where the header containing the master key(s) is stored. This option is only relevant for LUKS and TrueCrypt/VeraCrypt devices. See `cryptsetup(8)` for possible values and the default value of this option. Optionally, the path may be followed by `:` and an `/etc/fstab` device specification (e.g. starting with `UUID=` or similar); in which case, the path is relative to the device file system root. The device gets mounted automatically for LUKS device activation duration only. `keyfile-offset=` Specifies the number of bytes to skip at the start of the key file. See `cryptsetup(8)` for possible values and the default value of this option. `keyfile-size=` Specifies the maximum number of bytes to read from the key file. See `cryptsetup(8)` for possible values and the default value of this option. This option is ignored in plain encryption mode, where the key file size is determined by the key size. It is also ignored when the key file is used as a salt file for a FIDO2 token, as the salt size in that case is defined by the FIDO2 specification to be exactly 32 bytes. `keyfile-erase` If enabled, the specified key file is erased after the volume is activated or when activation fails. This is in particular useful when the key file is only acquired transiently before activation (e.g. via a file in `/run/`, generated by a service running before activation), and shall be removed after use. Defaults to off. Note that this option only applies to a key file explicitly configured in the third field, and has no effect on key files that are automatically discovered in `/etc/cryptsetup-keys.d/` and `/run/cryptsetup-keys.d/`. The latter are considered shared resources that are not owned by an individual volume, and hence are never erased. To erase an automatically discovered key file, configure its path explicitly in the third field. `key-slot=` Specifies the key slot to compare the passphrase or key against. If the key slot does not match the given passphrase or key, but another would, the setup of the device will fail regardless. This option implies `luks`. See `cryptsetup(8)` for possible values. The default is to try all key slots in sequential order. `keyfile-timeout=` Specifies the timeout for the device on which the key file resides or the device used as the key file, and falls back to a password if it could not be accessed. See `systemd-cryptsetup-generator(8)` for key files on external devices. `link-volume-key=` Specifies the kernel keyring and key description (see `keyrings(7)`) where LUKS2 volume key gets linked during device activation. The kernel keyring description and key description must be separated by `::`. The kernel keyring part can be a string description or a predefined kernel keyring prefixed with `@` (e.g.: to use `@s` session or `@u` user keyring directly). The type prefix text in the kernel keyring description is not required. The specified kernel keyring must already exist at the time of device activation. The key part is a string description optionally prefixed by a `%key_type:`. If no type is specified, the `user` type key is linked by default. See `keyctl(1)` for more information on key descriptions (KEY IDENTIFIERS section). Note that the linked volume key is not cleaned up automatically when the device is detached. `luks` Force LUKS mode. When this mode is used, the following options are ignored since they are provided by the LUKS header on the device: `cipher=`, `hash=`, `size=`. `bitlk` Decrypt BitLocker drive. Encryption parameters are deduced by cryptsetup from BitLocker header. `_netdev` Marks this cryptsetup device as requiring network. It will be started after the network is available, similarly to `systemd.mount(5)` units marked with `_netdev`. The service unit to set up this device will be ordered between `remote-fs-pre.target` and `remote-cryptsetup.target`, instead of `cryptsetup-pre.target` and `cryptsetup.target`. Hint: if this device is used for a mount point that is specified in `fstab(5)`, the `_netdev` option should also be used for the mount point. Otherwise, a dependency loop might be created where the mount point will be pulled in by `local-fs.target`, while the service to configure the network is usually only started *after* the local file system has been mounted. `noauto` This device will not be added to `cryptsetup.target`. This means that it will not be automatically unlocked on boot, unless something else pulls it in. In particular, if the device is used for a mount point, it'll be unlocked automatically during boot, unless the mount point itself is also disabled with `noauto`. `nofail` This device will not be a hard dependency of `cryptsetup.target`. It'll still be pulled in and started, but the system will not wait for the device to show up and be unlocked, and boot will not fail if this is unsuccessful. Note that other units that depend on the unlocked device may still fail. In particular, if the device is used for a mount point, the mount point itself also needs to have the `nofail` option, or the boot will fail if the device is not unlocked successfully. If a keyfile and/or a `header` are specified, the dependencies on their respective directories will also not be fatal, so that unmounting said directories will not cause the generated cryptset unit to be deactivated. `offset=` Start offset in the backend device, in 512-byte sectors. This option is only relevant for plain devices. `plain` Force plain encryption mode. `read-only`; `readonly` Set up the encrypted block device in read-only mode. `same-cpu-crypt` Perform encryption using the same CPU that IO was submitted on. The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs. This requires kernel 4.0 or newer. `submit-from-crypt-cpus` Disable offloading writes to a separate thread after encryption. There are some situations where offloading write requests from the encryption threads to a dedicated thread degrades performance significantly. The default is to offload write requests to a dedicated thread because it benefits the CFQ scheduler to have writes submitted using the same context. This requires kernel 4.0 or newer. `no-read-workqueue` Bypass dm-crypt internal workqueue and process read requests synchronously. The default is to queue these requests and process them asynchronously. This requires kernel 5.9 or newer. `no-write-workqueue` Bypass dm-crypt internal workqueue and process write requests synchronously. The default is to queue these requests and process them asynchronously. This requires kernel 5.9 or newer. `skip=` How many 512-byte sectors of the encrypted data to skip at the beginning. This is different from the `offset=` option with respect to the sector numbers used in initialization vector (IV) calculation. Using `offset=` will shift the IV calculation by the same negative amount. Hence, if `offset=n` is given, sector \ will get a sector number of 0 for the IV calculation. Using `skip=` causes sector \ to also be the first sector of the mapped device, but with its number for IV generation being \. This option is only relevant for plain devices. `size=` Specifies the key size in bits. See `cryptsetup(8)` for possible values and the default value of this option. `sector-size=` Specifies the sector size in bytes. See `cryptsetup(8)` for possible values and the default value of this option. `swap` The encrypted block device will be used as a swap device, and will be formatted accordingly after setting up the encrypted block device, with `mkswap(8)`. This option implies `plain`. > [!WARNING] > Using the `swap` option will destroy the contents of the named partition during every boot, so make sure the underlying block device is specified correctly. `tcrypt` Use TrueCrypt encryption mode. When this mode is used, the following options are ignored since they are provided by the TrueCrypt header on the device or do not apply: `cipher=`, `hash=`, `keyfile-offset=`, `keyfile-size=`, `size=`. When this mode is used, the passphrase is read from the key file given in the third field. Only the first line of this file is read, excluding the new line character. Note that the TrueCrypt format uses both passphrase and key files to derive a password for the volume. Therefore, the passphrase and all key files need to be provided. Use `tcrypt-keyfile=` to provide the absolute path to all key files. When using an empty passphrase in combination with one or more key files, use `/dev/null` as the password file in the third field. `tcrypt-hidden` Use the hidden TrueCrypt volume. This option implies `tcrypt`. This will map the hidden volume that is inside of the volume provided in the second field. Please note that there is no protection for the hidden volume if the outer volume is mounted instead. See `cryptsetup(8)` for more information on this limitation. `tcrypt-keyfile=` Specifies the absolute path to a key file to use for a TrueCrypt volume. This implies `tcrypt` and can be used more than once to provide several key files. See the entry for `tcrypt` on the behavior of the passphrase and key files when using TrueCrypt encryption mode. `tcrypt-system` Use TrueCrypt in system encryption mode. This option implies `tcrypt`. `tcrypt-veracrypt` Check for a VeraCrypt volume. VeraCrypt is a fork of TrueCrypt that is mostly compatible, but uses different, stronger key derivation algorithms that cannot be detected without this flag. Enabling this option could substantially slow down unlocking, because VeraCrypt's key derivation takes much longer than TrueCrypt's. This option implies `tcrypt`. `veracrypt-pim=` Specifies a custom Personal Iteration Multiplier (PIM) value, which can range from 0..2147468 for standard veracrypt volumes and 0..65535 for veracrypt system volumes. A value of 0 will imply the VeraCrypt default. This option is only effective when `tcrypt-veracrypt` is set. Note that VeraCrypt enforces a minimal allowed PIM value depending on the password strength and the hash algorithm used for key derivation, however `veracrypt-pim=` is not checked against these bounds. See [Veracrypt Personal Iterations Multiplier](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html) documentation for more information. `timeout=` Specifies the timeout for querying for a password. If no unit is specified, seconds is used. Supported units are s, ms, us, min, h, d. A timeout of 0 waits indefinitely (which is the default). `tmp=` The encrypted block device will be prepared for using it as `/tmp/`; it will be formatted using `mkfs(8)`. Takes a file system type as argument, such as `ext4`, `xfs` or `btrfs`. If no argument is specified defaults to `ext4`. This option implies `plain`. > [!WARNING] > Using the `tmp` option will destroy the contents of the named partition during every boot, so make sure the underlying block device is specified correctly. `tries=` Specifies the maximum number of times the user is queried for a password. The default is 3. If set to 0, the user is queried for a password indefinitely. `headless=` Takes a boolean argument, defaults to false. If true, never query interactively for the password/PIN. Useful for headless systems. `verify` If the encryption password is read from console, it has to be entered twice to prevent typos. `password-echo=yes|no|masked` Controls whether to echo passwords or security token PINs that are read from console. Takes a boolean or the special string `masked`. The default is `password-echo=masked`. If enabled, the typed characters are echoed literally. If disabled, the typed characters are not echoed in any form, the user will not get feedback on their input. If set to `masked`, an asterisk (`*`) is echoed for each character typed. Regardless of which mode is chosen, if the user hits the tabulator key (`↹`) at any time, or the backspace key (`⌫`) before any other data has been entered, then echo is turned off. `password-cache=yes|no|read-only` Controls whether to use cache for passwords or security token PINs. Takes a boolean or the special string `read-only`. Defaults to `yes`. If set to `read-only`, the kernel keyring is checked for a password/PIN before requesting one interactively. If set to `yes`, in addition to checking the keyring, any password/PIN entered interactively is cached in the keyring with a 2.5-minute timeout before being purged. Note that this option is not permitted for PKCS#11 security tokens. The reasoning behind this is that PKCS#11 security tokens are usually configured to lock after being supplied an invalid PIN multiple times, so using the cache might inadvertently lock the token. `pkcs11-uri=` Takes either the special value `auto` or an [RFC7512 PKCS#11 URI](https://tools.ietf.org/html/rfc7512) pointing to a private key which is used to decrypt the encrypted key specified in the third column of the line. This is useful for unlocking encrypted volumes through PKCS#11 compatible security tokens or smartcards. See below for an example how to set up this mechanism for unlocking a LUKS2 volume with a YubiKey security token. If specified as `auto` the volume must be of type LUKS2 and must carry PKCS#11 security token metadata in its LUKS2 JSON token section. In this mode the URI and the encrypted key are automatically read from the LUKS2 JSON token header. Use `systemd-cryptenroll(1)` as a simple tool for enrolling PKCS#11 security tokens or smartcards in a way compatible with `auto`. In this mode the third column of the line should remain empty (that is, specified as `-`). The specified URI can refer directly to a private key stored on a token or alternatively just to a slot or token, in which case a search for a suitable private key will be performed. In this case, if multiple suitable objects are found, the token is refused. The keyfile configured in the third column of the line is used as is (i.e. in binary form, unprocessed). The resulting decrypted key (for RSA) or derived shared secret (for ECC) is then Base64 encoded before it is used to unlock the LUKS volume. Use `systemd-cryptenroll --pkcs11-token-uri=list` to list all suitable PKCS#11 security tokens currently plugged in, along with their URIs. Note that many newer security tokens that may be used as PKCS#11 security token typically also implement the newer and simpler FIDO2 standard. Consider using `fido2-device=` (described below) to enroll it via FIDO2 instead. Note that a security token enrolled via PKCS#11 cannot be used to unlock the volume via FIDO2, unless also enrolled via FIDO2, and vice versa. `fido2-device=` Takes either the special value `auto` or the path to a `hidraw` device node (e.g. `/dev/hidraw1`) referring to a FIDO2 security token that implements the `hmac-secret` extension (most current hardware security tokens do). See below for an example how to set up this mechanism for unlocking an encrypted volume with a FIDO2 security token. If specified as `auto` the FIDO2 token device is automatically discovered, as it is plugged in. FIDO2 volume unlocking requires a client ID hash (CID) to be configured via `fido2-cid=` (see below) and a key to pass to the security token's HMAC functionality (configured in the line's third column) to operate. If not configured and the volume is of type LUKS2, the CID and the key are read from LUKS2 JSON token metadata instead. Use `systemd-cryptenroll(1)` as simple tool for enrolling FIDO2 security tokens for LUKS2 volumes. Use `systemd-cryptenroll --fido2-device=list` to list all suitable FIDO2 security tokens currently plugged in, along with their device nodes. This option implements the following mechanism: the configured key is hashed via they HMAC keyed hash function the FIDO2 device implements, keyed by a secret key embedded on the device. The resulting hash value is Base64 encoded and used to unlock the LUKS2 volume. As it should not be possible to extract the secret from the hardware token, it should not be possible to retrieve the hashed key given the configured key — without possessing the hardware token. Note that many security tokens that implement FIDO2 also implement PKCS#11, suitable for unlocking volumes via the `pkcs11-uri=` option described above. Typically the newer, simpler FIDO2 standard is preferable. `fido2-cid=` Takes a Base64 encoded FIDO2 client ID to use for the FIDO2 unlock operation. If specified, but `fido2-device=` is not, `fido2-device=auto` is implied. If `fido2-device=` is used but `fido2-cid=` is not, the volume must be of LUKS2 type, and the CID is read from the LUKS2 JSON token header. Use `systemd-cryptenroll(1)` for enrolling a FIDO2 token in the LUKS2 header compatible with this automatic mode. `fido2-rp=` Takes a string, configuring the FIDO2 Relying Party (rp) for the FIDO2 unlock operation. If not specified, `io.systemd.cryptsetup` is used, except if the LUKS2 JSON token header contains a different value. It should normally not be necessary to override this. `fido2-pin=` Controls whether to require the user to enter a PIN when unlocking the volume (the FIDO2 `clientPin` feature). This option only applies when in manual mode, i.e. when `fido2-cid=` option is set. Defaults to neither true or false, but rather to `v248` behavior, that is: try with no PIN first, but if token reports that PIN is required, try again asking for PIN. `fido2-up=` Controls whether to require the user to verify presence (tap the token, the FIDO2 `up` feature) when unlocking the volume. This option only applies when in manual mode, i.e. when `fido2-cid=` option is set. Defaults to neither true or false, but rather to `v248` behavior, that is: try with no UP first, but if token reports that UP is required, try again with UP enabled. `fido2-uv=` Controls whether to require user verification (the FIDO2 `uv` feature) when unlocking the volume. This option only applies when in manual mode, i.e. when `fido2-cid=` option is set. Defaults to neither true or false, but rather to `v248` behavior, that is: omit configuring UV whatsoever. `tpm2-device=` Takes either the special value `auto` or the path to a device node (e.g. `/dev/tpmrm0`) referring to a TPM2 security chip. See below for an example how to set up this mechanism for unlocking an encrypted volume with a TPM2 chip. Use `tpm2-pcrs=` (see below) to configure the set of TPM2 PCRs to bind the volume unlocking to. Use `systemd-cryptenroll(1)` as simple tool for enrolling TPM2 security chips in LUKS2 volumes. If specified as `auto` the TPM2 device is automatically discovered. Use `systemd-cryptenroll --tpm2-device=list` to list all suitable TPM2 devices currently available, along with their device nodes. This option implements the following mechanism: when enrolling a TPM2 device via `systemd-cryptenroll` on a LUKS2 volume, a randomized key unlocking the volume is generated on the host and loaded into the TPM2 chip where it is encrypted with an asymmetric "primary" key pair derived from the TPM2's internal "seed" key. Neither the seed key nor the primary key are permitted to ever leave the TPM2 chip — however, the now encrypted randomized key may. It is saved in the LUKS2 volume JSON token header. When unlocking the encrypted volume, the primary key pair is generated on the TPM2 chip again (which works as long as the chip's seed key is correctly maintained by the TPM2 chip), which is then used to decrypt (on the TPM2 chip) the encrypted key from the LUKS2 volume JSON token header saved there during enrollment. The resulting decrypted key is then used to unlock the volume. When the randomized key is encrypted the current values of the selected PCRs (see below) are included in the operation, so that different PCR state results in different encrypted keys and the decrypted key can only be recovered if the same PCR state is reproduced. `tpm2-pcrs=` Takes a `+` separated list of numeric TPM2 PCR (i.e. "Platform Configuration Register") indexes to bind the TPM2 volume unlocking to. This option is only useful when TPM2 enrollment metadata is not available in the LUKS2 JSON token header already, the way `systemd-cryptenroll` writes it there. If not used (and no metadata in the LUKS2 JSON token header defines it), defaults to a list of a single entry: PCR 7. Assign an empty string to encode a policy that binds the key to no PCRs, making the key accessible to local programs regardless of the current PCR state. `tpm2-pin=` Takes a boolean argument, defaults to `false`. Controls whether TPM2 volume unlocking is bound to a PIN in addition to PCRs. Similarly, this option is only useful when TPM2 enrollment metadata is not available. `tpm2-signature=` Takes an absolute path to a TPM2 PCR JSON signature file, as produced by the `systemd-measure(1)` tool. This permits locking LUKS2 volumes to any PCR values for which a valid signature matching a public key specified at key enrollment time can be provided. See `systemd-cryptenroll(1)` for details on enrolling TPM2 PCR public keys. If this option is not specified but it is attempted to unlock a LUKS2 volume with a signed TPM2 PCR enrollment, a suitable signature file `tpm2-pcr-signature.json` is searched for in `/etc/systemd/`, `/run/systemd/`, `/usr/lib/systemd/` (in this order). `tpm2-pcrlock=` Takes an absolute path to a TPM2 pcrlock policy file, as produced by the `systemd-pcrlock(8)` tool. This permits locking LUKS2 volumes to a local policy of allowed PCR values with variants. See `systemd-cryptenroll(1)` for details on enrolling TPM2 pcrlock policies. If this option is not specified but it is attempted to unlock a LUKS2 volume with a TPM2 pcrlock enrollment, a suitable signature file `pcrlock.json` is searched for in `/run/systemd/` and `/var/lib/systemd/` (in this order). `tpm2-measure-pcr=` Controls whether to measure the volume key of the encrypted volume to a TPM2 PCR. If set to "no" (which is the default) no PCR extension is done. If set to "yes" the volume key is measured into PCR 15. If set to a decimal integer in the range 0…23 the volume key is measured into the specified PCR. The volume key is measured along with the activated volume name and its UUID. This functionality is particularly useful for the encrypted volume backing the root file system, as it then allows later TPM objects to be securely bound to the root file system and hence the specific installation. `tpm2-measure-bank=` This option is deprecated and has no effect since version 262. All suitable PCR banks are used. `tpm2-measure-keyslot-nvpcr=` Controls whether to measure information about the used LUKS unlock keyslot to a TPM2 non-volatile index (nvindex in PCR mode). Takes a boolean argument, or an NvPCR name. If set to false or an empty string (which is the default) no TPM2 nvindex extension is done, otherwise keyslot information is measured to an nvindex of the specified name, which is allocated if needed. If set to true the recommended default of `cryptsetup` is selected as NvPCR. The slot index and the used unlock mechanism (i.e. `tpm2`, `fido2`, `pkcs11`) are measured along with the activated volume name and its UUID. `token-timeout=` Specifies how long to wait at most for configured security devices (i.e. FIDO2, PKCS#11, TPM2) to show up. Takes a time value in seconds (but other time units may be specified too, see `systemd.time(7)` for supported formats). Defaults to 30s. Once the specified timeout elapsed authentication via password is attempted. Note that this timeout applies to waiting for the security device to show up — it does not apply to the PIN prompt for the device (should one be needed) or similar. Pass 0 to turn off the timeout and wait forever. `try-empty-password=` Takes a boolean argument. If enabled, right before asking the user for a password it is first attempted to unlock the volume with an empty password. This is useful for systems that are initialized with an encrypted volume with only an empty password set, which shall be replaced with a suitable password during first boot, but after activation. `x-systemd.device-timeout=` Specifies how long systemd should wait for a block device to show up before giving up on the entry. The argument is a time in seconds or explicitly specified units of `s`, `min`, `h`, `ms`. `x-initrd.attach` Setup this encrypted block device in the initrd, similarly to `systemd.mount(5)` units marked with `x-initrd.mount`. Although it is not necessary to mark the mount entry for the root file system with `x-initrd.mount`, `x-initrd.attach` is still recommended with the encrypted block device containing the root file system as otherwise systemd will attempt to detach the device during the regular system shutdown while it is still in use. With this option the device will still be detached but later after the root file system is unmounted. All other encrypted block devices that contain file systems mounted in the initrd should use this option. `fixate-volume-key=` Pin the expected hash of the volume key. In certain cases, e.g. for LUKS volumes where the key is sealed to the TPM2, this may be required to provide a guarantee that the volume being attached is the volume which was previously created. `fixate-volume-key=` can be used to set the expected volume key hash and refuse to attach the volume if it has a different one. The expected hash matches the digest which is measured to the sha256 PCR bank of the TPM2 when `tpm2-measure-pcr=` is used. For newly created LUKS volumes, the expected hash can be generated by `systemd-repart(8)`. For additional details, see the `EncryptedVolume=` description at `repart.d(5)`. `friendly-name=` Takes a string that overrides the automatically generated description of this device, which is displayed when the user is prompted for its passphrase or PKCS#11 token PIN and in some log messages. The name must be no more than 100 bytes. Invalid names are ignored. (A warning is logged, and the automatically generated description is used instead.) Note that the name cannot contain whitespace, because fields in `/etc/crypttab` are whitespace-delimited. At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by `systemd-cryptsetup-generator(8)`. # `AF_UNIX` Key Files If the key file path (as specified in the third column of `/etc/crypttab` entries, see above) refers to an `AF_UNIX` stream socket in the file system, the key is acquired by connecting to the socket and reading the key from the connection. The connection is made from an `AF_UNIX` socket name in the abstract namespace, see `unix(7)` for details. The source socket name is chosen according to the following format: NUL RANDOM /cryptsetup/ VOLUME In other words: a `NUL` byte (as required for abstract namespace sockets), followed by a random string (consisting of alphanumeric characters only), followed by the literal string `/cryptsetup/`, followed by the name of the volume to acquire they key for. For example, for the volume `myvol`: \0d7067f78d9827418/cryptsetup/myvol Services listening on the `AF_UNIX` stream socket may query the source socket name with `getpeername(2)`, and use this to determine which key to send, allowing a single listening socket to serve keys for multiple volumes. If the PKCS#11 logic is used (see above), the socket source name is picked in similar fashion, except that the literal string `/cryptsetup-pkcs11/` is used. And similarly for FIDO2 (`/cryptsetup-fido2-salt/`) and TPM2 (`/cryptsetup-tpm2/`). A different path component is used so that services providing key material know that the secret key was not requested directly, but instead an encrypted key that will be decrypted via the PKCS#11/FIDO2/TPM2 logic to acquire the final secret key. # Examples
/etc/crypttab example
Set up four encrypted block devices. One using LUKS for normal storage, another one for usage as a swap device and two TrueCrypt volumes. For the fourth device, the option string is interpreted as two options `cipher=xchacha12,aes-adiantum-plain64`, `keyfile-timeout=10s`. luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b swap /dev/sda7 /dev/urandom swap truecrypt /dev/sda2 /etc/container_password tcrypt hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchacha12\,aes-adiantum-plain64
Yubikey-based PKCS#11 Volume Unlocking Example
The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA or EC cryptographic keys for unlocking an encrypted volume. Here's an example how to set up a Yubikey security token for this purpose on a LUKS2 volume, using `ykmap(1)` from the yubikey-manager project to initialize the token and `systemd-cryptenroll(1)` to add it in the LUKS2 volume: A few notes on the above: - We use RSA2048, which is the longest key size current Yubikeys support - We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes, see [Yubico PIV certificate slots](https://developers.yubico.com/PIV/Introduction/Certificate_slots.html).
FIDO2 Volume Unlocking Example
The FIDO2 logic allows using any compatible FIDO2 security token that implements the `hmac-secret` extension for unlocking an encrypted volume. Here's an example how to set up a FIDO2 security token for this purpose for a LUKS2 volume, using `systemd-cryptenroll(1)`:
TPM2 Volume Unlocking Example
The TPM2 logic allows using any TPM2 chip supported by the Linux kernel for unlocking an encrypted volume. Here's an example how to set up a TPM2 chip for this purpose for a LUKS2 volume, using `systemd-cryptenroll(1)`:
# See Also `systemd(1)`, `systemd-cryptsetup@.service(8)`, `systemd-cryptsetup-generator(8)`, `systemd-cryptenroll(1)`, `systemd-repart(8)`, `repart.d(5)`, `fstab(5)`, `cryptsetup(8)`, `mkswap(8)`, `mke2fs(8)` # daemon systemd daemon 7 daemon Writing and packaging system daemons # Description A daemon is a service process that runs in the background and supervises the system or provides functionality to other processes. Traditionally, daemons are implemented following a scheme originating in SysV Unix. Modern daemons should follow a simpler yet more powerful scheme (here called "new-style" daemons), as implemented by `systemd(1)`. This manual page covers both schemes, and in particular includes recommendations for daemons that shall be included in the systemd init system. ## SysV Daemons When a traditional SysV daemon starts, it should execute the following steps as part of the initialization. Note that these steps are unnecessary for new-style daemons (see below), and should only be implemented if compatibility with SysV is essential. 1. Close all open file descriptors except standard input, output, and error (i.e. the first three file descriptors 0, 1, 2). This ensures that no accidentally passed file descriptor stays around in the daemon process. On Linux, this is best implemented by iterating through `/proc/self/fd`, with a fallback of iterating from file descriptor 3 to the value returned by `getrlimit()` for `RLIMIT_NOFILE`. 2. Reset all signal handlers to their default. This is best done by iterating through the available signals up to the limit of `_NSIG` and resetting them to `SIG_DFL`. 3. Reset the signal mask using `sigprocmask()`. 4. Sanitize the environment block, removing or resetting environment variables that might negatively impact daemon runtime. 5. Call `fork()`, to create a background process. 6. In the child, call `setsid()` to detach from any terminal and create an independent session. 7. In the child, call `fork()` again, to ensure that the daemon can never re-acquire a terminal again. (This is relevant if the program — and all its dependencies — does not carefully specify \`O_NOCTTY\` on each and every single \`open()\` call that might potentially open a TTY device node.) 8. Call `exit()` in the first child, so that only the second child (the actual daemon process) stays around. This ensures that the daemon process is re-parented to init/PID 1, as all daemons should be. 9. In the daemon process, connect `/dev/null` to standard input, output, and error. 10. In the daemon process, reset the umask to 0, so that the file modes passed to `open()`, `mkdir()` and suchlike directly control the access mode of the created files and directories. 11. In the daemon process, change the current directory to the root directory (/), in order to avoid that the daemon involuntarily blocks mount points from being unmounted. 12. In the daemon process, write the daemon PID (as returned by `getpid()`) to a PID file, for example `/run/foobar.pid` (for a hypothetical daemon "foobar") to ensure that the daemon cannot be started more than once. This must be implemented in race-free fashion so that the PID file is only updated when it is verified at the same time that the PID previously stored in the PID file no longer exists or belongs to a foreign process. 13. In the daemon process, drop privileges, if possible and applicable. 14. From the daemon process, notify the original process started that initialization is complete. This can be implemented via an unnamed pipe or similar communication channel that is created before the first `fork()` and hence available in both the original and the daemon process. 15. Call `exit()` in the original process. The process that invoked the daemon must be able to rely on that this `exit()` happens after initialization is complete and all external communication channels are established and accessible. The BSD `daemon()` function should not be used, as it implements only a subset of these steps. A daemon that needs to provide compatibility with SysV systems should implement the scheme pointed out above. However, it is recommended to make this behavior optional and configurable via a command line argument to ease debugging as well as to simplify integration into systems using systemd. ## New-Style Daemons Modern services for Linux should be implemented as new-style daemons. This makes it easier to supervise and control them at runtime and simplifies their implementation. For developing a new-style daemon, none of the initialization steps recommended for SysV daemons need to be implemented. New-style init systems such as systemd make all of them redundant. Moreover, since some of these steps interfere with process monitoring, file descriptor passing, and other functionality of the service manager, it is recommended not to execute them when run as new-style service. Note that new-style init systems guarantee execution of daemon processes in a clean process context: it is guaranteed that the environment block is sanitized, that the signal handlers and mask is reset and that no left-over file descriptors are passed. Daemons will be executed in their own session, with standard input connected to `/dev/null` and standard output/error connected to the `systemd-journald.service(8)` logging service, unless otherwise configured. The umask is reset. It is recommended for new-style daemons to implement the following: 1. If applicable, the daemon should notify the service manager about startup completion or status updates via the `sd_notify(3)` interface, in particular `READY=1` and `STATUS=…`. 2. If `SIGTERM` is received, shut down the daemon and exit cleanly. A `STOPPING=1` notification should be sent via `sd_notify(3)`. 3. If `SIGHUP` is received, reload the configuration files, if this applies. This should be combined with notifications via `sd_notify(3)`: `RELOADING=1` and `READY=1`. 4. Provide a correct exit code from the main daemon process, as this is used by the service manager to detect service errors and problems. It is recommended to follow the exit code scheme as defined in the [LSB recommendations for SysV init scripts](http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html). 5. If possible and applicable, expose the daemon's control interface via the D-Bus IPC system and grab a bus name as last step of initialization. 6. For integration in systemd, provide a `.service` unit file that carries information about starting, stopping and otherwise maintaining the daemon. See `systemd.service(5)` for details. 7. As much as possible, rely on the service manager's functionality to limit the access of the daemon to files, services, and other resources, i.e. in the case of systemd, rely on systemd's resource limit control instead of implementing your own, rely on systemd's privilege dropping code instead of implementing it in the daemon, and so on. See `systemd.exec(5)` for the available controls. 8. If D-Bus is used, make your daemon bus-activatable by supplying a D-Bus service activation configuration file. This has multiple advantages: your daemon may be started lazily on-demand; it may be started in parallel to other daemons requiring it — which maximizes parallelization and boot-up speed; your daemon can be restarted on failure without losing any bus requests, as the bus queues requests for activatable services. See below for details. 9. If your daemon provides services to other local processes or remote clients via a socket, it should be made socket-activatable following the scheme pointed out below. Like D-Bus activation, this enables on-demand starting of services as well as it allows improved parallelization of service start-up. Also, for state-less protocols (such as syslog, DNS), a daemon implementing socket-based activation can be restarted without losing a single request. See below for details. 10. If the service opens sockets or other files on it own, and those file descriptors shall survive a restart, the daemon should store them in the service manager via `sd_notify(3)` with `FDSTORE=1`. 11. Instead of using the `syslog()` call to log directly to the system syslog service, a new-style daemon may choose to simply log to standard error via `fprintf()`, which is then forwarded to syslog. If log levels are necessary, these can be encoded by prefixing individual log lines with strings like `<4>` (for log level 4 "WARNING" in the syslog priority scheme), following a similar style as the Linux kernel's `printk()` level system. For details, see `sd-daemon(3)` and `systemd.exec(5)`. 12. As new-style daemons are invoked without a controlling TTY (but as their own session leaders) care should be taken to always specify `O_NOCTTY` on `open(2)` calls that possibly reference a TTY device node, so that no controlling TTY is accidentally acquired. These recommendations are similar but not identical to the [Apple MacOS X Daemon Requirements](https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html). # Activation New-style init systems provide multiple additional mechanisms to activate services, as detailed below. It is common that services are configured to be activated via more than one mechanism at the same time. An example for systemd: `bluetoothd.service` might get activated either when Bluetooth hardware is plugged in, or when an application accesses its programming interfaces via D-Bus. Or, a print server daemon might get activated when traffic arrives at an IPP port, or when a printer is plugged in, or when a file is queued in the printer spool directory. Even for services that are intended to be started on system bootup unconditionally, it is a good idea to implement some of the various activation schemes outlined below, in order to maximize parallelization. If a daemon implements a D-Bus service or listening socket, implementing the full bus and socket activation scheme allows starting of the daemon with its clients in parallel (which speeds up boot-up), since all its communication channels are established already, and no request is lost because client requests will be queued by the bus system (in case of D-Bus) or the kernel (in case of sockets) until the activation is completed. ## Activation on Boot Old-style daemons are usually activated exclusively on boot (and manually by the administrator) via SysV init scripts, as detailed in the [LSB Linux Standard Base Core Specification](http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html). Among other issues, SysV init scripts have the disadvantage of involving shell scripts in the boot process. Support for init scripts has been phased out in modern Linux init systems, and should not be relied upon. New-style init systems generally use updated versions of activation, both during boot-up and during runtime and using more minimal service description files. In systemd, if the developer or administrator wants to make sure that a service or other unit is activated automatically on boot, it is recommended to place a symlink to the unit file in the `.wants/` directory of either `multi-user.target` or `graphical.target`, which are normally used as boot targets at system startup. See `systemd.unit(5)` for details about the `.wants/` directories, and `systemd.special(7)` for details about the two boot targets. ## Socket-Based Activation In order to maximize the possible parallelization and robustness and simplify configuration and development, it is recommended for all new-style daemons that communicate via listening sockets to use socket-based activation. In a socket-based activation scheme, the creation and binding of the listening socket as primary communication channel of daemons to local (and sometimes remote) clients is moved out of the daemon code and into the service manager. Based on per-daemon configuration, the service manager installs the sockets and then hands them off to the spawned process as soon as the respective daemon is to be started. Optionally, activation of the service can be delayed until the first inbound traffic arrives at the socket to implement on-demand activation of daemons. However, the primary advantage of this scheme is that all providers and all consumers of the sockets can be started in parallel as soon as all sockets are established. In addition to that, daemons can be restarted with losing only a minimal number of client transactions, or even any client request at all (the latter is particularly true for state-less protocols, such as DNS or syslog), because the socket stays bound and accessible during the restart, and all requests are queued while the daemon cannot process them. New-style daemons which support socket activation must be able to receive their sockets from the service manager instead of creating and binding them themselves. For details about the programming interfaces for this scheme provided by systemd, see `sd_listen_fds(3)` and `sd-daemon(3)`. For details about porting existing daemons to socket-based activation, see below. With minimal effort, it is possible to implement socket-based activation in addition to traditional internal socket creation in the same codebase in order to support both new-style and old-style init systems from the same daemon binary. systemd implements socket-based activation via `.socket` units, which are described in `systemd.socket(5)`. When configuring socket units for socket-based activation, it is essential that all listening sockets are pulled in by the special target unit `sockets.target`. It is recommended to place a `WantedBy=sockets.target` directive in the \[Install\] section to automatically add such a dependency on installation of a socket unit. Unless `DefaultDependencies=no` is set, the necessary ordering dependencies are implicitly created for all socket units. For more information about `sockets.target`, see `systemd.special(7)`. It is not necessary or recommended to place any additional dependencies on socket units (for example from `multi-user.target` or suchlike) when one is installed in `sockets.target`. ## Bus-Based Activation When the D-Bus IPC system is used for communication with clients, new-style daemons should use bus activation so that they are automatically activated when a client application accesses their IPC interfaces. This is configured in D-Bus service files (not to be confused with systemd service unit files!). To ensure that D-Bus uses systemd to start-up and maintain the daemon, use the `SystemdService=` directive in these service files to configure the matching systemd service for a D-Bus service. e.g.: For a D-Bus service whose D-Bus activation file is named `org.freedesktop.RealtimeKit.service`, make sure to set `SystemdService=rtkit-daemon.service` in that file to bind it to the systemd service `rtkit-daemon.service`. This is needed to make sure that the daemon is started in a race-free fashion when activated via multiple mechanisms simultaneously. ## Device-Based Activation Often, daemons that manage a particular type of hardware should be activated only when the hardware of the respective kind is plugged in or otherwise becomes available. In a new-style init system, it is possible to bind activation to hardware plug/unplug events. In systemd, kernel devices appearing in the sysfs/udev device tree can be exposed as units if they are tagged with the string `systemd`. Like any other kind of unit, they may then pull in other units when activated (i.e. plugged in) and thus implement device-based activation. systemd dependencies may be encoded in the udev database via the `SYSTEMD_WANTS=` property. See `systemd.device(5)` for details. Often, it is nicer to pull in services from devices only indirectly via dedicated targets. Example: Instead of pulling in `bluetoothd.service` from all the various bluetooth dongles and other hardware available, pull in bluetooth.target from them and `bluetoothd.service` from that target. This provides for nicer abstraction and gives administrators the option to enable `bluetoothd.service` via controlling a `bluetooth.target.wants/` symlink uniformly with a command like `enable` of `systemctl(1)` instead of manipulating the udev ruleset. ## Path-Based Activation Often, runtime of daemons processing spool files or directories (such as a printing system) can be delayed until these file system objects change state, or become non-empty. New-style init systems provide a way to bind service activation to file system changes. systemd implements this scheme via path-based activation configured in `.path` units, as outlined in `systemd.path(5)`. ## Timer-Based Activation Some daemons that implement clean-up jobs that are intended to be executed in regular intervals benefit from timer-based activation. In systemd, this is implemented via `.timer` units, as described in `systemd.timer(5)`. ## Other Forms of Activation Other forms of activation have been suggested and implemented in some systems. However, there are often simpler or better alternatives, or they can be put together of combinations of the schemes above. Example: Sometimes, it appears useful to start daemons or `.socket` units when a specific IP address is configured on a network interface, because network sockets shall be bound to the address. However, an alternative to implement this is by utilizing the Linux `IP_FREEBIND`/`IPV6_FREEBIND` socket option, as accessible via `FreeBind=yes` in systemd socket files (see `systemd.socket(5)` for details). This option, when enabled, allows sockets to be bound to a non-local, not configured IP address, and hence allows bindings to a particular IP address before it actually becomes available, making such an explicit dependency to the configured address redundant. Another often suggested trigger for service activation is low system load. However, here too, a more convincing approach might be to make proper use of features of the operating system, in particular, the CPU or I/O scheduler of Linux. Instead of scheduling jobs from userspace based on monitoring the OS scheduler, it is advisable to leave the scheduling of processes to the OS scheduler itself. systemd provides fine-grained access to the CPU and I/O schedulers. If a process executed by the service manager shall not negatively impact the amount of CPU or I/O bandwidth available to other processes, it should be configured with `CPUSchedulingPolicy=idle` and/or `IOSchedulingClass=idle`. Optionally, this may be combined with timer-based activation to schedule background jobs during runtime and with minimal impact on the system, and remove it from the boot phase itself. # Integration with systemd ## Writing systemd Unit Files When writing systemd unit files, it is recommended to consider the following suggestions: 1. If possible, do not use the `Type=forking` setting in service files. But if you do, make sure to set the PID file path using `PIDFile=`. See `systemd.service(5)` for details. 2. If your daemon registers a D-Bus name on the bus, make sure to use `Type=dbus` in the service file if possible. 3. Make sure to set a good human-readable description string with `Description=`. 4. Do not disable `DefaultDependencies=`, unless you really know what you do and your unit is involved in early boot or late system shutdown. 5. Normally, little if any dependencies should need to be defined explicitly. However, if you do configure explicit dependencies, only refer to unit names listed on `systemd.special(7)` or names introduced by your own package to keep the unit file operating system-independent. 6. Make sure to include an \[Install\] section including installation information for the unit file. See `systemd.unit(5)` for details. To activate your service on boot, make sure to add a `WantedBy=multi-user.target` or `WantedBy=graphical.target` directive. To activate your socket on boot, make sure to add `WantedBy=sockets.target`. Usually, you also want to make sure that when your service is installed, your socket is installed too, hence add `Also=foo.socket` in your service file `foo.service`, for a hypothetical program `foo`. ## Installing systemd Service Files At the build installation time (e.g. `make install` during package build), packages are recommended to install their systemd unit files in the directory returned by `pkg-config systemd --variable=systemdsystemunitdir` (for system services) or `pkg-config systemd --variable=systemduserunitdir` (for user services). This will make the services available in the system on explicit request but not activate them automatically during boot. Optionally, during package installation (e.g. `rpm -i` by the administrator), symlinks should be created in the systemd configuration directories via the `enable` command of the `systemctl(1)` tool to activate them automatically on boot. Packages using `autoconf(1)` are recommended to use a configure script excerpt like the following to determine the unit installation path during source configuration: PKG_PROG_PKG_CONFIG() AC_ARG_WITH([systemdsystemunitdir], [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],, [with_systemdsystemunitdir=auto]) AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [ def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd) AS_IF([test "x$def_systemdsystemunitdir" = "x"], [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"], [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])]) with_systemdsystemunitdir=no], [with_systemdsystemunitdir="$def_systemdsystemunitdir"])]) AS_IF([test "x$with_systemdsystemunitdir" != "xno"], [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])]) AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"]) This snippet allows automatic installation of the unit files on systemd machines, and optionally allows their installation even on machines lacking systemd. (Modification of this snippet for the user unit directory is left as an exercise for the reader.) Additionally, to ensure that `make distcheck` continues to work, it is recommended to add the following to the top-level `Makefile.am` file in `automake(1)`-based projects: AM_DISTCHECK_CONFIGURE_FLAGS = \ --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir) Finally, unit files should be installed in the system with an automake excerpt like the following: if HAVE_SYSTEMD systemdsystemunit_DATA = \ foobar.socket \ foobar.service endif In the `rpm(8)` `.spec` file, use snippets like the following to enable/disable the service during installation/deinstallation. This makes use of the RPM macros shipped along systemd. Consult the packaging guidelines of your distribution for details and the equivalent for other package managers. At the top of the file: BuildRequires: systemd %{?systemd_requires} And as scriptlets, further down: %post %systemd_post foobar.service foobar.socket %preun %systemd_preun foobar.service foobar.socket %postun %systemd_postun If the service shall be restarted during upgrades, replace the `%postun` scriptlet above with the following: %postun %systemd_postun_with_restart foobar.service Note that `%systemd_post` and `%systemd_preun` expect the names of all units that are installed/removed as arguments, separated by spaces. `%systemd_postun` expects no arguments. `%systemd_postun_with_restart` expects the units to restart as arguments. To facilitate upgrades from a package version that shipped only SysV init scripts to a package version that ships both a SysV init script and a native systemd service file, use a fragment like the following: %triggerun -- foobar < 0.47.11-1 if /sbin/chkconfig --level 5 foobar ; then /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || : fi Where 0.47.11-1 is the first package version that includes the native unit file. This fragment will ensure that the first time the unit file is installed, it will be enabled if and only if the SysV init script is enabled, thus making sure that the enable status is not changed. Note that `chkconfig` is a command specific to Fedora which can be used to check whether a SysV init script is enabled. Other operating systems will have to use different commands here. # Porting Existing Daemons Since new-style init systems such as systemd are compatible with traditional SysV init systems, it is not strictly necessary to port existing daemons to the new style. However, doing so offers additional functionality to the daemons as well as simplifying integration into new-style init systems. To port an existing SysV compatible daemon, the following steps are recommended: 1. If not already implemented, add an optional command line switch to the daemon to disable daemonization. This is useful not only for using the daemon in new-style init systems, but also to ease debugging. 2. If the daemon offers interfaces to other software running on the local system via local `AF_UNIX` sockets, consider implementing socket-based activation (see above). Usually, a minimal patch is sufficient to implement this: Extend the socket creation in the daemon code so that `sd_listen_fds(3)` is checked for already passed sockets first. If sockets are passed (i.e. when `sd_listen_fds()` returns a positive value), skip the socket creation step and use the passed sockets. Secondly, ensure that the file system socket nodes for local `AF_UNIX` sockets used in the socket-based activation are not removed when the daemon shuts down, if sockets have been passed. Third, if the daemon normally closes all remaining open file descriptors as part of its initialization, the sockets passed from the service manager must be spared. Since new-style init systems guarantee that no left-over file descriptors are passed to executed processes, it might be a good choice to simply skip the closing of all remaining open file descriptors if sockets are passed. 3. Write and install a systemd unit file for the service (and the sockets if socket-based activation is used, as well as a path unit file, if the daemon processes a spool directory), see above for details. 4. If the daemon exposes interfaces via D-Bus, write and install a D-Bus activation file for the service, see above for details. # Placing Daemon Data It is recommended to follow the general guidelines for placing package files, as discussed in `file-hierarchy(7)`. # Notes All example codes in this page are licensed under `MIT No Attribution` (SPDX-License-Identifier: MIT-0). # See Also `systemd(1)`, `sd-daemon(3)`, `sd_listen_fds(3)`, `sd_notify(3)`, `daemon(3)`, `systemd.service(5)`, `file-hierarchy(7)` # directives-template systemd systemd.directives 7 systemd.directives Index of configuration directives # Unit directives Directives for configuring units, used in unit files. # Options on the kernel command line Kernel boot options for configuring the behaviour of the systemd process. # SMBIOS Type 11 Variables Data passed from VMM to system via SMBIOS Type 11. # Environment variables Environment variables understood by the systemd manager and other programs and environment variable-compatible settings. # System Credentials System credentials understood by the system and service manager and various other components: # EFI variables EFI variables understood by `systemd-boot(7)` and other programs. # Home Area/User Account directives Directives for configuring home areas and user accounts via `systemd-homed.service(8)`. # UDEV directives Directives for configuring systemd units through the udev database. # Network directives Directives for configuring network links through the net-setup-link udev builtin and networks through systemd-networkd. # Journal fields Fields in the journal events with a well known meaning. # PAM configuration directives Directives for configuring PAM behaviour. # `/etc/crypttab`, `/etc/veritytab` and `/etc/fstab` options Options which influence mounted filesystems and encrypted volumes. # `systemd.nspawn(5)` directives Directives for configuring systemd-nspawn containers. # Program configuration options Directives for configuring the behaviour of the systemd process and other tools through configuration files. # Command line options Command-line options accepted by programs in the systemd suite. # Constants Various constants used and/or defined by systemd. # DNS resource record types # Miscellaneous options and directives Other configuration elements which do not fit in any of the above groups. # Specifiers Short strings which are substituted in configuration directives. # Files and directories Paths and file names referred to in the documentation. # D-Bus interfaces Interfaces exposed over D-Bus. # D-Bus methods Methods exposed in the D-Bus interface. # D-Bus properties Properties exposed in the D-Bus interface. # D-Bus signals Signals emitted in the D-Bus interface. # Colophon # dnssec-trust-anchors.d systemd dnssec-trust-anchors.d 5 dnssec-trust-anchors.d systemd.positive systemd.negative DNSSEC trust anchor configuration files `/etc/dnssec-trust-anchors.d/*.positive`, `/run/dnssec-trust-anchors.d/*.positive`, `/usr/local/lib/dnssec-trust-anchors.d/*.positive`, `/usr/lib/dnssec-trust-anchors.d/*.positive`, `/etc/dnssec-trust-anchors.d/*.negative`, `/run/dnssec-trust-anchors.d/*.negative`, `/usr/local/lib/dnssec-trust-anchors.d/*.negative`, `/usr/lib/dnssec-trust-anchors.d/*.negative` # Description The DNSSEC trust anchor configuration files define positive and negative trust anchors `systemd-resolved.service(8)` bases DNSSEC integrity proofs on. # Positive Trust Anchors Positive trust anchor configuration files contain `DNSKEY` and `DS` resource record definitions to use as base for DNSSEC integrity proofs. See [RFC 4035, Section 4.4](https://tools.ietf.org/html/rfc4035#section-4.4) for more information about DNSSEC trust anchors. Positive trust anchors are read from files with the suffix `.positive` located in `/etc/dnssec-trust-anchors.d/`, `/run/dnssec-trust-anchors.d/` and `/usr/lib/dnssec-trust-anchors.d/`. These directories are searched in the specified order, and a trust anchor file of the same name in an earlier path overrides a trust anchor files in a later path. To disable a trust anchor file shipped in `/usr/lib/dnssec-trust-anchors.d/` it is sufficient to provide an identically-named file in `/etc/dnssec-trust-anchors.d/` or `/run/dnssec-trust-anchors.d/` that is either empty or a symlink to `/dev/null` ("masked"). Positive trust anchor files are simple text files resembling DNS zone files, as documented in [RFC 1035, Section 5](https://tools.ietf.org/html/rfc1035#section-5). One `DS` or `DNSKEY` resource record may be listed per line. Empty lines and lines starting with `#` or `;` are ignored, which may be used for commenting. A `DS` resource record is specified like in the following example: . IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5 The first word specifies the domain, use `.` for the root domain. The domain may be specified with or without trailing dot, which is considered equivalent. The second word must be `IN` the third word `DS`. The following words specify the key tag, signature algorithm, digest algorithm, followed by the hex-encoded key fingerprint. See [RFC 4034, Section 5](https://tools.ietf.org/html/rfc4034#section-5) for details about the precise syntax and meaning of these fields. Alternatively, `DNSKEY` resource records may be used to define trust anchors, like in the following example: . IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0= The first word specifies the domain again, the second word must be `IN`, followed by `DNSKEY`. The subsequent words encode the `DNSKEY` flags, protocol and algorithm fields, followed by the key data encoded in Base64. See [RFC 4034, Section 2](https://tools.ietf.org/html/rfc4034#section-2) for details about the precise syntax and meaning of these fields. If multiple `DS` or `DNSKEY` records are defined for the same domain (possibly even in different trust anchor files), all keys are used and are considered equivalent as base for DNSSEC proofs. Note that `systemd-resolved` will automatically use a built-in trust anchor key for the Internet root domain if no positive trust anchors are defined for the root domain. In most cases it is hence unnecessary to define an explicit key with trust anchor files. The built-in key is disabled as soon as at least one trust anchor key for the root domain is defined in trust anchor files. It is generally recommended to encode trust anchors in `DS` resource records, rather than `DNSKEY` resource records. If a trust anchor specified via a `DS` record is found revoked it is automatically removed from the trust anchor database for the runtime. See [RFC 5011](https://tools.ietf.org/html/rfc5011) for details about revoked trust anchors. Note that `systemd-resolved` will not update its trust anchor database from DNS servers automatically. Instead, it is recommended to update the resolver software or update the new trust anchor via adding in new trust anchor files. The current DNSSEC trust anchor for the Internet's root domain is available at the [IANA Trust Anchor and Keys](https://data.iana.org/root-anchors/root-anchors.xml) page. # Negative Trust Anchors Negative trust anchors define domains where DNSSEC validation shall be turned off. Negative trust anchor files are found at the same location as positive trust anchor files, and follow the same overriding rules. They are text files with the `.negative` suffix. Empty lines and lines whose first character is `;` are ignored. Each line specifies one domain name which is the root of a DNS subtree where validation shall be disabled. For example: # Reverse IPv4 mappings 10.in-addr.arpa 16.172.in-addr.arpa 168.192.in-addr.arpa ... # Some custom domains prod stag Negative trust anchors are useful to support private DNS subtrees that are not referenced from the Internet DNS hierarchy, and not signed. [RFC 7646](https://tools.ietf.org/html/rfc7646) for details on negative trust anchors. If no negative trust anchor files are configured a built-in set of well-known private DNS zone domains is used as negative trust anchors. It is also possible to define per-interface negative trust anchors using the `DNSSECNegativeTrustAnchors=` setting in `systemd.network(5)` files. # See Also `systemd(1)`, `systemd-resolved.service(8)`, `resolved.conf(5)`, `systemd.network(5)` # environment.d systemd environment.d 5 environment.d Definition of user service environment `~/.config/environment.d/*.conf`, `/etc/environment.d/*.conf`, `/run/environment.d/*.conf`, `/usr/local/lib/environment.d/*.conf`, `/usr/lib/environment.d/*.conf`, `/etc/environment` # Description Configuration files in the `environment.d/` directories contain lists of environment variable assignments passed to services started by the systemd user instance. `systemd-environment-d-generator(8)` parses them and updates the environment exported by the systemd user instance. See below for an discussion of which processes inherit those variables. The user-level configuration directory defaults to `~/.config/environment.d/`. If `$XDG_CONFIG_HOME` is set to an absolute path in the user service manager environment (e.g. via PAM or `/etc/environment`), it takes precedence over `~/.config/`. Note that this creates a bootstrapping consideration: variables set in `environment.d/` files, including `$XDG_CONFIG_HOME` itself, are not available when the generator determines which directory to read. It is recommended to use numerical prefixes for file names to simplify ordering. For backwards compatibility, a symlink to `/etc/environment` is installed, so this file is also parsed. # Configuration Format The configuration files contain a list of `KEY=VALUE` environment variable assignments, separated by newlines. The right hand side of these assignments may reference previously defined environment variables, using the `${OTHER_KEY}` and `$OTHER_KEY` format. It is also possible to use `${FOO:-DEFAULT_VALUE}` to expand in the same way as `${FOO}` unless the expansion would be empty, in which case it expands to \, and use `${FOO:+ALTERNATE_VALUE}` to expand to \ as long as `${FOO}` would have expanded to a non-empty value. You can escape a literal dollar sign `$` by doubling it, as in `$$`. A backslash character `\` followed by a newline acts as a line continuation (both characters are discarded); in all other cases, the backslash is consumed and the following character is included literally in the value. This can be used to preserve leading/trailing whitespace or include literal backslashes. You may optionally enclose the right hand side of assignments in pairs of either `'`single quotes`'` or `"`double quotes`"`; these will be stripped from the value before saving it. Using either quoting style does not affect variable expansion; however, single quotes disable backslash escaping entirely, while double quoting removes backslashes that precede double quotes `"`, dollar signs `$`, backslashes `\`, backticks `` ` ``, and newlines, and leaves all other backslashes in place. Leading and trailing whitespace characters are stripped from both the left and right hand sides of the assignment. To preserve such spaces in the value, you can either enclose the entire value in quotes, or escape the space characters with backslashes. You can also include literal newlines in the value by enclosing it in quotes. Each \ must be a valid variable name. Empty lines and lines beginning with the comment characters `#` or `;` are ignored. No other elements of shell syntax are supported. ## Examples
Setup environment to allow access to a program installed in `/opt/foo`
`/etc/environment.d/60-foo.conf`: FOO_DEBUG=force-software-gl,log-verbose PATH=/opt/foo/bin:$PATH LD_LIBRARY_PATH=/opt/foo/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} XDG_DATA_DIRS=/opt/foo/share:${XDG_DATA_DIRS:-/usr/local/share/:/usr/share/}
Escaping and variable expansion
`/etc/environment.d/70-bar.conf`: # A comment test_var=(variable) ; Another comment test_comment=value # This is a part of the variable, and not a comment! test_none= \ before\ after "" '' \${test_var} test_double=" \ before\ after "" '' \${test_var}" test_single=' \ before\ after "" '' \${test_var}' # The above example produces the following environment variables, written using # C-style string escapes: # # test_var="(variable)" # test_comment="value # This is a part of the variable, and not a comment!" # test_none=" beforeafter \"\" '' (variable)" # test_double=" \\ beforeafter '' (variable)" # test_single=" \\ before\\\nafter \"\" \\(variable)"
# Applicability Environment variables exported by the user service manager (`systemd --user` instance started in the `user@uid.service` system service) are passed to any services started by that service manager. In particular, this may include services which run user shells. For example in the GNOME environment, the graphical terminal emulator runs as the `gnome-terminal-server.service` user unit, which in turn runs the user shell, so that shell will inherit environment variables exported by the user manager. For other instances of the shell, not launched by the user service manager, the environment they inherit is defined by the program that starts them. Hint: in general, `systemd.service(5)` units contain programs launched by systemd, and `systemd.scope(5)` units contain programs launched by something else. Note that these files do not affect the environment block of the service manager itself, but exclusively the environment blocks passed to the services it manages. Environment variables set that way thus cannot be used to influence behaviour of the service manager. In order to make changes to the service manager's environment block the environment must be modified before the user's service manager is invoked, for example from the system service manager or via a PAM module. Specifically, for ssh logins, the `sshd(8)` service builds an environment that is a combination of variables forwarded from the remote system and defined by `sshd`, see the discussion in `ssh(1)`. A graphical display session will have an analogous mechanism to define the environment. Note that some managers query the systemd user instance for the exported environment and inject this configuration into programs they start, using `systemctl show-environment` or the underlying D-Bus call. # See Also `systemd(1)`, `systemd-environment-d-generator(8)`, `systemd.environment-generator(7)` # experimental # This option is experimental and subject to change without advance notice. It will be stabilized and given a backward-compatibility guarantee in a future release, but may also possibly be removed. These options are experimental and subject to change without advance notice. They will be stabilized and given a backward-compatibility guarantee in a future release, but may also possibly be removed. This feature is experimental and subject to change without advance notice. It will be stabilized and given a backward-compatibility guarantee in a future release, but may also possibly be removed. # Experimental This component is experimental and subject to change without advance notice. It will be stabilized and given a backward-compatibility guarantee in a future release, but may also possibly be removed. # file-hierarchy systemd file-hierarchy 7 file-hierarchy systemd file system hierarchy requirements # Description Operating systems using the `systemd(1)` system and service manager are organized based on a file system hierarchy inspired by UNIX, as described in [ UAPI.9 Linux File System Hierarchy](https://uapi-group.org/specifications/specs/linux_file_system_hierarchy/). Additional requirements on *when* given parts of the hierarchy must be available during boot are listed in [Mount Requirements](https://systemd.io/MOUNT_REQUIREMENTS/). Many of the paths described here can be queried with the `systemd-path(1)` tool. # See Also `hier(7)`, [File System Hierarchy](http://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html), [XDG Base Directory Specification](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html), [XDG User Directories](https://www.freedesktop.org/wiki/Software/xdg-user-dirs) # homectl systemd homectl 1 homectl systemd-homed-firstboot.service Create, remove, change or inspect home directories homectl OPTIONS COMMAND NAME # Description `homectl` may be used to create, remove, change or inspect a user's home directory. It's primarily a command interfacing with `systemd-homed.service(8)` which manages home directories of users. Home directories managed by `systemd-homed.service` are self-contained, and thus include the user's full metadata record in the home's data storage itself, making them easy to migrate between machines. In particular, a home directory describes a matching user record, and every user record managed by `systemd-homed.service` also implies existence and encapsulation of a home directory. The user account and home directory become the same concept. The following backing storage mechanisms are supported: - An individual LUKS2 encrypted loopback file for a user, stored in `/home/*.home`. At login the file system contained in this files is mounted, after the LUKS2 encrypted volume has been attached. The user's password is identical to the encryption passphrase of the LUKS2 volume. Access to data without preceding user authentication is thus not possible, even for the system administrator. This storage mechanism provides the strongest data security and is thus recommended. - Similar, but the LUKS2 encrypted file system is located on regular block device, such as a USB storage stick. In this mode home directories and all data they include are nicely migratable between machines, simply by plugging the USB stick into different systems at different times. - An encrypted directory using `fscrypt` on file systems that support it (at the moment this is primarily `ext4`), located in `/home/*.homedir`. This mechanism also provides encryption, but substantially weaker than LUKS2, as most file system metadata is unprotected. Moreover it currently does not support changing user passwords once the home directory has been created. - A `btrfs` subvolume for each user, also located in `/home/*.homedir`. This provides no encryption, but good quota support. - A regular directory for each user, also located in `/home/*.homedir`. This provides no encryption, but is a suitable fallback available on all machines, even where LUKS2, `fscrypt` or `btrfs` support is not available. - An individual Windows file share (CIFS) for each user. Note that `systemd-homed.service` and `homectl` will not manage "classic" UNIX user accounts as created with `useradd(8)` or similar tools. In particular, this functionality is not suitable for managing system users (i.e. users with a UID below 1000) but is exclusive to regular ("human") users. Note that users/home directories managed via `systemd-homed.service` do not show up in `/etc/passwd` and similar files, they are synthesized via glibc NSS during runtime. They are thus resolvable and may be enumerated via the `getent(1)` tool. This tool interfaces directly with `systemd-homed.service`, and may execute specific commands on the home directories it manages. Since every home directory managed that way also defines a JSON user and group record these home directories may also be inspected and enumerated via `userdbctl(1)`. Home directories managed by `systemd-homed.service` are usually in one of two states, or in a transition state between them: when `active` they are unlocked and mounted, and thus accessible to the system and its programs; when `inactive` they are not mounted and thus not accessible. Activation happens automatically at login of the user and usually can only complete after a password (or other authentication token) has been supplied. Deactivation happens after the user fully logged out. A home directory remains active as long as the user is logged in at least once, i.e. has at least one login session. When the user logs in a second time simultaneously the home directory remains active. It is deactivated only after the last of the user's sessions ends. # Options The following general options are understood (further options that control the various properties of user records managed by `systemd-homed.service` are documented further down): `--identity=FILE` Read the user's JSON record from the specified file. If passed as `-` read the user record from standard input. The supplied JSON object must follow the structure documented in [JSON User Records](https://systemd.io/USER_RECORD). This option may be used in conjunction with the `create` and `update` commands (see below), where it allows configuring the user record in JSON as-is, instead of setting the individual user record properties (see below). `--json=FORMAT`; `-j` Controls whether to output the user record in JSON format, if the `inspect` command (see below) is used. Takes one of `pretty`, `short` or `off`. If `pretty` human-friendly whitespace and newlines are inserted in the output to make the JSON data more readable. If `short` all superfluous whitespace is suppressed. If `off` (the default) the user information is not shown in JSON format but in a friendly human-readable formatting instead. The `-j` option picks `pretty` when run interactively and `short` otherwise. `--export-format=FORMAT`; `-E`; `-EE` When used with the `inspect` verb in JSON mode (see above) may be used to suppress certain aspects of the JSON user record on output. Specifically, if `stripped` format is used the binding and runtime fields of the record are removed. If `minimal` format is used the cryptographic signature is removed too. If `full` format is used the full JSON record is shown (this is the default). This option is useful for copying an existing user record to a different system in order to create a similar user there with the same settings. Specifically: `homectl inspect -EE | ssh root@othersystem homectl create -i-` may be used as simple command line for replicating a user on another host. `-E` is equivalent to `-j --export-format=stripped`, `-EE` to `-j --export-format=minimal`. Note that when replicating user accounts user records acquired in `stripped` mode will retain the original cryptographic signatures and thus may only be modified when the private key to update them is available on the destination machine. When replicating users in `minimal` mode, the signature is removed during the replication and thus the record will be implicitly signed with the key of the destination machine and may be updated there without any private key replication. `--offline` Do not attempt to update the copy of the user record and blob directory that is embedded inside of the home area. This allows for operation on home areas that are absent, or without needing to authenticate as the user being modified. `--key-name=` When used with the `add-signing-key` command, specify or override the name under which to store the public key being added. The specified name can be chosen freely, but must be suffixed with `.public`. If this option is not used the name is derived from the specified filename. If a key is read from standard input this option is mandatory in order to provide a suitable name for the key being added. `--seize=` Takes a boolean argument. When used with `create` or `register`, controls whether to strip cryptographic signatures from the provided JSON user records, which has the effect of signing them with the local signing key (`local.public`) instead. If this switch is set to true, added user records hence become locally managed (and thus can be modified locally), while if it is set to false the user records remain managed and owned by its origin (and thus cannot be modified locally). This switch defaults to true for `create` and false for `register`. `--prompt-new-user` If used in conjunction with `firstboot` and no regular user account exists on the system so far the tool will interactively query for user information and create an account. `--prompt-shell=` Takes a boolean argument. Controls whether to interactively query for a login shell, if `firstboot --prompt-new-user` is used. Defaults to true. `--prompt-groups=` Takes a boolean argument. Controls whether to interactively query for auxiliary groups to add the new user to, if `firstboot --prompt-new-user` is used. Defaults to true. `--chrome=` Takes a boolean argument. By default the interactive user creation via `firstboot --prompt-new-user` screen will show reverse color "chrome" bars at the top and the bottom of the terminal screen, which may be disabled by setting this option to false. `--mute-console=` Takes a boolean argument. If true kernel log output and service manager status output to the system console is temporarily disabled while `firstboot --prompt-new-user` is running, so that its own output is not interrupted. Defaults to false. `--match=this|other|any|auto`; `-A`; `-N`; `-T` Option `--match=` takes one of `this`, `other`, `any` or `auto`. Some user record settings can be defined to match only specific machines, or all machines but one, or all machines. With this switch it is possibly to control to which machines to apply the settings appearing on the command line after it. If `this` is specified the setting will only apply to the local system (positive match), if `other` it will apply to all but the local system (negative match), if `any` it will apply to all systems (unless there's a matching positive or negative per-machine setting). If `auto` returns to the default logic: whether a setting applies by default to the local system or all systems depends on the option in question. Note that only some user record settings can be conditioned like this. This option has no effect on the others and is ignored there. This option may appear multiple times in a single command line to apply settings conditioned by different matches to the same user record. See [JSON User Records](https://systemd.io/USER_RECORD) for details on which settings may be used with such per-machine matching and which ones may not. `-A` is a shortcut for `--match=any`, `-T` is short for `--match=this` and `-N` is short for `--match=other`. Here's an example call that sets the storage field to `luks` on the local system, but to `cifs` on all others: # homectl update lennart -T --storage=luks -N --storage=cifs # General User Record Properties The following options control various properties of the user records/home directories that `systemd-homed.service` manages. These switches may be used in conjunction with the `create` and `update` commands for configuring various aspects of the home directory and the user account: `--real-name=NAME`; `-c` \ The real name for the user. This corresponds with the GECOS field on classic UNIX NSS records. `--realm=REALM` The realm for the user. The realm associates a user with a specific organization or installation, and allows distinguishing users of the same name defined in different contexts. The realm can be any string that also qualifies as valid DNS domain name, and it is recommended to use the organization's or installation's domain name for this purpose, but this is not enforced nor required. On each system only a single user of the same name may exist, and if a user with the same name and realm is seen it is assumed to refer to the same user while a user with the same name but different realm is considered a different user. Note that this means that two users sharing the same name but with distinct realms are not allowed on the same system. Assigning a realm to a user is optional. `--alias=NAME,NAME…` Additional names for the user. Takes one or more valid UNIX user names, separated by commas. May be used multiple times to define multiple aliases. An alias username may be specified wherever the primary user name may be specified, and resolves to the same user record. `--email-address=EMAIL` Takes an electronic mail address to associate with the user. On log-in the `$EMAIL` environment variable is initialized from this value. `--location=TEXT` Takes location specification for this user. This is free-form text, which might or might not be usable by geo-location applications. Example: `--location="Berlin, Germany"` or `--location="Basement, Room 3a"` `--birth-date=DATE` Takes a birth date for the user in ISO 8601 calendar date format (`YYYY-MM-DD`). The earliest representable year is 1900. If an empty string is passed the birth date is reset to unset. `--icon-name=ICON` Takes an icon name to associate with the user, following the scheme defined by the [Icon Naming Specification](https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html). `--home-dir=PATH`; `-dPATH` Takes a path to use as home directory for the user. Note that this is the directory the user's home directory is mounted to while the user is logged in. This is not where the user's data is actually stored, see `--image-path=` for that. If not specified, defaults to `/home/$USER`. `--uid=UID` Takes a preferred numeric UNIX UID to assign this user. If a user is to be created with the specified UID and it is already taken by a different user on the local system then creation of the home directory is refused. Note though, if after creating the home directory it is used on a different system and the configured UID is taken by another user there, then `systemd-homed` may assign the user a different UID on that system. The specified UID must be outside of the system user range. It is recommended to use the 60001…60513 UID range for this purpose. If not specified, the UID is automatically picked. If the home directory is found to be owned by a different UID when logging in, the home directory and everything underneath it will have its ownership changed automatically before login completes. Note that changing this option for existing home directories generally has no effect on home directories that already have been registered locally (have a local *binding*), as the UID used for an account on the local system is determined when the home directory is first activated on it, and then remains in effect until the home directory is removed. Note that users managed by `systemd-homed` always have a matching group associated with the same name as well as a GID matching the UID of the user. Thus, configuring the GID separately is not permitted. `--member-of=GROUP`; `-G` \ Takes a comma-separated list of auxiliary UNIX groups this user shall belong to. Example: `--member-of=wheel` to provide the user with administrator privileges. Note that `systemd-homed` does not manage any groups besides a group matching the user in name and numeric UID/GID. Thus any groups listed here must be registered independently, for example with `groupadd(8)`. Any non-existent groups are ignored. This option may be used more than once, in which case all specified group lists are combined. If the user is currently a member of a group which is not listed, the user will be removed from the group. `--capability-bounding-set=CAPABILITIES`; `--capability-ambient-set=CAPABILITIES` These options take a space separated list of process capabilities (e.g. `CAP_WAKE_ALARM`, `CAP_BLOCK_SUSPEND`, …) that shall be set in the capability bounding and ambient sets for all the user's sessions. See `capabilities(7)` for details on the capabilities concept. These options may be used more than once, in which case the specified lists are combined. If the parameter begins with a `~` character the effect is inverted: the specified capability is dropped from the specific set. `--access-mode=MODE` Takes a UNIX file access mode written in octal. Configures the access mode of the home directory itself. Note that this is only used when the directory is first created, and the user may change this any time afterwards. Example: `--access-mode=0700` `--umask=MASK` Takes the access mode mask (in octal syntax) to apply to newly created files and directories of the user ("umask"). If set this controls the initial umask set for all login sessions of the user, possibly overriding the system's defaults. `--skel=PATH` Takes a file system path to a directory. Specifies the skeleton directory to initialize the home directory with. All files and directories in the specified path are copied into any newly create home directory. If not specified, defaults to `/etc/skel/`. `--shell=SHELL` Takes a file system path. Specifies the shell binary to execute on terminal logins. If not specified, defaults to `/bin/bash`. `--setenv=VARIABLE[=VALUE]` Takes an environment variable assignment to set for all user processes. May be used multiple times to set multiple environment variables. When `=` and \ are omitted, the value of the variable with the same name in the program environment will be used. Note that a number of other settings also result in environment variables to be set for the user, including `--email=`, `--timezone=` and `--language=`. `--timezone=TIMEZONE` Takes a time zone location name that sets the timezone for the specified user. When the user logs in the `$TZ` environment variable is initialized from this setting. Example: `--timezone=Europe/Amsterdam` will result in the environment variable `TZ=:Europe/Amsterdam`. (`:` is used intentionally as part of the timezone specification, see `tzset(3)`.) `--language=LANG` Takes a comma- or colon-separated list of languages preferred by the user, ordered by descending priority. The `$LANG` and `$LANGUAGE` environment variables are initialized from this value on login, and thus values suitable for these environment variables are accepted here, for example `--language=de_DE.UTF-8`. This option may be used more than once, in which case the language lists are concatenated. `--default-area=AREA` Takes a string identifying a home directory "area" to use as default. Areas are secondary home directories within the primary home directory of a user. When logging in a user can specify the area they wish to log into, which ensures that the `$HOME` environment variable is set to `~/Areas/` suffixed by the area name. For details on the area concept see `pam_systemd_home(8)`. Note that this option just defines the default, which can be overridden at login time. When this option is specified with an empty string as value any previously declared default area is removed from the user record. # Authentication User Record Properties `--ssh-authorized-keys=KEYS` Either takes a SSH authorized key line to associate with the user record or a `@` character followed by a path to a file to read one or more such lines from. SSH keys configured this way are made available to SSH to permit access to this home directory and user record. This option may be used more than once to configure multiple SSH keys. `--pkcs11-token-uri=URI` Takes an RFC 7512 PKCS#11 URI referencing a security token (e.g. YubiKey or PIV smartcard) that shall be able to unlock the user account. The security token URI should reference a security token with exactly one pair of X.509 certificate and private key. A random secret key is then generated, encrypted with the public key of the X.509 certificate, and stored as part of the user record. At login time it is decrypted with the PKCS#11 module and then used to unlock the account and associated resources. See below for an example how to set up authentication with a security token. Instead of a valid PKCS#11 URI, the special strings `list` and `auto` may be specified. If `list` is passed, a brief table of suitable, currently plugged in PKCS#11 hardware tokens is shown, along with their URIs. If `auto` is passed, a suitable PKCS#11 hardware token is automatically selected (this operation will fail if there isn't exactly one suitable token discovered). The latter is a useful shortcut for the most common case where a single PKCS#11 hardware token is plugged in. Note that many hardware security tokens implement both PKCS#11/PIV and FIDO2 with the `hmac-secret` extension (for example: the YubiKey 5 series), as supported with the `--fido2-device=` option below. Both mechanisms are similarly powerful, though FIDO2 is the more modern technology. PKCS#11/PIV tokens have the benefit of being recognizable before authentication and hence can be used for implying the user identity to use for logging in, which FIDO2 does not allow. PKCS#11/PIV devices generally require initialization (i.e. storing a private/public key pair on them, see example below) before they can be used; FIDO2 security tokens generally do not required that, and work out of the box. `--fido2-credential-algorithm=STRING` Specify COSE algorithm used in credential generation. The default value is `es256`. Supported values are `es256`, `rs256` and `eddsa`. `es256` denotes ECDSA over NIST P-256 with SHA-256. `rs256` denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. `eddsa` denotes EDDSA over Curve25519 with SHA-512. Note that your authenticator may choose not to support some algorithms. `--fido2-device=PATH` Takes a path to a Linux `hidraw` device (e.g. `/dev/hidraw1`), referring to a FIDO2 security token implementing the `hmac-secret` extension that shall be able to unlock the user account. A random salt value is generated on the host and passed to the FIDO2 device, which calculates a HMAC hash of the salt using an internal secret key. The result is then used as the key to unlock the user account. The random salt is included in the user record, so that whenever authentication is needed it can be passed to the FIDO2 token again. Instead of a valid path to a FIDO2 `hidraw` device the special strings `list` and `auto` may be specified. If `list` is passed, a brief table of suitable discovered FIDO2 devices is shown. If `auto` is passed, a suitable FIDO2 token is automatically selected, if exactly one is discovered. The latter is a useful shortcut for the most common case where a single FIDO2 hardware token is plugged in. Note that FIDO2 devices suitable for this option must implement the `hmac-secret` extension. Most current devices (such as the YubiKey 5 series) do. If the extension is not implemented the device cannot be used for unlocking home directories. The FIDO2 device may be subsequently removed by setting the device path to an empty string (e.g. `homectl update $USER --fido2-device=""`). Note that many hardware security tokens implement both FIDO2 and PKCS#11/PIV (and thus may be used with either `--fido2-device=` or `--pkcs11-token-uri=`), for a discussion see above. `--fido2-with-client-pin=BOOL` When enrolling a FIDO2 security token, controls whether to require the user to enter a PIN when unlocking the account (the FIDO2 `clientPin` feature). Defaults to `yes`. (Note: this setting is without effect if the security token does not support the `clientPin` feature at all, or does not allow enabling or disabling it.) `--fido2-with-user-presence=BOOL` When enrolling a FIDO2 security token, controls whether to require the user to verify presence (tap the token, the FIDO2 `up` feature) when unlocking the account. Defaults to `yes`. (Note: this setting is without effect if the security token does not support the `up` feature at all, or does not allow enabling or disabling it.) `--fido2-with-user-verification=BOOL` When enrolling a FIDO2 security token, controls whether to require user verification when unlocking the account (the FIDO2 `uv` feature). Defaults to `no`. (Note: this setting is without effect if the security token does not support the `uv` feature at all, or does not allow enabling or disabling it.) `--recovery-key=BOOL` Accepts a boolean argument. If enabled a recovery key is configured for the account. A recovery key is a computer generated access key that may be used to regain access to an account if the password has been forgotten or the authentication token lost. The key is generated and shown on screen, and should be printed or otherwise transferred to a secure location. A recovery key may be entered instead of a regular password to unlock the account. `--recovery-key-file=PATH` Attempts to write the generated recovery key to the specified file. The file is created with access mode `0600` and must not exist yet. This option may only be used together with `--recovery-key=yes`. If the file cannot be written, a warning is shown and the account operation still succeeds. The recovery key is always shown on screen. # Blob Directory User Record Properties `--blob=PATH`; `-b` \; `--blob=FILENAME=PATH`; `-b` \=\ Accepts either a directory path, or a file name followed by a file path. If just a directory path is specified, then the user's entire blob directory is replaced the specified path. Note that this replacement is performed before per-file manipulations are applied, which means these per-file manipulations will be applied on top of the specified directory. If a filename and file path are specified, then the single specified blob file will be overwritten with the specified path. If completely blank, the entire blob directory is emptied out (which also resets all previous blob-related flags up to this point). If a filename is specified but the corresponding path is blank, that single file will be deleted from the blob directory. All changes are performed in temporary copies of the specified files in directories, which means that the originals specified on the command line are not modified. See [User Record Blob Directories](https://systemd.io/USER_RECORD_BLOB_DIRS) for more information about blob directories. `--avatar=PATH`; `--login-background=PATH` Accept a file path. If set, the specified file is used to overwrite the corresponding file in the user's blob directory. If blank, the corresponding file is deleted from the blob directory. Essentially, these options are shortcuts to `--blob=FILENAME=PATH` for the known filenames defined in [User Record Blob Directories](https://systemd.io/USER_RECORD_BLOB_DIRS). # Account Management User Record Properties `--locked=BOOLEAN` Takes a boolean argument. Specifies whether this user account shall be locked. If true logins into this account are prohibited, if false (the default) they are permitted (of course, only if authorization otherwise succeeds). `--not-before=TIMESTAMP`; `--not-after=TIMESTAMP` These options take a timestamp string, in the format documented in `systemd.time(7)` and configures points in time before and after logins into this account are not permitted. `--rate-limit-interval=SECS`; `--rate-limit-burst=NUMBER` Configures a rate limit on authentication attempts for this user. If the user attempts to authenticate more often than the specified number, on a specific system, within the specified time interval authentication is refused until the time interval passes. Defaults to 10 times per 1min. `--password-hint=TEXT` Takes a password hint to store alongside the user record. This string is stored accessible only to privileged users and the user itself and may not be queried by other users. Example: `--password-hint="My first pet's name"`. `--enforce-password-policy=BOOL`; `-P` Takes a boolean argument. Configures whether to enforce the system's password policy for this user, regarding quality and strength of selected passwords. Defaults to on. `-P` is short for `--enforce-password-policy=no`. `--password-change-now=BOOL` Takes a boolean argument. If true the user is asked to change their password on next login. `--password-change-min=TIME`; `--password-change-max=TIME`; `--password-change-warn=TIME`; `--password-change-inactive=TIME` Each of these options takes a time span specification as argument (in the syntax documented in `systemd.time(7)`) and configures various aspects of the user's password expiration policy. Specifically, `--password-change-min=` configures how much time has to pass after changing the password of the user until the password may be changed again. If the user tries to change their password before this time passes the attempt is refused. `--password-change-max=` configures how soon after it has been changed the password expires and needs to be changed again. After this time passes logging in may only proceed after the password is changed. `--password-change-warn=` specifies how much earlier than then the time configured with `--password-change-max=` the user is warned at login to change their password as it will expire soon. Finally, `--password-change-inactive=` configures the time which has to pass after the password as expired until the user is not permitted to log in or change the password anymore. Note that these options only apply to password authentication, and do not apply to other forms of authentication, for example PKCS#11-based security token authentication. # Resource Management User Record Properties `--disk-size=BYTES` Either takes a size in bytes as argument (possibly using the usual K, M, G, … suffixes for 1024 base values), a percentage value, or the special strings `min` or `max`, and configures the disk space to assign to the user. If a percentage value is specified (i.e. the argument suffixed with `%`) it is taken relative to the available disk space of the backing file system. If specified as `min` assigns the minimal disk space permitted by the constraints of the backing file system and other limits, when specified as `max` assigns the maximum disk space available. If the LUKS2 backend is used this configures the size of the loopback file and file system contained therein. For the other storage backends configures disk quota using the filesystem's native quota logic, if available. If not specified, defaults to 85% of the available disk space for the LUKS2 backend and to no quota for the others. `--nice=NICE` Takes the numeric scheduling priority ("nice level") to apply to the processes of the user at login time. Takes a numeric value in the range -20 (highest priority) to 19 (lowest priority). `--rlimit=LIMIT=VALUE:VALUE` Allows configuration of resource limits for processes of this user, see `getrlimit(2)` for details. Takes a resource limit name (e.g. `LIMIT_NOFILE`) followed by an equal sign, followed by a numeric limit. Optionally, separated by colon a second numeric limit may be specified. If two are specified this refers to the soft and hard limits, respectively. If only one limit is specified the setting sets both limits in one. `--tasks-max=TASKS` Takes a non-zero unsigned integer as argument. Configures the maximum number of tasks (i.e. threads, where each process is at least one thread) the user may have at any given time. This limit applies to all tasks forked off the user's sessions, even if they change user identity via `su(1)` or a similar tool. Use `--rlimit=LIMIT_NPROC=` to place a limit on the tasks actually running under the UID of the user, thus excluding any child processes that might have changed user identity. This controls the `TasksMax=` setting of the per-user systemd slice unit `user-$UID.slice`. See `systemd.resource-control(5)` for further details. `--memory-high=BYTES`; `--memory-max=BYTES` Set a limit on the memory a user may take up on a system at any given time in bytes (the usual K, M, G, … suffixes are supported, to the base of 1024). This includes all memory used by the user itself and all processes they forked off that changed user credentials. This controls the `MemoryHigh=` and `MemoryMax=` settings of the per-user systemd slice unit `user-$UID.slice`. See `systemd.resource-control(5)` for further details. `--cpu-weight=WEIGHT`; `--io-weight=WEIGHT` Set CPU and IO scheduling weights of the processes of the user, including those of processes forked off by the user that changed user credentials. Takes a numeric value in the range 1…10000. This controls the `CPUWeight=` and `IOWeight=` settings of the per-user systemd slice unit `user-$UID.slice`. See `systemd.resource-control(5)` for further details. # Storage User Record Properties `--tmp-limit=BYTES`; `--tmp-limit=PERCENT`; `--dev-shm-limit=BYTES`; `--dev-shm-limit=PERCENT` Controls the per-user quota on `/tmp/` and `/dev/shm/` that is applied when the user logs in. Takes either an absolute value in bytes (with the usual K, M, G, T suffixes to the base of 1024), or a percentage. In the latter case the limit is applied relative to the size of the respective file system. This limit is only applied if the relevant file system is `tmpfs` and has no effect otherwise. Note that if these options are not used, a default quota might still be enforced (typically 80%.) `--storage=STORAGE` Selects the storage mechanism to use for this home directory. Takes one of `luks`, `fscrypt`, `directory`, `subvolume`, `cifs`. For details about these mechanisms, see above. If a new home directory is created and the storage type is not specifically specified, `homed.conf(5)` defines which default storage to use. `--image-path=PATH` Takes a file system path. Configures where to place the user's home directory. When LUKS2 storage is used refers to the path to the loopback file, otherwise to the path to the home directory (which may be in `/home/` or any other accessible filesystem). When unspecified defaults to `/home/$USER.home` when LUKS storage is used and `/home/$USER.homedir` for the other storage mechanisms. Not defined for the `cifs` storage mechanism. To use LUKS2 storage on a regular block device (for example a USB stick) pass the path to the block device here. Specifying the path to a directory here when using LUKS2 storage is not allowed. Similar, specifying the path to a regular file or device node is not allowed if any of the other storage backends are used. `--drop-caches=BOOL` Automatically flush OS file system caches on logout. This is useful in combination with the fscrypt storage backend to ensure the OS does not keep decrypted versions of the files and directories in memory (and accessible) after logout. This option is also supported on other backends, but should not bring any benefit there. Defaults to off, except if the selected storage backend is fscrypt, where it defaults to on. Note that flushing OS caches will negatively influence performance of the OS shortly after logout. # LUKS Storage User Record Properties `--fs-type=TYPE` When LUKS2 storage is used configures the file system type to use inside the home directory LUKS2 container. One of `btrfs`, `ext4`, `xfs`. If not specified `homed.conf(5)` defines which default file system type to use. Note that `xfs` is not recommended as its support for file system resizing is too limited. `--luks-discard=BOOL` When LUKS2 storage is used configures whether to enable the `discard` feature of the file system. If enabled the file system on top of the LUKS2 volume will report empty block information to LUKS2 and the loopback file below, ensuring that empty space in the home directory is returned to the backing file system below the LUKS2 volume, resulting in a "sparse" loopback file. This option mostly defaults to off, since this permits over-committing home directories which results in I/O errors if the underlying file system runs full while the upper file system wants to allocate a block. Such I/O errors are generally not handled well by file systems nor applications. When LUKS2 storage is used on top of regular block devices (instead of on top a loopback file) the discard logic defaults to on. `--luks-offline-discard=BOOL` Similar to `--luks-discard=`, controls the trimming of the file system. However, while `--luks-discard=` controls what happens when the home directory is active, `--luks-offline-discard=` controls what happens when it becomes inactive, i.e. whether to trim/allocate the storage when deactivating the home directory. This option defaults to on, to ensure disk space is minimized while a user is not logged in. `--luks-extra-mount-options=OPTIONS` Takes a string containing additional mount options to use when mounting the LUKS volume. If specified, this string will be appended to the default, built-in mount options. Defaults to "compress=zstd:1,noacl,user_subvol_rm_allowed". `--luks-cipher=CIPHER`; `--luks-cipher-mode=MODE`; `--luks-volume-key-size=BYTES`; `--luks-pbkdf-type=TYPE`; `--luks-pbkdf-hash-algorithm=ALGORITHM`; `--luks-pbkdf-force-iterations=ITERATIONS`; `--luks-pbkdf-time-cost=SECONDS`; `--luks-pbkdf-memory-cost=BYTES`; `--luks-pbkdf-parallel-threads=THREADS`; `--luks-sector-size=BYTES` Configures various cryptographic parameters for the LUKS2 storage mechanism. See `cryptsetup(8)` for details on the specific attributes. Note that `homectl` uses bytes for key size, like `/proc/crypto`, but `cryptsetup(8)` uses bits. `--auto-resize-mode=` Configures whether to automatically grow and/or shrink the backing file system on login and logout. Takes one of the strings `off`, `grow`, `shrink-and-grow`. Only applies to the LUKS2 backend currently, and if the btrfs file system is used inside it (since only then online growing/shrinking of the file system is supported). Defaults to `shrink-and-grow`, if LUKS2/btrfs is used, otherwise is off. If set to `off` no automatic shrinking/growing during login or logout is done. If set to `grow` the home area is grown to the size configured via `--disk-size=` should it currently be smaller. If it already matches the configured size or is larger no operation is executed. If set to `shrink-and-grow` the home area is also resized during logout to the minimal size the used disk space and file system constraints permit. This mode thus ensures that while a home area is activated it is sized to the configured size, but while deactivated it is compacted taking up only the minimal space possible. Note that if the system is powered off abnormally or if the user otherwise not logged out cleanly the shrinking operation will not take place, and the user has to re-login/logout again before it is executed again. `--rebalance-weight=` Configures the weight parameter for the free disk space rebalancing logic. Only applies to the LUKS2 backend (since for the LUKS2 backend disk space is allocated from a per-user loopback file system instead of immediately from a common pool like the other backends do it). In regular intervals free disk space in the active home areas and their backing storage is redistributed among them, taking the weight value configured here into account. Expects an integer in the range 1…10000, or the special string `off`. If not specified, defaults to 100. The weight is used to scale free space made available to the home areas: a home area with a weight of 200 will get twice the free space as one with a weight of 100; a home area with a weight of 50 will get half of that. The backing file system will be assigned space for a weight of 20. If set to `off` no automatic free space distribution is done for this home area. Note that resizing the home area explicitly (with `homectl resize` see below) will implicitly turn off the automatic rebalancing. To reenable the automatic rebalancing use `--rebalance-weight=` with an empty parameter. # Mounting User Record Properties `--nosuid=BOOL`; `--nodev=BOOL`; `--noexec=BOOL` Configures the `nosuid`, `nodev` and `noexec` mount options for the home directories. By default, `nodev` and `nosuid` are on, while `noexec` is off. For details about these mount options see `mount(8)`. # CIFS User Record Properties `--cifs-domain=DOMAIN`; `--cifs-user-name=USER`; `--cifs-service=SERVICE`; `--cifs-extra-mount-options=OPTIONS` Configures the Windows File Sharing (CIFS) domain and user to associate with the home directory/user account, as well as the file share ("service") to mount as directory. The latter is used when `cifs` storage is selected. The file share should be specified in format `//host/share/directory/…`. The directory part is optional — if not specified, the home directory will be placed in the top-level directory of the share. The `--cifs-extra-mount-options=` setting allows specifying additional mount options when mounting the share, see `mount.cifs(8)` for details. # Login Behaviour Record Properties `--stop-delay=SECS` Configures the time the per-user service manager shall continue to run after the all sessions of the user ended. The default is configured in `logind.conf(5)` (for home directories of LUKS2 storage located on removable media this defaults to 0 though). A longer time makes sure quick, repetitive logins are more efficient as the user's service manager does not have to be started every time. `--kill-processes=BOOL` Configures whether to kill all processes of the user on logout. The default is configured in `logind.conf(5)`. `--auto-login=BOOL` Takes a boolean argument. Configures whether the graphical UI of the system should automatically log this user in if possible. Defaults to off. If less or more than one user is marked this way automatic login is disabled. `--session-launcher=LAUNCHER` Takes a string argument. Configures the user's preferred session launcher .desktop entry file (i.e. `gnome`, `plasma`, or other names that appear in `/usr/share/xesssions/` or `/usr/share/wayland-sessions`). This is read by the display manager to pick the default session that is launched when the user logs in. `--session-type=TYPE` Takes a string argument. Configures the user's preferred session type (i.e. `x11`, `wayland`, and other values accepted by `$XDG_SESSION_TYPE`). This is read by the display manage to pick the default session type the user is logged into. # Commands The following commands are understood: `list` List all home directories (along with brief details) currently managed by `systemd-homed.service`. This command is also executed if none is specified on the command line. (Note that the list of users shown by this command does not include users managed by other subsystems, such as system users or any traditional users listed in `/etc/passwd`.) `activate` \ \[\\] Activate one or more home directories. The home directories of each listed user will be activated and made available under their mount points (typically in `/home/$USER`). Note that any home activated this way stays active indefinitely, until it is explicitly deactivated again (with `deactivate`, see below), or the user logs in and out again and it thus is deactivated due to the automatic deactivation-on-logout logic. Activation of a home directory involves various operations that depend on the selected storage mechanism. If the LUKS2 mechanism is used, this generally involves: inquiring the user for a password, setting up a loopback device, validating and activating the LUKS2 volume, checking the file system, mounting the file system, and potentially changing the ownership of all included files to the correct UID/GID. `deactivate` \ \[\\] Deactivate one or more home directories. This undoes the effect of `activate`. `inspect` \ \[\\] Show various details about the specified home directories. This shows various information about the home directory and its user account, including runtime data such as current state, disk use and similar. Combine with `--json=` to show the detailed JSON user record instead, possibly combined with `--export-format=` to suppress certain aspects of the output. `authenticate` \ \[\\] Validate authentication credentials of a home directory. This queries the caller for a password (or similar) and checks that it correctly unlocks the home directory. This leaves the home directory in the state it is in, i.e. it leaves the home directory in inactive state if it was inactive before, and in active state if it was active before. `create` \; `create` `--identity=PATH` \[\\] Create a new home directory/user account of the specified name. Use the various user record property options (as documented above) to control various aspects of the home directory and its user accounts. The specified user name should follow the strict syntax described on [User/Group Name Syntax](https://systemd.io/USER_NAMES). `adopt` \ \[\…\] Adopts one or more existing home directories on the local system. Takes one or more paths to `*.home` LUKS home directories or `*.homedir/` standalone home directories or subvolumes previously created by `systemd-homed` and makes them available locally for login. The referenced files are not moved. This is an alternative for moving such home directories into `/home/` (where they would be picked up automatically). `register` \ \[\…\] Registers one or more users, without creating their home directories. Takes one or more paths to JSON user record files. If the path is specified as `-` reads the JSON user record from standard input. Registering a user makes it accessible on the local system without creating a new home directory. This is particularly useful for making a user accessible on a system it was not originally created on. Here's an example how to make a local user account with its home directory accessible on a remote system, using SMB/CIFS file sharing. With Samba installed in its default configuration invoke as `root`: # smbpasswd -a lennart Continue as regular user `lennart`: $ homectl update lennart --ssh-authorized-keys=… -N --storage=cifs --cifs-service="//$HOSTNAME/lennart" $ homectl get-signing-key | ssh targetsystem homectl add-signing-key --key-name="$HOSTNAME".public $ homectl inspect -E lennart | ssh targetsystem homectl register - $ ssh lennart@targetsystem This first ensures the user account `lennart` is known to and accessible by Samba. It then registers a local SSH access that shall be used for accessing this user, and configures CIFS as default storage for non-local systems on the account. It then adds the local system's account signing key to the target system. Then it registers the local user account with the target system. Finally it logs into the account on the target system. The target system will then connect back via SMB/CIFS to access the home directory. `unregister` \… Unregisters one or more user accounts. This only removes the user record from the local system, it does not delete the home directory. The home directory can be readded via the `register` or `adopt` command later, on this or another system. Note that unregistering a user whose home directory is placed in `/home/` will not make the user disappear from the local user database, as all supported home directories placed there will show up in the user database. However, the user record will become "unfixated", i.e. lose its binding to the local system. When logged into it will automatically regain the binding, and acquire a local UID/GID pair. `remove` \ Remove a home directory/user account. This will remove both the home directory's user record and the home directory itself, and thus delete all files and directories owned by the user. `update` \; `update` `--identity=PATH` \[\\] Update a home directory/user account. Use the various user record property options (as documented above) to make changes to the account, or alternatively provide a full, updated JSON user record via the `--identity=` option. Note that changes to user records not signed by a cryptographic private key available locally are not permitted, unless `--identity=` is used with a user record that is already correctly signed by a recognized private key. `passwd` \ Change the password of the specified home directory/user account. `resize` \ \ Change the disk space assigned to the specified home directory. If the LUKS2 storage mechanism is used this will automatically resize the loopback file and the file system contained within. Note that if `ext4` is used inside of the LUKS2 volume, it is necessary to deactivate the home directory before shrinking it (i.e the user has to log out). Growing can be done while the home directory is active. If `xfs` is used inside of the LUKS2 volume the home directory may not be shrunk whatsoever. On all three of `ext4`, `xfs` and `btrfs` the home directory may be grown while the user is logged in, and on the latter also shrunk while the user is logged in. If the `subvolume`, `directory`, `fscrypt` storage mechanisms are used, resizing will change file system quota. The size parameter may make use of the usual suffixes B, K, M, G, T (to the base of 1024). The special strings `min` and `max` may be specified in place of a numeric size value, for minimizing or maximizing disk space assigned to the home area, taking constraints of the file system, disk usage inside the home area and on the backing storage into account. `lock` \ Temporarily suspend access to the user's home directory and remove any associated cryptographic keys from memory. Any attempts to access the user's home directory will stall until the home directory is unlocked again (i.e. re-authenticated). This functionality is primarily intended to be used during system suspend to make sure the user's data cannot be accessed until the user re-authenticates on resume. This operation is only defined for home directories that use the LUKS2 storage mechanism. `unlock` \ Resume access to the user's home directory again, undoing the effect of `lock` above. This requires authentication of the user, as the cryptographic keys required for access to the home directory need to be reacquired. `lock-all` Execute the `lock` command on all suitable home directories at once. This operation is generally executed on system suspend (i.e. by `systemctl suspend` and related commands), to ensure all active user's cryptographic keys for accessing their home directories are removed from memory. `deactivate-all` Execute the `deactivate` command on all active home directories at once. This operation is generally executed on system shut down (i.e. by `systemctl poweroff` and related commands), to ensure all active user's home directories are fully deactivated before `/home/` and related file systems are unmounted. `with` \ \ Activate the specified user's home directory, run the specified command (under the caller's identity, not the specified user's) and deactivate the home directory afterwards again (unless the user is logged in otherwise). This command is useful for running privileged backup scripts and such, but requires authentication with the user's credentials in order to be able to unlock the user's home directory. `rebalance` Rebalance free disk space between active home areas and the backing storage. See `--rebalance-weight=` above. This executes no operation unless there's at least one active LUKS2 home area that has disk space rebalancing enabled. This operation is synchronous: it will only complete once disk space is rebalanced according to the rebalancing weights. Note that rebalancing also takes place automatically in the background in regular intervals. Use this command to synchronously ensure disk space is properly redistributed before initiating an operation requiring large amounts of disk space. `firstboot` This command is supposed to be invoked during the initial boot of the system. It checks whether any regular home area exists so far, and if not queries the user interactively on the console for user name and password and creates one (only if `--prompt-new-user` is specified). Alternatively, if one or more service credentials whose name starts with `home.create.` are passed to the command (containing a user record in JSON format) these users are automatically created at boot. This command is invoked by the `systemd-homed-firstboot.service` service unit. `list-signing-keys` Show a list of public keys that home directories can be signed with to be allowed for local login. One such key (`local.public`) will be generated automatically for signing locally created home directories, but additional public keys may be registered to accept home directories from other origins too (see `add-signing-key` below). `get-signing-key` \[\\] Write the public key identified by the specified name to standard output (in PEM format). If no name is specified defaults to `local.public`, i.e. the automatically generated key for locally created home directories. `add-signing-key` \[\\] Add public key(s) from the specified PEM key file(s) to the list of keys that home areas have to be signed by to be permitted for local login. If a path of `-` is specified, or if no file is specified at all, the key will be read from standard input. The key file name(s) must carry the `.public` suffix, and the file name(s) will be used to name the key(s) once added, too. If a key is added from standard input the key name must be specified explicitly via `--key-name=`, see above. This command is useful for permitting local home directories to be used on a remote system. Example: homectl get-signing-key | ssh myotherhost homectl add-signing-key --key-name="$HOSTNAME".public `remove-signing-key` \ Remove the public key identified by the specified name from the list of keys that control from which origins to permit home directories for login. # Credentials When invoked with the `firstboot` command, `homectl` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `home.create.*` If one or more credentials whose names begin with `home.create.`, followed by a valid UNIX username are passed, a new home area is created, one for each specified user record. # Kernel Command Line `systemd.firstboot=` This boolean will disable the effect of `homectl firstboot` command. It's primarily interpreted by `systemd-firstboot(1)`. # Exit status On success, 0 is returned, a non-zero failure code otherwise. When a command is invoked with `with`, the exit status of the child is propagated. Effectively, `homectl` will exit without error if the command is successfully invoked *and* finishes successfully. # Examples
Create a user `waldo` in the administrator group `wheel`, and assign 500 MiB disk space to them.
homectl create waldo --real-name="Waldo McWaldo" -G wheel --disk-size=500M
Create a user `wally` on a USB stick, and assign a maximum of 500 concurrent tasks to them.
homectl create wally --real-name="Wally McWally" --image-path=/dev/disk/by-id/usb-SanDisk_Ultra_Fit_476fff954b2b5c44-0:0 --tasks-max=500
Change nice level of user `odlaw` to +5 and make sure the environment variable `$SOME` is set to the string `THING` for them on login.
homectl update odlaw --nice=5 --setenv=SOME=THING
Set up authentication with a YubiKey security token using PKCS#11/PIV:
# Clear the Yubikey from any old keys (careful!) ykman piv reset # Generate a new private/public key pair on the device, store the public key in 'pubkey.pem'. ykman piv generate-key -a RSA2048 9d pubkey.pem # Create a self-signed certificate from this public key, and store it on the device. ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem # We do not need the public key on disk anymore rm pubkey.pem # Allow the security token to unlock the account of user 'lafcadio'. homectl update lafcadio --pkcs11-token-uri=auto
Set up authentication with a FIDO2 security token:
# Allow a FIDO2 security token to unlock the account of user 'nihilbaxter'. homectl update nihilbaxter --fido2-device=auto
Add a recovery key to an existing user account:
# Generate and add a recovery key for user 'emily'. homectl update emily --recovery-key=yes
# See Also `systemd(1)`, `systemd-homed.service(8)`, `homed.conf(5)`, `userdbctl(1)`, `useradd(8)`, `cryptsetup(8)` # homed.conf systemd homed.conf 5 homed.conf homed.conf.d Home area/user account manager configuration files `/etc/systemd/homed.conf`, `/run/systemd/homed.conf`, `/usr/local/lib/systemd/homed.conf`, `/usr/lib/systemd/homed.conf`, `/etc/systemd/homed.conf.d/*.conf`, `/run/systemd/homed.conf.d/*.conf`, `/usr/local/lib/systemd/homed.conf.d/*.conf`, `/usr/lib/systemd/homed.conf.d/*.conf` # Description These configuration files control default parameters for home areas/user accounts created and managed by `systemd-homed.service(8)`. # Options The following options are available in the \[Home\] section: `DefaultStorage=` The default storage to use for home areas. Takes one of `luks`, `fscrypt`, `directory`, `subvolume`, `cifs`. For details about these options, see `homectl(1)`. If not configured or assigned the empty string, the default storage is automatically determined: if not running in a container environment and `/home/` is not itself encrypted, defaults to `luks`. Otherwise, defaults to `subvolume` if `/home/` is on a btrfs file system, and `directory` otherwise. Note that the storage selected on the `homectl` command line always takes precedence. `DefaultFileSystemType=` When using `luks` as storage (see above), selects the default file system to use inside the user's LUKS volume. Takes one of `btrfs`, `ext4` or `xfs`. If not specified, defaults to `btrfs`. This setting has no effect if a different storage mechanism is used. The file system type selected on the `homectl` command line always takes precedence. # See Also `systemd(1)`, `systemd-homed.service(8)` # hostnamectl systemd hostnamectl 1 hostnamectl Control the system hostname hostnamectl OPTIONS COMMAND # Description `hostnamectl` may be used to query and change the system hostname and related settings. `systemd-hostnamed.service(8)` and this tool distinguish three different hostnames: the high-level "pretty" hostname which might include all kinds of special characters (e.g. "Lennart's Laptop"), the "static" hostname which is the user-configured hostname (e.g. "lennarts-laptop"), and the transient hostname which is a fallback value received from network configuration (e.g. "node12345678"). If a static hostname is set to a valid value, then the transient hostname is not used. Note that the pretty hostname has little restrictions on the characters and length used, while the static and transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at maximum (the latter being a Linux limitation). Use `systemd-firstboot(1)` to initialize the system hostname for mounted (but not booted) system images. # Commands The following commands are understood: `status` Show system hostname and related information. If no command is specified, this is the implied default. `hostname` \[\\] If no argument is given, print the system hostname. If an optional argument \ is provided then the command changes the system hostname to \. By default, this will alter the pretty, the static, and the transient hostname alike; however, if one or more of `--static`, `--transient`, `--pretty` are used, only the selected hostnames are changed. If the pretty hostname is being set, and static or transient are being set as well, the specified hostname will be simplified in regards to the character set used before the latter are updated. This is done by removing special characters and spaces. This ensures that the pretty and the static hostname are always closely related while still following the validity rules of the specific name. This simplification of the hostname string is not done if only the transient and/or static hostnames are set, and the pretty hostname is left untouched. The static and transient hostnames must each be either a single DNS label (a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the format allowed for DNS domain name labels), or a sequence of such labels separated by single dots that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux limitation (DNS allows longer names). `icon-name` \[\\] If no argument is given, print the icon name of the system. If an optional argument \ is provided then the command changes the icon name to \. The icon name is used by some graphical applications to visualize this host. The icon name should follow the [Icon Naming Specification](https://specifications.freedesktop.org/icon-naming/latest). `chassis` \[\\] If no argument is given, print the chassis type. If an optional argument \ is provided then the command changes the chassis type to \. The chassis type is used by some graphical applications to visualize the host or alter user interaction. Currently, the following chassis types are defined: `desktop`, `laptop`, `convertible`, `server`, `tablet`, `handset`, `watch`, `embedded`, as well as the special chassis types `vm` and `container` for virtualized systems that lack an immediate physical chassis. `deployment` \[\\] If no argument is given, print the deployment environment. If an optional argument \ is provided then the command changes the deployment environment to \. Argument \ must be a single word without any control characters. One of the following is suggested: `development`, `integration`, `staging`, `production`. `location` \[\\] If no argument is given, print the location string for the system. If an optional argument \ is provided then the command changes the location string for the system to \. Argument \ should be a human-friendly, free-form string describing the physical location of the system, if it is known and applicable. This may be as generic as `Berlin, Germany` or as specific as `Left Rack, 2nd Shelf`. `tags` \[\…\] If no argument is given, print the machine tags currently configured, as a colon-separated list. If one or more \ arguments are provided then the command replaces the configured tags with the specified ones. Each argument may itself be a colon-separated list of tags, so that the tags may be specified either as multiple arguments or as a single colon-separated argument, or any combination thereof. Duplicate tags are removed and the resulting list is sorted before being stored. To remove all tags, invoke the command with a single empty string argument. Alternatively, each argument may be prefixed with `+` or `-` to incrementally update the configured tags rather than replacing them: an argument prefixed with `+` adds all of its (colon-separated) tags to the list, one prefixed with `-` specifies a removal pattern. For example, `hostnamectl tags +foo:bar -quux:ooo=*` adds the tags `foo` and `bar` and removes `quux` and any assignment of `ooo=`. The prefix applies to the whole argument, i.e. to every tag listed within it. Adding a `key=value` tag replaces any value previously assigned to the same key. Prefixed and unprefixed arguments may not be combined in a single invocation. Removal patterns may use shell-style globbing to remove any matching tags, `glob(7)`. If `--apply` is specified, no \ arguments may be given. Instead, `systemd-hostnamed` is asked to apply the tag configuration declared in the `machine-tags.d/` directories, see `machine-tags.d(5)`. Machine tags are short labels that may be used to classify and group machines for management purposes, for example to identify the role a machine plays in a deployment, the fleet or organizational unit it belongs to, or any other administrator-defined attribute. Each individual tag must be 1…255 characters long and consist only of ASCII alphanumeric characters, `-`, `.` and `=`. A tag may optionally be parameterized with a value, in the form `key=value`, in which case the same key may not be assigned more than one distinct value. The tags are stored in the `TAGS=` field of `/etc/machine-info`; see `machine-info(5)` for details. They may also be matched against with the `ConditionMachineTag=`/`AssertMachineTag=` unit settings, see `systemd.unit(5)`. # Options The following options are understood: `--static`; `--transient`; `--pretty` If `status` is invoked (or no explicit command is given) and one of these switches is specified, `hostnamectl` will print out just this selected hostname. This selection does not apply to JSON output: with `--json=`, `status` always prints the full status object. If used with `hostname`, only the selected hostnames will be updated. When more than one of these switches are specified, all the specified hostnames will be updated. `--apply` When used with `tags`, ask `systemd-hostnamed` to apply the tag configuration from the `machine-tags.d/` directories instead of setting the tags specified on the command line. See `machine-tags.d(5)` and the description of the `tags` command above. When this option is used, tags to apply cannot be listed on the command line. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `hostname(1)`, `hostname(5)`, `machine-info(5)`, `machine-tags.d(5)`, `systemctl(1)`, `systemd-hostnamed.service(8)`, `systemd-firstboot(1)` # hwdb systemd hwdb 7 hwdb Hardware Database # Description The hardware database is a key-value store for associating modalias-like keys to udev-property-like values. It is used primarily by udev to add the relevant properties to matching devices, but it can also be queried directly. # Hardware Database Files The hwdb files are read from the files located in the system hwdb directory `/usr/lib/udev/hwdb.d` and the local administration directory `/etc/udev/hwdb.d`. All hwdb files are collectively sorted and processed in lexicographic order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in `/etc/` have the highest priority and take precedence over files with the same name in `/usr/lib/`. This can be used to override a system-supplied hwdb file with a local file if needed; a symlink in `/etc/` with the same name as a hwdb file in `/usr/lib/`, pointing to `/dev/null`, disables that hwdb file entirely. hwdb files must have the extension `.hwdb`; other extensions are ignored. Each hwdb file contains data records consisting of matches and associated key-value pairs. Every record in the hwdb starts with one or more match strings, specifying a shell glob to compare the lookup string against. Multiple match lines are specified in consecutive lines. Every match line is compared individually, and they are combined by OR. Every match line must start at the first character of the line. Match patterns consist of literal characters, and shell-style wildcards: - Asterisk `*` matches any number of characters - Question mark `?` matches a single character - Character list `[chars]` matches one of the characters \ listed between `[` and `]`. A range may be specified as with a dash as `[first-last]`. The match may be inverted with a caret `[^…]`. The match lines are followed by one or more key-value pair lines, which are recognized by a leading space character. The key name and value are separated by `=`. An empty line signifies the end of a record. Lines beginning with `#` are ignored. In case multiple records match a given lookup string, the key-value pairs from all records are combined. If a key is specified multiple times, the value from the record with the highest priority is used (each key can have only a single value). The priority is higher when the record is in a file that sorts later lexicographically, and in case of records in the same file, later records have higher priority. The content of all hwdb files is read by `systemd-hwdb(8)` and compiled to a binary database located at `/etc/udev/hwdb.bin`, or alternatively `/usr/lib/udev/hwdb.bin` if you want ship the compiled database in an immutable image. During runtime, only the binary database is used. # Examples
General syntax of hwdb files
# /usr/lib/udev/hwdb.d/example.hwdb # Comments can be placed before any records. This is a good spot # to describe what that file is used for, what kind of properties # it defines, and the ordering convention. # A record with three matches and one property mouse:*:name:*Trackball*:* mouse:*:name:*trackball*:* mouse:*:name:*TrackBall*:* ID_INPUT_TRACKBALL=1 # The rule above could be also be written in a form that # matches Tb, tb, TB, tB: mouse:*:name:*[tT]rack[bB]all*:* ID_INPUT_TRACKBALL=1 # A record with a single match and five properties mouse:usb:v046dp4041:name:Logitech MX Master:* MOUSE_DPI=1000@166 MOUSE_WHEEL_CLICK_ANGLE=15 MOUSE_WHEEL_CLICK_ANGLE_HORIZONTAL=26 MOUSE_WHEEL_CLICK_COUNT=24 MOUSE_WHEEL_CLICK_COUNT_HORIZONTAL=14
Overriding of properties
# /usr/lib/udev/hwdb.d/60-keyboard.hwdb evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer*:pn*:* KEYBOARD_KEY_a1=help KEYBOARD_KEY_a2=setup KEYBOARD_KEY_a3=battery # Match vendor name "Acer" and any product name starting with "X123" evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer:pnX123*:* KEYBOARD_KEY_a2=wlan # /etc/udev/hwdb.d/70-keyboard.hwdb # disable wlan key on all at keyboards evdev:atkbd:* KEYBOARD_KEY_a2=reserved PROPERTY_WITH_SPACES=some string If the hwdb consists of those two files, a keyboard with the lookup string `evdev:atkbd:dmi:bvnAcer:bvr:bdXXXXX:bd08/05/2010:svnAcer:pnX123:` will match all three records, and end up with the following properties: KEYBOARD_KEY_a1=help KEYBOARD_KEY_a2=reserved KEYBOARD_KEY_a3=battery PROPERTY_WITH_SPACES=some string
# See Also `systemd-hwdb(8)` # importctl systemd importctl 1 importctl Download, import or export disk images importctl OPTIONS COMMAND NAME # Description `importctl` may be used to download, import, and export disk images via `systemd-importd.service(8)`. `importctl` operates both on block-level disk images (such as DDIs), file-system-level images (tarballs), as well as OCI images. It supports disk images in one of the four following classes: - VM images or full OS container images, that may be run via `systemd-vmspawn(1)` or `systemd-nspawn(1)`, and managed via `machinectl(1)`. - Portable service images, that may be attached and managed via `portablectl(1)`. - System extension (sysext) images, that may be activated via `systemd-sysext(8)`. - Configuration extension (confext) images, that may be activated via `systemd-confext(8)`. When images are downloaded or imported they are placed in the following directories, depending on the `--class=` parameter: | Class | Directory | |------------|------------------------| | `machine` | `/var/lib/machines/` | | `portable` | `/var/lib/portables/` | | `sysext` | `/var/lib/extensions/` | | `confext` | `/var/lib/confexts/` | Classes and Directories # Commands The following commands are understood: `pull-tar` \ \[\\] Downloads a `.tar` image from the specified URL, and makes it available under the specified local name in the image directory for the selected `--class=`. The URL must be of type `http://` or `https://`, and must refer to a `.tar`, `.tar.gz`, `.tar.xz` or `.tar.bz2` archive file. If the local image name is omitted, it is automatically derived from the last component of the URL, with its suffix removed. The image is verified before it is made available, unless `--verify=no` is specified. Verification is done either via a file with the name of the image and the suffix `.sha256` and a detached `.sha256.asc` or `.sha256.gpg` signature or via separate `SHA256SUMS` and `SHA256SUMS.asc` or `SHA256SUMS.gpg` files. The signature files need to be made available on the same web server, under the same URL as the `.tar` file. With `--verify=checksum`, only the SHA256 checksum for the file is verified, based on the `.sha256` suffixed file or the `SHA256SUMS` file. With `--verify=signature`, the sha checksum file is first verified with the detached GPG signature of `.sha256` or `SHA256SUMS`. The public key for this verification step needs to be available in the system keyring consisting of `/usr/lib/systemd/import-pubring.pgp` and the local keyring in `/etc/systemd/import-pubring.pgp` (or, if that does not exist, `/etc/systemd/import-pubring.gpg`). If `-keep-download=yes` is specified the image will be downloaded and stored in a read-only subvolume/directory in the image directory that is named after the specified URL and its HTTP etag (see [HTTP ETag](https://en.wikipedia.org/wiki/HTTP_ETag) for more information). A writable snapshot is then taken from this subvolume, and named after the specified local name. This behavior ensures that creating multiple instances of the same URL is efficient, as multiple downloads are not necessary. In order to create only the read-only image, and avoid creating its writable snapshot, specify `-` as local name. Note that pressing Control-c during execution of this command will not abort the download. Use `cancel-transfer`, described below. `pull-raw` \ \[\\] Downloads a `.raw` disk image from the specified URL, and makes it available under the specified local name in the image directory for the selected `--class=`. The URL must be of type `http://` or `https://`. The image must either be a qcow2 or raw disk image, optionally compressed as `.gz`, `.xz`, or `.bz2`. If the local name is omitted, it is automatically derived from the last component of the URL, with its suffix removed. Image verification is identical for raw and tar images (see above). If the downloaded image is in qcow2 format it is converted into a raw image file before it is made available. If `-keep-download=yes` is specified the image will be downloaded and stored in a read-only file in the image directory that is named after the specified URL and its HTTP etag. A writable copy is then made from this file, and named after the specified local name. This behavior ensures that creating multiple instances of the same URL is efficient, as multiple downloads are not necessary. In order to create only the read-only image, and avoid creating its writable copy, specify `-` as local name. Note that pressing Control-c during execution of this command will not abort the download. Use `cancel-transfer`, described below. `pull-oci` \ \[\\] Downloads the specified OCI container image, and makes it available under the specified local name in the image directory for the selected `--class=`. The first argument must be an OCI container reference, such as `library/nginx` If the local name is omitted, it is automatically derived from the last component of the URL, with its suffix removed. When downloading images of this type no image verification is done beyond the usual authentication of the HTTPS certificates. Images in Docker's "Image Manifest V2, Schema 2" format, from which the OCI image format was derived, may be downloaded too. Note that pressing Control-c during execution of this command will not abort the download. Use `cancel-transfer`, described below. `import-tar` \ \[\\]; `import-raw` \ \[\\] Imports a TAR or RAW image, and places it under the specified name in the image directory for the image class selected via `--class=`. When `import-tar` is used, the file specified as the first argument should be a `tar(1)` archive, possibly compressed with `xz(1)`, `gzip(1)`, `zstd(1)`, or `bzip2(1)`. It will then be unpacked into its own subvolume/directory. When `import-raw` is used, the file should be a qcow2 or raw disk image, possibly compressed with xz, gzip, zstd or bzip2. If the second argument (the resulting image name) is not specified, it is automatically derived from the file name. If the filename is passed as `-`, the image is read from standard input, in which case the second argument is mandatory. No cryptographic validation is done when importing the images. Much like image downloads, ongoing imports may be listed with `list` and aborted with `cancel-transfer`. `import-fs` \ \[\\] Imports an image stored in a local directory into the image directory for the image class selected via `--class=` and operates similarly to `import-tar` or `import-raw`, but the first argument is the source directory. If supported, this command will create a `btrfs(8)` snapshot or subvolume for the new image. `export-tar` \ \[\\]; `export-raw` \ \[\\] Exports a TAR or RAW image and stores it in the specified file. The first parameter should be an image name. The second parameter should be a file path the TAR or RAW image is written to. If the path ends in `.gz`, the file is compressed with `gzip(1)`, if it ends in `.xz`, with `xz(1)`, if it ends in `.zst`, with `zstd(1)`, and if it ends in `.bz2`, with `bzip2(1)`. If the path ends in neither, the file is left uncompressed. If the second argument is missing, the image is written to standard output. The compression may also be explicitly selected with the `--format=` switch. This is in particular useful if the second parameter is left unspecified. Much like image downloads and imports, ongoing exports may be listed with `list` and aborted with `cancel-transfer`. Note that, currently, only directory and subvolume images may be exported as TAR images, and only raw disk images as RAW images. `list-transfer` Shows a list of image downloads, imports and exports that are currently in progress. `cancel-transfer` \… Aborts a download, import or export of the image with the specified ID. To list ongoing transfers and their IDs, use `list`. `list-images` Shows a list of already downloaded/imported images. # Options The following options are understood: `--read-only` When used with `pull-raw`, `pull-tar`, `import-raw`, `import-tar` or `import-fs` a read-only image is created. `--verify=` When downloading an image, specify whether the image shall be verified before it is made available. Takes one of `no`, `checksum` and `signature`. If `no`, no verification is done. If `checksum` is specified, the download is checked for integrity after the transfer is complete, but no signatures are verified. If `signature` is specified, the checksum is verified and the image's signature is checked against a local keyring of trustable vendors, in combination with the vendor keyring in `/usr/lib/systemd/import-pubring.pgp`. It is strongly recommended to set this option to `signature` if the server and protocol support this. Defaults to `signature`. `--force` When downloading an image, and a local copy by the specified local name already exists, delete it first and replace it by the newly downloaded image. `--format=` When used with the `export-tar` or `export-raw` commands, specifies the compression format to use for the resulting file. Takes one of `uncompressed`, `xz`, `gzip`, `zst`, `bzip2`. By default, the format is determined automatically from the output image file name passed. `-q`; `--quiet` Suppresses additional informational output while running. `-M`; `--machine=` Connect to `systemd-importd.service(8)` running in a local container, to perform the specified operation within the container. `--class=`; `-m`; `-P`; `-S`; `-C` Selects the image class for the downloaded images. This primarily selects the directory to download into. The `--class=` switch takes `machine`, `portable`, `sysext` or `confext` as argument. The short options `-m`, `-P`, `-S`, `-C` are shortcuts for `--class=machine`, `--class=portable`, `--class=sysext`, `--class=confext`. Note that `--keep-download=` defaults to true for `--class=machine` and false otherwise, see below. `--keep-download=`; `-N` Takes a boolean argument. When specified with `pull-raw` or `pull-tar`, selects whether to download directly into the specified local image name, or whether to download into a read-only copy first of which to make a writable copy after the download is completed. Defaults to true for `--class=machine`, false otherwise. The `-N` switch is a shortcut for `--keep-download=no`. # Examples
Download an Ubuntu TAR image and open a shell in it
# importctl pull-tar -mN https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-root.tar.xz # systemd-nspawn -M jammy-server-cloudimg-amd64-root This downloads and verifies the specified `.tar` image, and then uses `systemd-nspawn(1)` to open a shell in it.
Download an Ubuntu RAW image, set a root password in it, start it as a service
# importctl pull-raw -mN \ https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64-disk-kvm.img \ jammy # systemd-firstboot --image=/var/lib/machines/jammy.raw --prompt-root-password --force # machinectl start jammy # machinectl login jammy This downloads the specified `.raw` image and makes it available under the local name `jammy`. Then, a root password is set with `systemd-firstboot(1)`. Afterwards the machine is started as system service. With the last command a login prompt into the container is requested.
Exports a container image as tar file
# importctl export-tar -m fedora myfedora.tar.xz Exports the container `fedora` as an xz-compressed tar file `myfedora.tar.xz` into the current directory.
# Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-importd.service(8)`, `systemd-nspawn(1)`, `systemd-vmspawn(1)`, `machinectl(1)`, `portablectl(1)`, `systemd-sysext(8)`, `systemd-confext(8)`, `tar(1)`, `xz(1)`, `gzip(1)`, `zstd(1)`, `bzip2(1)` # integritytab systemd integritytab 5 integritytab Configuration for integrity block devices `/etc/integritytab` # Description The `/etc/integritytab` file describes integrity protected block devices that are set up during system boot. Empty lines and lines starting with the `#` character are ignored. Each of the remaining lines describes one verity integrity protected block device. Fields are delimited by white space. Each line is in the form volume-name block-device [keyfile|-] [options|-] The first two fields are mandatory, the remaining two are optional and only required if user specified non-default options during integrity format. The first field contains the name of the resulting integrity volume; its block device is set up below `/dev/mapper/`. The second field contains a path to the underlying block device, or a specification of a block device via `UUID=` followed by the UUID, `PARTUUID=` followed by the partition UUID, `LABEL=` followed by the label, `PARTLABEL=` followed by the partition label. The third field if present contains an absolute filename path to a key file or a `-` to specify none. When the filename is present, the "integrity-algorithm" defaults to `hmac-sha256` with the key length derived from the number of bytes in the key file. At this time the only supported integrity algorithms when using key file are hmac-sha256, hmac-sha512, phmac-sha256, and hmac-sha512. The maximum size of the key file is 4096 bytes. The fourth field, if present, is a comma-delimited list of options or a `-` to specify none. The following options are recognized: `allow-discards` Allow the use of discard (TRIM) requests for the device. This option is available since the Linux kernel version 5.7. `mode=(journal|bitmap|direct)` Enable journaled, bitmapped or direct (passthrough) mode. Journaled mode is the default when this option is not specified. It provides safety against crashes, but can be slow because all data has to be written twice. Bitmap mode is more efficient since it requires only a single write, but it is less reliable because if data corruption happens when the machine crashes, it might not be detected. Direct mode disables the journal and the bitmap. Corresponds to the "direct writes" mode documented in [the dm-integrity documentation](https://docs.kernel.org/admin-guide/device-mapper/dm-integrity.html). Note that without a journal, if there is a crash, it is possible that the integrity tags and data will not match. If used, the journal-\* options below will have no effect if passed. `journal-watermark=[0..100]%` Journal watermark in percent. When the journal percentage exceeds this watermark, the journal flush will be started. Setting a value of "0%" uses default value. `journal-commit-time=[0..N]` Commit time in milliseconds. When this time passes (and no explicit flush operation was issued), the journal is written. Setting a value of zero uses default value. `data-device=/dev/disk/by-...` Specify a separate block device that contains existing data. The second field specified in the integritytab for block device then will contain calculated integrity tags and journal for data-device, but not the end user data. `integrity-algorithm=[crc32c|crc32|xxhash64|sha1|sha256|hmac-sha256|hmac-sha512|phmac-sha256|phmac-sha512]` The algorithm used for integrity checking. The default is crc32c. Must match option used during format. `_netdev` Marks this veritysetup device as requiring network. It will be started after the network is available, similarly to `systemd.mount(5)` units marked with `_netdev`. The service unit to set up this device will be ordered between `remote-fs-pre.target` and `remote-integritysetup.target`, instead of `integritysetup-pre.target` and `integritysetup.target`. Hint: if this device is used for a mount point that is specified in `fstab(5)`, the `_netdev` option should also be used for the mount point. Otherwise, a dependency loop might be created where the mount point will be pulled in by `local-fs.target`, while the service to configure the network is usually only started *after* the local file system has been mounted. `noauto` This device will not be added to `integritysetup.target`. This means that it will not be automatically enabled on boot, unless something else pulls it in. In particular, if the device is used for a mount point, it'll be enabled automatically during boot, unless the mount point itself is also disabled with `noauto`. `nofail` This device will not be a hard dependency of `integritysetup.target`. It'll still be pulled in and started, but the system will not wait for the device to show up and be enabled, and boot will not fail if this is unsuccessful. Note that other units that depend on the enabled device may still fail. In particular, if the device is used for a mount point, the mount point itself also needs to have the `nofail` option, or the boot will fail if the device is not enabled successfully. At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by `systemd-integritysetup-generator(8)`. # Examples
/etc/integritytab
Set up two integrity protected block devices. home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 - journal-commit-time=10,allow-discards,journal-watermark=55% data PARTUUID=5d4b1808-be76-774d-88af-03c4c3a41761 - allow-discards
/etc/integritytab
Set up 1 integrity protected block device using defaults home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8
/etc/integritytab
Set up 1 integrity device using existing data block device which contains user data home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 - data-device=/dev/disk/by-uuid/9276d9c0-d4e3-4297-b4ff-3307cd0d092f
/etc/integritytab
Set up 1 integrity device using a HMAC key file using defaults home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 /etc/hmac.key
# See Also `systemd(1)`, `systemd-integritysetup@.service(8)`, `systemd-integritysetup-generator(8)`, `integritysetup(8)` # iocost.conf systemd iocost.conf 5 iocost.conf Configuration files for the iocost solution manager `/etc/systemd/iocost.conf` `/etc/systemd/iocost.conf.d/*.conf` # Description This file configures the behavior of `iocost`, a tool mostly used by `systemd-udevd(8)` rules to automatically apply I/O cost solutions to `/sys/fs/cgroup/io.cost.*`. The qos and model values are calculated based on benchmarks collected on the [iocost-benchmark](https://github.com/iocost-benchmark/iocost-benchmarks) project and turned into a set of solutions that go from most to least isolated. Isolation allows the system to remain responsive in face of high I/O load. Which solutions are available for a device can be queried from the udev metadata attached to it. By default the naive solution is used, which provides the most bandwidth. # Options All options are configured in the \[IOCost\] section: `TargetSolution=` Chooses which I/O cost solution (identified by named string) should be used for the devices in this system. The known solutions can be queried from the udev metadata attached to the devices. If a device does not have the specified solution, the first one listed in `IOCOST_SOLUTIONS` is used instead. E.g. `TargetSolution=isolated-bandwidth`. # See Also `udevadm(8)`, [The iocost-benchmarks github project](https://github.com/iocost-benchmark/iocost-benchmarks), [The resctl-bench documentation details how the values are obtained](https://github.com/facebookexperimental/resctl-demo/tree/main/resctl-bench/doc) # journal-remote.conf systemd journal-remote.conf 5 journal-remote.conf journal-remote.conf.d Configuration files for the service accepting remote journal uploads `/etc/systemd/journal-remote.conf`, `/run/systemd/journal-remote.conf`, `/usr/local/lib/systemd/journal-remote.conf`, `/usr/lib/systemd/journal-remote.conf`, `/etc/systemd/journal-remote.conf.d/*.conf`, `/run/systemd/journal-remote.conf.d/*.conf`, `/usr/local/lib/systemd/journal-remote.conf.d/*.conf`, `/usr/lib/systemd/journal-remote.conf.d/*.conf` # Description These files configure various parameters of `systemd-journal-remote.service(8)`. See `systemd.syntax(7)` for a general description of the syntax. # Options All options are configured in the \[Remote\] section: `Seal=` Periodically sign the data in the journal using Forward Secure Sealing. `SplitMode=` One of `host` or `none`. `ServerKeyFile=` SSL key in PEM format. `ServerCertificateFile=` SSL certificate in PEM format. `TrustedCertificateFile=` SSL CA certificate. `AddClientCertificateSubject=` Takes a boolean. If enabled, records the verified HTTPS client's full certificate subject in `_REMOTE_CERTIFICATE_SUBJECT=`. All incoming copies of this field are removed, including from non-HTTPS inputs and imported files. Without a verified client certificate, the field is omitted. Certificate verification and connection acceptance are unchanged. Defaults to no, leaving incoming fields unchanged. `MaxUse=`; `KeepFree=`; `MaxFileSize=`; `MaxFiles=` These are analogous to `SystemMaxUse=`, `SystemKeepFree=`, `SystemMaxFileSize=` and `SystemMaxFiles=` in `journald.conf(5)`. `MaxUse=` controls how much disk space the `systemd-journal-remote` may use up at most. `KeepFree=` controls how much disk space `systemd-journal-remote` shall leave free for other uses. `systemd-journal-remote` will respect both limits and use the smaller of the two values. `MaxFiles=` controls how many individual journal files to keep at most. Note that only archived files are deleted to reduce the number of files until this limit is reached; active files will stay around. This means that, in effect, there might still be more journal files around in total than this limit after a vacuuming operation is complete. `Compression=` Configurs acceptable compression algorithms to be announced through `Accept-Encoding` HTTP header. The header suggests `systemd-journal-upload` to compress data to be sent. Takes a space separated list of compression algorithms, or `no`. Supported algorithms are `zstd`, `xz`, or `lz4`. When a list of algorithms is specified, `Accept-Encoding` header will be constructed with priorities based on the order of the algorithms in the list. When `no`, `Accept-Encoding` header will not be sent. This option can be specified multiple times. If an empty string is assigned, then all the previous assignments are cleared. Defaults to unset and all supported compression algorithms will be listed in the header. Example: Compression=zstd lz4 # See Also `journald.conf(5)`, `systemd(1)`, `systemd-journal-remote.service(8)`, `systemd-journald.service(8)` # journal-upload.conf systemd journal-upload.conf 5 journal-upload.conf journal-upload.conf.d Configuration files for the journal upload service `/etc/systemd/journal-upload.conf` `/run/systemd/journal-upload.conf` `/usr/lib/systemd/journal-upload.conf` `/etc/systemd/journal-upload.conf.d/*.conf` `/run/systemd/journal-upload.conf.d/*.conf` `/usr/lib/systemd/journal-upload.conf.d/*.conf` # Description These files configure various parameters of `systemd-journal-upload.service(8)`. See `systemd.syntax(7)` for a general description of the syntax. # Options All options are configured in the \[Upload\] section: `URL=` The URL to upload the journal entries to. See the description of `--url=` option in `systemd-journal-upload(8)` for the description of possible values. There is no default value, so either this option or the command-line option must be always present to make an upload. `ServerKeyFile=` SSL key in PEM format. `ServerCertificateFile=` SSL CA certificate in PEM format. `TrustedCertificateFile=` SSL CA certificate. `NetworkTimeoutSec=` When network connectivity to the server is lost, this option configures the time to wait for the connectivity to get restored. If the server is not reachable over the network for the configured time, `systemd-journal-upload` exits. Takes a value in seconds (or in other time units if suffixed with "ms", "min", "h", etc). For details, see `systemd.time(7)`. `Compression=` Configures compression algorithm to be applied to logs data before sending. Takes a space separated list of compression algorithms, or `no`. Supported algorithms are `zstd`, `xz`, or `lz4`. Optionally, each algorithm followed by a colon (`:`) and its compression level, for example `zstd:4`. The compression level is expected to be a positive integer. When `no` is specified, no compression algorithm will be applied to data to be sent. This option can be specified multiple times. If an empty string is assigned, then all previous assignments are cleared. Defaults to unset, and all supported compression algorithms with their default compression levels are listed. Example: Compression=zstd:4 lz4:2 Even when compression is enabled, the initial requests are sent without compression. It becomes effective either if `ForceCompression=` is enabled, or the server response contains `Accept-Encoding` headers with a list of compression algorithms that contains one of the algorithms specified in this option. `ForceCompression=` Takes a boolean value, enforces using compression without content encoding negotiation. Defaults to `false`. `Header=` Specifies an additional HTTP header to be added to each request to a URL. Takes a pair of header name and value separated with a colon(`:`), e.g. `Name:Value`. Header name can contain alphanumeric values, `_` and `-` symbols additionally. This option may be specified more than once, in which case all listed headers will be set. If the same header name is listed more than once, all its unique values will be concatenated with comma. Setting `Header=` to empty string clears all previous assignments. Example: Header=HeaderName: HeaderValue Header=HeaderName: NewValue Header=HeaderName: HeaderValue adds `HeaderName` header with `HeaderValue, NewValue` to each HTTP request. # See Also `systemd-journal-upload.service(8)`, `systemd(1)`, `systemd-journald.service(8)` # journalctl systemd journalctl 1 journalctl Print log entries from the systemd journal journalctl OPTIONS MATCHES # Description `journalctl` is used to print the log entries stored in the journal by `systemd-journald.service(8)` and `systemd-journal-remote.service(8)`. If called without parameters, it will show the contents of the journal accessible to the calling user, starting with the oldest entry collected. If one or more match arguments are passed, the output is filtered accordingly. A match is in the format `FIELD=VALUE`, e.g. `_SYSTEMD_UNIT=httpd.service`, referring to the components of a structured journal entry. See `systemd.journal-fields(7)` for a list of well-known fields. If multiple matches are specified matching different fields, the log entries are filtered by both, i.e. the resulting output will show only entries matching all the specified matches of this kind. If two matches apply to the same field, then they are automatically matched as alternatives, i.e. the resulting output will show entries matching any of the specified matches for the same field. Finally, the character `+` may appear as a separate word between other terms on the command line. This causes all matches before and after to be combined in a disjunction (i.e. logical OR). It is also possible to filter the entries by specifying an absolute file path as an argument. The file path may be a file or a symbolic link and the file must exist at the time of the query. If a file path refers to an executable binary, an `_EXE=` match for the canonicalized binary path is added to the query. If a file path refers to an executable script, a `_COMM=` match for the script name is added to the query. If a file path refers to a device node, `_KERNEL_DEVICE=` matches for the kernel name of the device and for each of its ancestor devices is added to the query. Symbolic links are dereferenced, kernel names are synthesized, and parent devices are identified from the environment at the time of the query. In general, a device node is the best proxy for an actual device, as log entries do not usually contain fields that identify an actual device. For the resulting log entries to be correct for the actual device, the relevant parts of the environment at the time the entry was logged, in particular the actual device corresponding to the device node, must have been the same as those at the time of the query. Because device nodes generally change their corresponding devices across reboots, specifying a device node path causes the resulting entries to be restricted to those from the current boot. Additional constraints may be added using options `--boot`, `--unit=`, etc., to further limit what entries will be shown (logical AND). Output is interleaved from all accessible journal files, whether they are rotated or currently being written, and regardless of whether they belong to the system itself or are accessible user journals. The `--header` option can be used to identify which files *are* being shown. The set of journal files which will be used can be modified using the `--user`, `--system`, `--directory=`, and `--file=` options, see below. All users are granted access to their private per-user journals. However, by default, only root and users who are members of a few special groups are granted access to the system journal and the journals of other users. Members of the groups `systemd-journal`, `adm`, and `wheel` can read all journal files. Note that the two latter groups traditionally have additional privileges specified by the distribution. Members of the `wheel` group can often perform administrative tasks. The output is paged through `less` by default, and long lines are "truncated" to screen width. The hidden part can be viewed by using the left-arrow and right-arrow keys. Paging can be disabled; see the `--no-pager` option and the "Environment" section below. When outputting to a tty, lines are colored according to priority: lines of level ERROR and higher are colored red; lines of level WARNING are colored yellow; lines of level NOTICE are highlighted; lines of level INFO are displayed normally; lines of level DEBUG are colored grey. To write entries *to* the journal, a few methods may be used. In general, output from systemd units is automatically connected to the journal, see `systemd-journald.service(8)`. In addition, `systemd-cat(1)` may be used to send messages to the journal directly. # Source Options The following options control where to read journal records from: `--system`; `--user` Show messages from system services and the kernel (with `--system`). Show messages from service of current user (with `--user`). If neither is specified, show all messages that the user can see. The `--user` option affects how `--unit=` arguments are treated. See `--unit=`. Note that `--user` only works if persistent logging is enabled, via the `Storage=` setting in `journald.conf(5)`. `-M`; `--machine=` Show messages from a running, local container. Specify a container name to connect to. `-m`; `--merge` Show entries interleaved from all available journals, including remote ones. `-D DIR`; `--directory=DIR` Takes a directory path as argument. If specified, journalctl will operate on the specified journal directory \ instead of the default runtime and system journal paths. `-i GLOB`; `--file=GLOB` Takes a file glob as an argument. If specified, journalctl will operate on the specified journal files matching \ instead of the default runtime and system journal paths. May be specified multiple times, in which case files will be suitably interleaved. `--root=ROOT` Takes a directory path as an argument. If specified, `journalctl` will operate on journal directories and catalog file hierarchy underneath the specified directory instead of the root directory (e.g. `--update-catalog` will create `ROOT/var/lib/systemd/catalog/database`, and journal files under `ROOT/run/journal/` or `ROOT/var/log/journal/` will be displayed). `--image=IMAGE` Takes a path to a disk image file or block device node. If specified, `journalctl` will operate on the file system in the indicated disk image. This option is similar to `--root=`, but operates on file systems stored in disk images or block devices, thus providing an easy way to extract log data from disk images. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). For further information on supported disk images, see `systemd-nspawn(1)`'s switch of the same name. `--namespace=NAMESPACE` Takes a journal namespace identifier string as argument. If not specified, the data collected by the default namespace is shown. If specified, shows the log data of the specified namespace instead. If the namespace is specified as `*` data from all namespaces is shown, interleaved. If the namespace identifier is prefixed with `+` data from the specified namespace and the default namespace is shown, interleaved, but no other. For details about journal namespaces see `systemd-journald.service(8)`. # Filtering Options The following options control how to filter journal records: `-S`; `--since=`; `-U`; `--until=` Start showing entries on or newer than the specified date, or on or older than the specified date, respectively. Date specifications should be of the format `2012-10-30 18:17:16`. If the time part is omitted, `00:00:00` is assumed. If only the seconds component is omitted, `:00` is assumed. If the date component is omitted, the current day is assumed. Alternatively the strings `yesterday`, `today`, `tomorrow` are understood, which refer to 00:00:00 of the day before the current day, the current day, or the day after the current day, respectively. `now` refers to the current time. Finally, relative times may be specified, prefixed with `-` or `+`, referring to times before or after the current time, respectively. For complete time and date specification, see `systemd.time(7)`. Note that `--output=short-full` prints timestamps that follow precisely this format. `-c`; `--cursor=` Start showing entries from the location in the journal specified by the passed cursor. `--after-cursor=` Start showing entries from the location in the journal *after* the location specified by the passed cursor. The cursor is shown when the `--show-cursor` option is used. `--cursor-file=FILE` If \ exists and contains a cursor, start showing entries *after* this location. Otherwise, show entries according to the other given options. At the end, write the cursor of the last entry to \. Use this option to continually read the journal by sequentially calling `journalctl`. `-b ID±offset|all`; `--boot=ID±offset|all` Show messages from a specific boot. This will add a match for `_BOOT_ID=`. The argument may be empty, in which case logs for the current boot will be shown. If the boot ID is omitted, a positive \ will look up the boots starting from the beginning of the journal, and an equal-or-less-than zero \ will look up boots starting from the end of the journal. Thus, `1` means the first boot found in the journal in chronological order, `2` the second and so on; while `-0` is the last boot, `-1` the boot before last, and so on. An empty \ is equivalent to specifying `-0`, except when the current boot is not the last boot (e.g. because `--directory=` was specified to look at logs from a different machine). If the 32-character \ is specified, it may optionally be followed by \ which identifies the boot relative to the one given by boot \. Negative values mean earlier boots and positive values mean later boots. If \ is not specified, a value of zero is assumed, and the logs for the boot given by \ are shown. The special argument `all` can be used to negate the effect of an earlier use of `-b`. `-u`; `--unit=UNIT|PATTERN` Show messages for the specified systemd unit \ (such as a service unit), or for any of the units matched by \. If a pattern is specified, a list of unit names found in the journal is compared with the specified pattern and all that match are used. For each unit name, a match is added for messages from the unit (`_SYSTEMD_UNIT=UNIT`), along with additional matches for messages from systemd and messages about coredumps for the specified unit. A match is also added for `_SYSTEMD_SLICE=UNIT`, such that if the provided \ is a `systemd.slice(5)` unit, all logs of children of the slice will be shown. With `--user`, all `--unit=` arguments will be converted to match user messages as if specified with `--user-unit=`. This parameter can be specified multiple times. `--user-unit=` Show messages for the specified user session unit. This will add a match for messages from the unit (`_SYSTEMD_USER_UNIT=` and `_UID=`) and additional matches for messages from session systemd and messages about coredumps for the specified unit. A match is also added for `_SYSTEMD_USER_SLICE=UNIT`, such that if the provided \ is a `systemd.slice(5)` unit, all logs of children of the unit will be shown. This parameter can be specified multiple times. `-I`; `--invocation=ID±offset|offset` Show messages from a specific invocation of unit. This will add a match for `_SYSTEMD_INVOCATION_ID=`, `OBJECT_SYSTEMD_INVOCATION_ID=`, `INVOCATION_ID=`, `USER_INVOCATION_ID=`. A positive \ will look up the invocations of a systemd unit from the beginning of the journal, and zero or a negative offset will look up invocations starting from the end of the journal. Thus, `1` means the first invocation found in the journal in chronological order, `2` the second and so on; while `0` is the latest invocation, `-1` the invocation before the latest, and so on. If the 32-character \ is specified, it may optionally be followed by \<±offset\> which identifies the invocation relative to the one given by invocation \. Negative values mean earlier invocations and positive values mean later invocations. If \<±offset\> is not specified, a value of zero is assumed, and the logs for the invocation given by \ will be shown. `-I` is equivalent to `--invocation=0`, and logs for the latest invocation will be shown. When an offset is specified, a unit name must be specified with `-u/--unit=` or `--user-unit=` option. When specified with `-b/--boot=`, then invocations are searched within the specified boot. `-t`; `--identifier=SYSLOG_IDENTIFIER` Show messages for the specified syslog identifier \. This parameter can be specified multiple times. If the argument contains a shell-style glob, it is matched against the syslog identifiers actually present in the journal, as for `--unit=`. If no glob matches anything, and no exact identifier was given either, an error is returned. `-T`; `--exclude-identifier=SYSLOG_IDENTIFIER` Exclude messages for the specified syslog identifier \. This parameter can be specified multiple times. If the argument contains a shell-style glob, it is matched against the syslog identifiers actually present in the journal, as for `--identifier=`. Patterns which do not match anything are silently skipped. `-p`; `--priority=` Filter output by message priorities or priority ranges. Takes either a single numeric or textual log level (i.e. between 0/`emerg` and 7/`debug`), or a range of numeric/text log levels in the form FROM..TO. The log levels are the usual syslog log levels as documented in `syslog(3)`, i.e. `emerg` (0), `alert` (1), `crit` (2), `err` (3), `warning` (4), `notice` (5), `info` (6), `debug` (7). If a single log level is specified, all messages with this log level or a lower (hence more important) log level are shown. If a range is specified, all messages within the range are shown, including both the start and the end value of the range. This will add `PRIORITY=` matches for the specified priorities. `--facility=` Filter output by syslog facility. Takes a comma-separated list of numbers or facility names. The names are the usual syslog facilities as documented in `syslog(3)`. `--facility=help` may be used to display a list of known facility names and exit. `-g`; `--grep=` Filter output to entries where the `MESSAGE=` field matches the specified regular expression. PERL-compatible regular expressions are used, see `pcre2pattern(3)` for a detailed description of the syntax. If the pattern is all lowercase, matching is case insensitive. Otherwise, matching is case sensitive. This can be overridden with the `--case-sensitive` option, see below. When used with `--lines=` (not prefixed with `+`), `--reverse` is implied. `--case-sensitive=BOOLEAN` Make pattern matching case sensitive or case insensitive. `-k`; `--dmesg` Show only kernel messages. This adds the match `_TRANSPORT=kernel`. This implies `--boot=0` unless explicitly specified otherwise. # Output Options The following options control how journal records are printed: `-o`; `--output=` Controls the formatting of the journal entries that are shown. Takes one of the following options: `short` is the default and generates an output that is mostly identical to the formatting of classic syslog files, showing one line per journal entry. `short-full` is very similar, but shows timestamps in the format the `--since=` and `--until=` options accept. Unlike the timestamp information shown in `short` output mode this mode includes weekday, year and timezone information in the output, and is locale-independent. `short-iso` is very similar, but shows timestamps in the [RFC 3339](https://tools.ietf.org/html/rfc3339) profile of ISO 8601. `short-iso-precise` as for `short-iso` but includes full microsecond precision. `short-precise` is very similar, but shows classic syslog timestamps with full microsecond precision. `short-monotonic` is very similar, but shows monotonic timestamps instead of wallclock timestamps. `short-delta` as for `short-monotonic` but includes the time difference to the previous entry. Maybe unreliable time differences are marked by a `*`. `short-unix` is very similar, but shows seconds passed since January 1st 1970 UTC instead of wallclock timestamps ("UNIX time"). The time is shown with microsecond accuracy. `verbose` shows the full-structured entry items with all fields. `export` serializes the journal into a binary (but mostly text-based) stream suitable for backups and network transfer (see [Journal Export Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format) for more information). To import the binary stream back into native journald format use `systemd-journal-remote(8)`. `json` formats entries as JSON objects, separated by newline characters (see [Journal JSON Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format) for more information). Field values are generally encoded as JSON strings, with three exceptions: 1. Fields larger than 4096 bytes are encoded as `null` values. (This may be turned off by passing `--all`, but be aware that this may allocate overly long JSON objects.) 2. Journal entries permit non-unique fields within the same log entry. JSON does not allow non-unique fields within objects. Due to this, if a non-unique field is encountered a JSON array is used as field value, listing all field values as elements. 3. Fields containing non-printable or non-UTF8 bytes are encoded as arrays containing the raw bytes individually formatted as unsigned numbers. Note that this encoding is reversible (with the exception of the size limit). `json-pretty` formats entries as JSON data structures, but formats them in multiple lines in order to make them more readable by humans. `json-sse` formats entries as JSON data structures, but wraps them in a format suitable for [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events). `json-seq` formats entries as JSON data structures, but prefixes them with an ASCII Record Separator character (0x1E) and suffixes them with an ASCII Line Feed character (0x0A), in accordance with [JavaScript Object Notation (JSON) Text Sequences ](https://tools.ietf.org/html/rfc7464) (`application/json-seq`). `cat` generates a very terse output, only showing the actual message of each journal entry with no metadata, not even a timestamp. If combined with the `--output-fields=` option will output the listed fields for each log record, instead of the message. `with-unit` similar to `short-full`, but prefixes the unit and user unit names instead of the traditional syslog identifier. Useful when using templated instances, as it will include the arguments in the unit names. `--truncate-newline` Truncate each log message at the first newline character on output, so that only the first line of each message is displayed. `--output-fields=` A comma separated list of the fields which should be included in the output. This has an effect only for the output modes which would normally show all fields (`verbose`, `export`, `json`, `json-pretty`, `json-sse` and `json-seq`), as well as on `cat`. For the former, the `__CURSOR`, `__REALTIME_TIMESTAMP`, `__MONOTONIC_TIMESTAMP`, and `_BOOT_ID` fields are always printed. `-n`; `--lines=` Show the most recent journal events and limit the number of events shown. The argument is a positive integer or `all` to disable the limit. Additionally, if the number is prefixed with `+`, the oldest journal events are used instead. The default value is 10 if no argument is given. If `--follow` is used, this option is implied. When not prefixed with `+` and used with `--grep=`, `--reverse` is implied. `-r`; `--reverse` Reverse output so that the newest entries are displayed first. `--show-cursor` The cursor is shown after the last entry after two dashes: -- cursor: s=0639… The format of the cursor is private and subject to change. `--utc` Express time in Coordinated Universal Time (UTC). `-x`; `--catalog` Augment log lines with explanation texts from the message catalog. This will add explanatory help texts to log messages in the output where this is available. These short help texts will explain the context of an error or log event, possible solutions, as well as pointers to support forums, developer documentation, and any other relevant manuals. Note that help texts are not available for all messages, but only for selected ones. For more information on the message catalog, see [Journal Message Catalogs](https://systemd.io/CATALOG). Note: when attaching `journalctl` output to bug reports, please do *not* use `-x`. `-W`; `--no-hostname` Do not show the hostname field of log messages. This switch has an effect only on the `short` family of output modes (see above). Note: this option does not remove occurrences of the hostname from log entries themselves, so it does not prevent the hostname from being visible in the logs. `--no-full`; `--full`; `-l` Ellipsize fields when they do not fit in available columns. The default is to show full fields, allowing them to wrap or be truncated by the pager, if one is used. The old options `-l`/`--full` are not useful anymore, except to undo `--no-full`. `-a`; `--all` Show all fields in full, even if they include unprintable characters or are very long. By default, fields with unprintable characters are abbreviated as "blob data". (Note that the pager may escape unprintable characters again.) `-f`; `--follow` Show only the most recent journal entries, and continuously print new entries as they are appended to the journal, until Ctrl-C is hit (or the tool is otherwise terminated). `journalctl` will send an `sd_notify(3)` `READY=1` message once it initialized and successfully established its watch on the journal. `--no-tail` Show all stored output lines, even in follow mode. Undoes the effect of `--lines=`. `-q`; `--quiet` Suppresses all informational messages (i.e. "-- Journal begins at …", "-- Reboot --"), any warning messages regarding inaccessible system journals when run as a normal user. `--synchronize-on-exit=` Takes a boolean argument. If true and operating in `--follow` mode, a journal synchronization request (equivalent to `journalctl --sync`) is issued when `SIGTERM`/`SIGINT` is received, and log output continues until this request completes. This is useful for synchronizing journal log output to the runtime of services or external events, ensuring that any log data enqueued to the logging subsystem by the time `SIGTERM`/`SIGINT` is issued is guaranteed to be processed and displayed by the time log output ends. Defaults to false. # Pager Control Options The following options control page support: `-e`; `--pager-end` Immediately jump to the end of the journal inside the implied pager tool. This implies `--lines=1000` and `--boot=0` unless explicitly specified otherwise, to guarantee that the pager will not buffer logs of unbounded size. Note that this option is only supported for the `less(1)` pager. # Forward Secure Sealing (FSS) Options The following options may be used together with the `--setup-keys` command described below: `--interval=` Specifies the change interval for the sealing key when generating an FSS key pair with `--setup-keys`. Shorter intervals increase CPU consumption but shorten the time range of undetectable journal alterations. Defaults to 15min. Note, `--output=json-sse` and `--output=json-seq` are silently migrated to `--output=json`. `--verify-key=` Specifies the FSS verification key to use for the `--verify` operation. `--force` When `--setup-keys` is passed and Forward Secure Sealing (FSS) has already been configured, recreate FSS keys. # Commands The following commands are understood. If none is specified the default is to display journal records: `-N`; `--fields` Print all field names currently used in all entries of the journal. `-F`; `--field=` Print all possible data values the specified field can take in all entries of the journal. `--list-boots` Show a tabular list of boot numbers (relative to the current boot), their IDs, and the timestamps of the first and last message pertaining to the boot. When specified with `-n/--lines=+N` option, only the first (when the number prefixed with `+`) or the last (without prefix) \ entries will be shown. When specified with `-r/--reverse`, the list will be shown in the reverse order. `--list-invocations` List invocation IDs of a unit. Requires a unit name with `-u/--unit=` or `--user-unit=`. Show a tabular list of invocation numbers (relative to the current or latest invocation), their IDs, and the timestamps of the first and last message pertaining to the invocation. When `-b/-boot` is specified, invocations in the boot will be shown. When specified with `-n/--lines=+N` option, only the first (when the number prefixed with `+`) or the last (without prefix) \ entries will be shown. When specified with `-r/--reverse`, the list will be shown in the reverse order. `--disk-usage` Shows the current disk usage of all journal files. This shows the sum of the disk usage of all archived and active journal files. `--vacuum-size=`; `--vacuum-time=`; `--vacuum-files=` `--vacuum-size=` removes the oldest archived journal files until the disk space they use falls below the specified size. Accepts the usual `K`, `M`, `G` and `T` suffixes (to the base of 1024). `--vacuum-time=` removes archived journal files older than the specified timespan. Accepts the usual `s` (default), `m`, `h`, `days`, `weeks`, `months`, and `years` suffixes, see `systemd.time(7)` for details. `--vacuum-files=` leaves only the specified number of separate journal files. Note that running `--vacuum-size=` has only an indirect effect on the output shown by `--disk-usage`, as the latter includes active journal files, while the vacuuming operation only operates on archived journal files. Similarly, `--vacuum-files=` might not actually reduce the number of journal files to below the specified number, as it will not remove active journal files. `--vacuum-size=`, `--vacuum-time=` and `--vacuum-files=` may be combined in a single invocation to enforce any combination of a size, a time and a number of files limit on the archived journal files. Specifying any of these three parameters as zero is equivalent to not enforcing the specific limit, and is thus redundant. These three switches may also be combined with `--rotate` into one command. If so, all active files are rotated first, and the requested vacuuming operation is executed right after. The rotation has the effect that all currently active files are archived (and potentially new, empty journal files opened as replacement), and hence the vacuuming operation has the greatest effect as it can take all log data written so far into account. `--verify` Check the journal file for internal consistency. If the file has been generated with FSS enabled and the FSS verification key has been specified with `--verify-key=`, authenticity of the journal file is verified. `--sync` Asks the journal daemon to write all yet unwritten journal data to the backing file system and synchronize all journals. This call does not return until the synchronization operation is complete. This command guarantees that any log messages written before its invocation are safely stored on disk at the time it returns. `--relinquish-var` Asks the journal daemon for the reverse operation to `--flush`: if requested the daemon will write further log data to `/run/log/journal/` and stops writing to `/var/log/journal/`. A subsequent call to `--flush` causes the log output to switch back to `/var/log/journal/`, see above. `--smart-relinquish-var` Similar to `--relinquish-var`, but executes no operation if the root file system and `/var/log/journal/` reside on the same mount point. This operation is used during system shutdown in order to make the journal daemon stop writing data to `/var/log/journal/` in case that directory is located on a mount point that needs to be unmounted. `--flush` Asks the journal daemon to flush any log data stored in `/run/log/journal/` into `/var/log/journal/`, if persistent storage is enabled. This call does not return until the operation is complete. Note that this call is idempotent: the data is only flushed from `/run/log/journal/` into `/var/log/journal/` once during system runtime (but see `--relinquish-var` below), and this command exits cleanly without executing any operation if this has already happened. This command effectively guarantees that all data is flushed to `/var/log/journal/` at the time it returns. `--rotate` Asks the journal daemon to rotate journal files. This call does not return until the rotation operation is complete. Journal file rotation has the effect that all currently active journal files are marked as archived and renamed, so that they are never written to in future. New (empty) journal files are then created in their place. This operation may be combined with `--vacuum-size=`, `--vacuum-time=` and `--vacuum-file=` into a single command, see above. `--header` Instead of showing journal contents, show internal header information of the journal fields accessed. This option is particularly useful when trying to identify out-of-order journal entries, as happens for example when the machine is booted with the wrong system time. `--list-catalog 128-bit-ID…` List the contents of the message catalog as a table of message IDs, plus their short description strings. If any \<128-bit-ID\>s are specified, only those entries are shown. `--dump-catalog 128-bit-ID…` Show the contents of the message catalog, with entries separated by a line consisting of two dashes and the ID (the format is the same as `.catalog` files). If any \<128-bit-ID\>s are specified, only those entries are shown. `--update-catalog` Update the message catalog index. This command needs to be executed each time new catalog files are installed, removed, or updated to rebuild the binary catalog index. `--setup-keys` Instead of showing journal contents, generate a new key pair for Forward Secure Sealing (FSS). This will generate a sealing key and a verification key. The sealing key is stored in the journal data directory and shall remain on the host. The verification key should be stored externally. Refer to the `Seal=` option in `journald.conf(5)` for information on Forward Secure Sealing and for a link to a refereed scholarly paper detailing the cryptographic theory it is based on. # Exit status On success, 0 is returned; otherwise, a non-zero failure code is returned. # Examples Without arguments, all collected logs are shown unfiltered: journalctl With one match specified, all entries with a field matching the expression are shown: journalctl _SYSTEMD_UNIT=avahi-daemon.service journalctl _SYSTEMD_CGROUP=/user.slice/user-42.slice/session-c1.scope If two different fields are matched, only entries matching both expressions at the same time are shown: journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 If two matches refer to the same field, all entries matching either expression are shown: journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service If the separator `+` is used, two expressions may be combined in a logical OR. The following will show all messages from the Avahi service process with the PID 28097 plus all messages from the D-Bus service (from any of its processes): journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service To show all fields emitted *by* a unit and *about* the unit, option `-u`/`--unit=` should be used. `journalctl -u name` expands to a complex filter similar to _SYSTEMD_UNIT=name.service + UNIT=name.service _PID=1 + OBJECT_SYSTEMD_UNIT=name.service _UID=0 + COREDUMP_UNIT=name.service _UID=0 MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 (see `systemd.journal-fields(7)` for an explanation of those patterns). Show all logs generated by the D-Bus executable: journalctl /usr/bin/dbus-daemon Show all kernel logs from previous boot: journalctl -k -b -1 Show a live log display from a system service `apache.service`: journalctl -f -u apache # See Also `systemd(1)`, `systemd-cat(1)`, `systemd-journald.service(8)`, `systemctl(1)`, `coredumpctl(1)`, `systemd.journal-fields(7)`, `journald.conf(5)`, `systemd.time(7)`, `systemd-journal-remote.service(8)`, `systemd-journal-upload.service(8)` # kernel-command-line systemd kernel-command-line 7 kernel-command-line Kernel command line parameters `/proc/cmdline` # Description The kernel, the programs running in the initrd and in the host system may be configured at boot via kernel command line arguments. For command line parameters understood by the kernel, please see [`kernel-parameters.html`](https://docs.kernel.org/admin-guide/kernel-parameters.html) and `bootparam(7)`. For command line parameters understood by the initrd, see the documentation of the specific initrd implementation of your installation. # Core OS Command Line Arguments `systemd.unit=`; `rd.systemd.unit=`; `systemd.dump_core`; `systemd.crash_chvt`; `systemd.crash_shell`; `systemd.crash_action=`; `systemd.confirm_spawn`; `systemd.service_watchdogs`; `systemd.show_status`; `systemd.status_unit_format=`; `systemd.log_target=`; `systemd.log_level=`; `systemd.log_location=`; `systemd.log_color`; `systemd.log_ratelimit_kmsg`; `systemd.default_standard_output=`; `systemd.default_standard_error=`; `systemd.setenv=`; `systemd.machine_id=`; `systemd.set_credential=`; `systemd.set_credential_binary=`; `systemd.import_credentials=`; `systemd.credentials_boot_policy=`; `systemd.reload_limit_interval_sec=`; `systemd.reload_limit_burst=`; `systemd.minimum_uptime_sec=` Parameters understood by the system and service manager to control system behavior. For details, see `systemd(1)`. `systemd.restrict_filesystem_access=` Controls the `RestrictFileSystemAccess=` execution enforcement policy. For details, see `systemd-system.conf(5)`. `systemd.mask=`; `systemd.wants=`; `systemd.debug_shell`; `systemd.default_debug_tty=` Additional parameters understood by `systemd-debug-generator(8)`, to mask or start specific units at boot, or invoke a debug shell on tty9. `systemd.break=`; `rd.systemd.break=` Parameters understood by `systemd-debug-generator(8)`, to pause the boot process at a certain point and spawn a debug shell. `systemd.run=`; `systemd.run_success_action=`; `systemd.run_failure_action=` Additional parameters understood by `systemd-run-generator(8)`, to run a command line specified on the kernel command line as system service after booting up. `systemd.early_core_pattern=` During early boot, the generation of core dump files is disabled until a core dump handler (if any) takes over. This parameter allows specifying an absolute path where core dump files should be stored until a handler is installed. The path should be absolute and may contain specifiers, see `core(5)` for details. `systemd.restore_state=` This parameter is understood by several system tools to control whether or not they should restore system state from the previous boot. For details, see `systemd-backlight@.service(8)` and `systemd-rfkill.service(8)`. `systemd.ssh_auto=`; `systemd.ssh_listen=` These parameters are interpreted by `systemd-ssh-generator(8)` and may be used to control SSH sockets the system shall be reachable on. `systemd.volatile=` This parameter controls whether the system shall boot up in volatile mode. Takes a boolean argument, or the special values `state` or `overlay`. If false (the default), normal boot mode is selected, the root directory and `/var/` are mounted as specified on the kernel command line or `/etc/fstab`, or otherwise configured. If true, full state-less boot mode is selected. In this case, the root directory is mounted as volatile memory file system (`tmpfs`), and only `/usr/` is mounted from the file system configured as root device, in read-only mode. This enables fully state-less boots where the vendor-supplied OS is used as shipped, with only default configuration and no stored state in effect, as `/etc/` and `/var/` (as well as all other resources shipped in the root file system) are reset at boot and lost on shutdown. If this setting is set to `state` the root file system is mounted read-only, however `/var/` is mounted as a volatile memory file system (`tmpfs`), so that the system boots up with the normal configuration applied, but all state reset at boot and lost at shutdown. If this setting is set to `overlay` the root file system is set up as `overlayfs` mount combining the read-only root directory with a writable `tmpfs`, so that no modifications are made to disk, but the file system may be modified nonetheless with all changes being lost at reboot. For details, see `systemd-volatile-root.service(8)` and `systemd-fstab-generator(8)`. `quiet` Parameter understood by both the kernel and the system and service manager to control console log verbosity. For details, see `systemd(1)`. `debug` Parameter understood by both the kernel and the system and service manager to control console log verbosity. For details, see `systemd(1)`. `-b`; `rd.emergency`; `emergency`; `rd.rescue`; `rescue`; `single`; `s`; `S`; `1`; `2`; `3`; `4`; `5` Parameters understood by the system and service manager, as compatibility and convenience options. For details, see `systemd(1)`. `locale.LANG=`; `locale.LANGUAGE=`; `locale.LC_CTYPE=`; `locale.LC_NUMERIC=`; `locale.LC_TIME=`; `locale.LC_COLLATE=`; `locale.LC_MONETARY=`; `locale.LC_MESSAGES=`; `locale.LC_PAPER=`; `locale.LC_NAME=`; `locale.LC_ADDRESS=`; `locale.LC_TELEPHONE=`; `locale.LC_MEASUREMENT=`; `locale.LC_IDENTIFICATION=` Parameters understood by the system and service manager to control locale and language settings. For details, see `systemd(1)`. `fsck.mode=`; `fsck.repair=` Parameters understood by the file system checker services. For details, see `systemd-fsck@.service(8)`. `quotacheck.mode=` Parameter understood by the file quota checker service. For details, see `systemd-quotacheck@.service(8)`. `systemd.journald.forward_to_syslog=`; `systemd.journald.forward_to_kmsg=`; `systemd.journald.forward_to_console=`; `systemd.journald.forward_to_wall=` Parameters understood by the journal service. For details, see `systemd-journald.service(8)`. `vconsole.keymap=`; `vconsole.keymap_toggle=`; `vconsole.font=`; `vconsole.font_map=`; `vconsole.font_unimap=`; `vconsole.font_scale=` Parameters understood by the virtual console setup logic. For details, see `vconsole.conf(5)`. `vconsole.font_scale=` was added in version 262. `udev.log_level=`; `rd.udev.log_level=`; `udev.trace=`; `rd.udev.trace=`; `udev.children_max=`; `rd.udev.children_max=`; `udev.exec_delay=`; `rd.udev.exec_delay=`; `udev.event_timeout=`; `rd.udev.event_timeout=`; `udev.timeout_signal=`; `rd.udev.timeout_signal=`; `udev.blockdev_read_only`; `rd.udev.blockdev_read_only`; `net.ifnames=`; `net.naming_scheme=` Parameters understood by the device event managing daemon. For details, see `systemd-udevd.service(8)`. `plymouth.enable=` May be used to disable the Plymouth boot splash. For details, see `plymouth(8)`. `luks=`; `rd.luks=`; `luks.crypttab=`; `rd.luks.crypttab=`; `luks.name=`; `rd.luks.name=`; `luks.uuid=`; `rd.luks.uuid=`; `luks.options=`; `rd.luks.options=`; `luks.key=`; `rd.luks.key=` Configures the LUKS full-disk encryption logic at boot. For details, see `systemd-cryptsetup-generator(8)`. `fstab=`; `rd.fstab=` Configures the `/etc/fstab` logic at boot. For details, see `systemd-fstab-generator(8)`. `root=`; `rootfstype=`; `rootflags=`; `ro`; `rw` Configures the root file system and its file system type and mount options, as well as whether it shall be mounted read-only or read-write initially. For details, see `systemd-fstab-generator(8)`. If `root=` is not set (or set to `gpt-auto`) the automatic root partition discovery implemented by `systemd-gpt-auto-generator(8)` will be in effect. In this case, `rootfstype=`, `rootflags=`, `ro`, `rw` will be interpreted by `systemd-gpt-auto-generator`. `mount.usr=`; `mount.usrfstype=`; `mount.usrflags=` Configures the /usr file system (if required) and its file system type and mount options. For details, see `systemd-fstab-generator(8)`. `veritytab=`; `rd.veritytab=`; `roothash=`; `systemd.verity=`; `rd.systemd.verity=`; `systemd.verity_root_data=`; `systemd.verity_root_hash=`; `systemd.verity_root_options=`; `usrhash=`; `systemd.verity_usr_data=`; `systemd.verity_usr_hash=`; `systemd.verity_usr_options=` Configures the integrity protection root hash for the root and `/usr` file systems, and other related parameters. For details, see `systemd-veritysetup-generator(8)`. `systemd.getty_auto=` Configures whether the `serial-getty@.service` will run. For details, see `systemd-getty-generator(8)`. `systemd.gpt_auto=`; `rd.systemd.gpt_auto=` Configures whether GPT-based partition auto-discovery shall be attempted. For details, see `systemd-gpt-auto-generator(8)`. `systemd.image_policy=` When GPT-based partition auto-discovery is used, configures the image dissection policy string to apply, as per `systemd.image-policy(7)`. For details see `systemd-gpt-auto-generator(8)`. `systemd.image_filter=` When GPT-based partition auto-discovery is used, configures the image dissection filter string to apply, as per `systemd.image-filter(7)`. For details see `systemd-gpt-auto-generator(8)`. `systemd.default_timeout_start_sec=` Overrides the default start job timeout `DefaultTimeoutStartSec=` at boot. For details, see `systemd-system.conf(5)`. `systemd.default_device_timeout_sec=` Overrides the default device timeout `DefaultDeviceTimeoutSec=` at boot. For details, see `systemd-system.conf(5)`. `systemd.watchdog_device=` Overrides the watchdog device path `WatchdogDevice=`. For details, see `systemd-system.conf(5)`. `systemd.watchdog_sec=` Overrides the watchdog timeout settings otherwise configured with `RuntimeWatchdog=`, `RebootWatchdog=` and `KExecWatchdogSec=`. Takes a time value (if no unit is specified, seconds is the implicitly assumed time unit) or the special strings `off` or `default`. For details, see `systemd-system.conf(5)`. `systemd.watchdog_pre_sec=` Overrides the watchdog pre-timeout settings otherwise configured with `RuntimeWatchdogPreSec=`. Takes a time value (if no unit is specified, seconds is the implicitly assumed time unit) or the special strings `off` or `default`. For details, see `systemd-system.conf(5)`. `systemd.watchdog_pretimeout_governor=` Overrides the watchdog pre-timeout settings otherwise configured with `RuntimeWatchdogPreGovernor=`. Takes a string value. For details, see `systemd-system.conf(5)`. `systemd.cpu_affinity=` Overrides the CPU affinity mask for the service manager and the default for all child processes it forks. This takes precedence over `CPUAffinity=`, see `systemd-system.conf(5)` for details. `modules_load=`; `rd.modules_load=` Load a specific kernel module early at boot. For details, see `systemd-modules-load.service(8)`. `nameserver=`; `domain=` Configures DNS server information and search domains, see `systemd-resolved.service(8)` for details. `resume=`; `resumeflags=` Enable resume from hibernation using the specified device and timeout options. All `fstab(5)`-style device identifiers are supported. For details, see `systemd-hibernate-resume-generator(8)`. `resume_offset=` Configure the page offset of the swap space from the resume device. For details, see `systemd-hibernate-resume-generator(8)`. `systemd.firstboot=` Takes a boolean argument or the special value `headless`, defaults to on. If off, `systemd-firstboot.service(1)` and `systemd-homed-firstboot.service(1)` will not query the user for basic system settings, even if the system boots up for the first time and the relevant settings are not initialized yet. If set to `headless`, the same interactive prompts are suppressed as with `no`, but non-interactive auto-configuration that requires no user input is still performed (for example, selecting the only installed locale, or applying settings provided via credentials). This is useful for unattended installations that should be provisioned as far as possible without ever blocking on a prompt. Not to be confused with `systemd.condition_first_boot=` (see below), which overrides the result of the `ConditionFirstBoot=` unit file condition, and thus controls more than just `systemd-firstboot.service` behaviour. `systemd.condition_needs_update=` Takes a boolean argument. If specified, overrides the result of `ConditionNeedsUpdate=` unit condition checks. See `systemd.unit(5)` for details. `systemd.condition_first_boot=` Takes a boolean argument. If specified, overrides the result of `ConditionFirstBoot=` unit condition checks. See `systemd.unit(5)` for details. Not to be confused with `systemd.firstboot=` which only controls behaviour of the `systemd-firstboot.service` system service but has no effect on the condition check (see above). `systemd.clock_usec=` Takes a decimal, numeric timestamp in μs since January 1st 1970, 00:00am, to set the system clock to. The system time is set to the specified timestamp early during boot. It is not propagated to the hardware clock (RTC). `systemd.random_seed=` Takes a base64 encoded random seed value to credit with full entropy to the kernel's random pool during early service manager initialization. This option is useful in testing environments where delays due to random pool initialization in entropy starved virtual machines shall be avoided. Note that if this option is used the seed is accessible to unprivileged programs from `/proc/cmdline`. This option is hence a security risk when used outside of test systems, since the (possibly) only seed used for initialization of the kernel's entropy pool might be easily acquired by unprivileged programs. It is recommended to pass 512 bytes of randomized data (as that matches the Linux kernel pool size), which may be generated with a command like the following: dd if=/dev/urandom bs=512 count=1 status=none | base64 -w 0 Again: do not use this option outside of testing environments, it is a security risk elsewhere, as secret key material derived from the entropy pool can possibly be reconstructed by unprivileged programs. `systemd.allow_userspace_verity=` Takes a boolean argument. Controls whether disk images that are Verity protected may be authenticated in userspace signature checks via `/etc/verity.d/*.crt` (and related directories) public key drop-ins, or whether in-kernel signature checking only. Defaults to on. `systemd.hostname=` Accepts a hostname to set during early boot. If specified takes precedence over what is set in `/etc/hostname`. Note that this does not bar later runtime changes to the hostname, it simply controls the initial hostname set during early boot. The name may use the `?` and `$` wildcard patterns documented in `hostname(5)`, which are expanded deterministically from the machine ID each time the name is applied. The expanded name is never persisted, hence it may change if the word lists change. Note that in the initrd the word lists (and possibly the machine ID) are typically not available; the option is then ignored and the hostname is instead determined from the other sources, i.e. `/etc/hostname` or the `system.hostname` credential, falling back to the default hostname if none of those apply. `systemd.tty.term.tty=`; `systemd.tty.rows.tty=`; `systemd.tty.columns.tty=` These arguments allow configuring default values for `$TERM`, `TTYRows=`, and `TTYColumns=` for tty \. Additionally, `systemd.tty.term.console` will configure the `$TERM` value used by `systemd` if not set explicitly using `TERM` on the kernel command line. The tty name should be specified without the `/dev/` prefix (e.g. `systemd.tty.rows.ttyS0=80`). `systemd.battery_check=` Accepts a boolean argument. If false the boot-time battery charge check implemented by `systemd-battery-check.service(8)` is disabled. `ifname=`; `net.ifname_policy=` Controls interface naming policies, implemented by `systemd-network-generator.service(8)`. `systemd.efivars_allow_clear=` Controls whether to allow erasing of the boot loader's EFI variables, implemented by `systemd-efivars-clear.service(8)`. `systemd.tpm2_allow_clear=` Controls whether to allow clearing of the TPM chip, implemented by `systemd-tpm2-clear.service(8)`. `systemd.tpm2_wait=` Controls whether to wait for a TPM2 device at boot, implemented by `systemd-tpm2-generator(8)`. `systemd.tpm2_software_fallback=` Controls whether to start a fallback software TPM service in case a hardware TPM is not available, implemented by `systemd-tpm2-generator(8)`. `systemd.tpm2_measured_os=` Controls whether to execute various boot and runtime TPM PCR measurements. Takes a boolean argument. If not specified explicitly this behaviour is enabled automatically in case `systemd-stub(7)` is used and it succeeded in doing pre-boot measurements of the booted UKI, and otherwise disabled. `systemd.factory_reset=` Controls whether to boot into factory reset mode, implemented by `systemd-factory-reset-generator(8)`, `systemd-repart(8)`, and other tools. `systemd.imds=`; `systemd.imds.*=` Controls various Instance Metadata Service (IMDS) cloud aspects, see `systemd-imdsd@.service(8)` and `systemd-imds-generator(8)` for details. `systemd.sysext=`; `systemd.confext=`; `rd.systemd.sysext=`; `rd.systemd.confext=` Take boolean arguments, default to on. Control whether system and configuration extensions for the initrd (`rd.systemd.sysext=`, `rd.systemd.confext=`) and for the main system (`systemd.sysext=`, `systemd.confext=`) are merged automatically on boot. See `systemd-sysext(8)` for details. # History systemd 252 Kernel command-line arguments `systemd.unified_cgroup_hierarchy` and `systemd.legacy_systemd_cgroup_controller` were deprecated. Please switch to the unified cgroup hierarchy. # See Also `systemd(1)`, `systemd-system.conf(5)`, `bootparam(7)`, `systemd.system-credentials(7)`, `smbios-type-11(7)`, `systemd-debug-generator(8)`, `systemd-fsck@.service(8)`, `systemd-quotacheck@.service(8)`, `systemd-journald.service(8)`, `systemd-vconsole-setup.service(8)`, `systemd-udevd.service(8)`, `plymouth(8)`, `systemd-cryptsetup-generator(8)`, `systemd-veritysetup-generator(8)`, `systemd-fstab-generator(8)`, `systemd-getty-generator(8)`, `systemd-gpt-auto-generator(8)`, `systemd-volatile-root.service(8)`, `systemd-modules-load.service(8)`, `systemd-backlight@.service(8)`, `systemd-rfkill.service(8)`, `systemd-hibernate-resume-generator(8)`, `systemd-firstboot.service(1)`, `bootctl(1)` # kernel-install systemd kernel-install 8 kernel-install Add and remove kernel and initrd images to and from the boot partition kernel-install OPTIONS add KERNEL-VERSION KERNEL-IMAGE INITRD-FILE kernel-install OPTIONS add-all kernel-install OPTIONS remove KERNEL-VERSION kernel-install OPTIONS inspect KERNEL-VERSION KERNEL-IMAGE INITRD-FILE kernel-install OPTIONS list # Description `kernel-install` is used to install and remove kernel and initrd images [^1] to and from the boot partition, referred to as `$BOOT` here. It will usually be one of `/boot/`, `/efi/`, or `/boot/efi/`, see below. `kernel-install` will run the executable files ("plugins") located in the directory `/usr/lib/kernel/install.d/` and the local administration directory `/etc/kernel/install.d/`. All files are collectively sorted and executed in lexicographic order, regardless of the directory in which they live. However, files with identical filenames replace each other. Files in `/etc/kernel/install.d/` take precedence over files with the same name in `/usr/lib/kernel/install.d/`. This can be used to override a system-supplied executables with a local file if needed; a symbolic link in `/etc/kernel/install.d/` with the same name as an executable in `/usr/lib/kernel/install.d/`, pointing to `/dev/null`, disables the executable entirely. Executables must have the extension `.install`; other extensions are ignored. An executable placed in these directories should return `0` on success. It may also return `77` to cause the whole operation to terminate (executables later in lexicographic order will be skipped). # Commands The following commands are understood: `add [[[KERNEL-VERSION] KERNEL-IMAGE] [INITRD-FILE ...]]` This command takes a kernel version string and a path to a kernel image file as arguments. If the former is omitted, specified as an empty string or as "-" it defaults to the current kernel version, i.e. the same string `uname -r` returns. If the latter is omitted, specified as an empty string or as "-" defaults to `/usr/lib/modules/KERNEL_VERSION/vmlinuz`. Optionally, one or more initrd images may be specified as well (note that plugins might generate additional ones). The executable files from `/usr/lib/kernel/install.d/*.install` and `/etc/kernel/install.d/*.install` (i.e. the plugins) are called with the following arguments: add KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...] The third argument directly refers to the path where to place kernel images, initrd images and other resources for [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#1 entries (the "entry directory"). If other boot loader schemes are used the parameter may be ignored. The \ string is typically the machine ID and is supposed to identify the local installation on the system. For details see below. `kernel-install` creates `$BOOT/ENTRY-TOKEN/KERNEL-VERSION`, if enabled (see `$KERNEL_INSTALL_LAYOUT`). Three default plugins execute the following operations in this case: `50-depmod.install` The plugin runs `depmod(8)` for the \. `90-loaderentry.install` The plugin copies \ to `$BOOT/ENTRY-TOKEN/KERNEL-VERSION/linux`. If \s are provided, it also copies them to `$BOOT/ENTRY-TOKEN/KERNEL_VERSION/INITRD-FILE`. This can also be used to prepend microcode before the actual initrd. It also creates a boot loader entry according to the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) (Type \#1) in `$BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf`. The title of the entry is the \ parameter specified in `/etc/os-release` or `/usr/lib/os-release` (if the former is missing), or "Linux \", if unset. If `$KERNEL_INSTALL_LAYOUT` is not "bls", this plugin does nothing. `90-uki-copy.install` If `$KERNEL_INSTALL_STAGING_AREA/uki.efi` exists, the plugin copies it to `$BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi`. Also, files in `$KERNEL_INSTALL_STAGING_AREA/uki.efi.extra.d"/` are copied to `$BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi.extra.d/`. If `$KERNEL_INSTALL_STAGING_AREA/uki.efi` does not exist, and the \ argument has a `.efi` extension, the plugin copies the image to `$BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi`. Also, files in `KERNEL-IMAGE.extra.d/` and `$KERNEL_INSTALL_STAGING_AREA/uki.efi.extra.d"/` are copied to `$BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi.extra.d/`. If `$KERNEL_INSTALL_LAYOUT` is not "uki", this plugin does nothing. `add-all` This is the same as `add` (see above), but invokes the operation iteratively for every installed kernel in `/usr/lib/modules/`. This operation is only supported on systems where the kernel image is installed in `/usr/lib/modules/KERNEL-VERSION/vmlinuz`. `remove KERNEL-VERSION` This command expects a kernel version string as single argument. The executable files from `/usr/lib/kernel/install.d/*.install` and `/etc/kernel/install.d/*.install` (i.e. the plugins) are called with the following arguments: remove KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ Afterwards, `kernel-install` removes the entry directory `$BOOT/ENTRY-TOKEN/KERNEL-VERSION/` and its contents, if it exists. Three default plugins execute the following operations in this case: `50-depmod.install` The plugin removes the files generated by `depmod` for this kernel again. `90-loaderentry.install` The plugin removes the file `$BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf`. `90-uki-copy.install` The plugin removes the file `$BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi` and `$BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi.extra.d/` directory including its contents. `inspect [[[KERNEL-VERSION] KERNEL-IMAGE] [INITRD-FILE ...]]` Takes the same parameters as `add`. Shows the various paths and parameters configured or auto-detected. In particular shows the values of the various `$KERNEL_INSTALL_*` environment variables listed below, as they would be passed to plugins. The `--json` option can be used to get the output of this verb as a JSON object. `list` Shows the various installed kernels. This enumerates the subdirectories of `/usr/lib/modules/`, and shows whether a kernel image is installed there. # Compatibility with the kernel build system installkernel OPTIONS VERSION VMLINUZ MAP INSTALLATION-DIR When invoked as `installkernel`, this program accepts arguments as specified by the kernel build system's `make install` command. The `VERSION` and `VMLINUZ` parameters specify the kernel version and the kernel binary. The other two parameters (`MAP` and `INSTALLATION-DIR`) are currently ignored. # The `$BOOT` partition The partition where the kernels and [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) snippets are located is called `$BOOT`. `kernel-install` determines the location of this partition by checking `/efi/`, `/boot/`, and `/boot/efi/` in turn. The first location where `$BOOT/loader/entries/` or `$BOOT/ENTRY-TOKEN/` exists is used. # Options The following options are understood: `--make-entry-directory=yes|no|auto` Controls creation and deletion of the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#1 entry directory on the file system containing resources such as kernel and initrd images during `add` and `remove`, respectively. The directory is named after the entry token, and is placed immediately below the boot root directory. When `auto`, the directory is created or removed only when the install layout is `bls`. Defaults to `auto`. `--entry-type=type1|type2|all` Controls the type of entries handled by the command. This is typically useful when multiple types of boot entries with the same kernel version are installed, and only one should be removed. When `type1` or `type2` is specified, each plugin is invoked with `$KERNEL_INSTALL_BOOT_ENTRY_TYPE` environment variable with the specified value. When `all` is specified, the environment variable will not be set. Defaults to `all`. `--entry-token=` Controls how to name and identify boot loader entries for this kernel installation or deletion. Takes one of `auto`, `machine-id`, `os-id`, `os-image-id`, or an arbitrary string prefixed by `literal:` as argument. If set to `machine-id` the entries are named after the machine ID of the running system (e.g. `b0e793a9baf14b5fa13ecbe84ff637ac`). See `machine-id(5)` for details about the machine ID concept and file. If set to `os-id` the entries are named after the OS ID of the running system, i.e. the `ID=` field of `os-release(5)` (e.g. `fedora`). Similarly, if set to `os-image-id` the entries are named after the OS image ID of the running system, i.e. the `IMAGE_ID=` field of `os-release` (e.g. `vendorx-cashier-system`). If set to `auto` (the default), the `/etc/kernel/entry-token` (or `$KERNEL_INSTALL_CONF_ROOT/entry-token`) file will be read if it exists, and the stored value used. Otherwise, if the local machine ID is initialized, it is used. Otherwise, `IMAGE_ID=` from `os-release` will be used, if set. Otherwise, `ID=` from `os-release` will be used, if set. Otherwise, a randomly generated machine ID is used. Using the machine ID for naming the entries is generally preferable, however there are cases where using the other identifiers is a good option. Specifically: if the identification data that the machine ID entails shall not be stored on the (unencrypted) `$BOOT_ROOT` partition, or if the ID shall be generated on first boot and is not known when the entries are prepared. Note that using the machine ID has the benefit that multiple parallel installations of the same OS can coexist on the same medium, and they can update their boot loader entries independently. When using another identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to use the same entry name. To support parallel installations, the installer must use a different entry token when adding a second installation. `-v`; `--verbose` Output additional information about operations being performed. `--root=root` Takes a directory path as an argument. All paths will be prefixed with the given alternate \ path, including config search paths. This is useful to operate on a system image mounted to the specified directory instead of the host system itself. `--image=image` Takes a path to a disk image file or block device node. If specified, all operations are applied to the file system in the indicated disk image. This option is similar to `--root=`, but operates on file systems stored in disk images or block devices. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). For further information on supported disk images, see `systemd-nspawn(1)`'s switch of the same name. # Environment variables ## Environment variables exported for plugins If `--verbose` is used, `$KERNEL_INSTALL_VERBOSE=1` will be exported for plugins. They may output additional logs in this case. `$KERNEL_INSTALL_IMAGE_TYPE=uki|pe|unknown` is set for the plugins to specify the type of the kernel image. uki Unified kernel image. pe PE binary. unknown Unknown type. `$KERNEL_INSTALL_MACHINE_ID` is set for the plugins to the desired machine-id to use. It's always a 128-bit ID. Normally it is read from `/etc/machine-id`, but it can also be overridden via `$MACHINE_ID` (see below). If not specified via these methods, a fallback value will generated by `kernel-install` and used only for a single invocation. `$KERNEL_INSTALL_ENTRY_TOKEN` is set for the plugins to the desired entry "token" to use. It's an identifier that shall be used to identify the local installation, and is often the machine ID, i.e. same as `$KERNEL_INSTALL_MACHINE_ID`, but might also be a different type of identifier, for example a fixed string or the `ID=`, `IMAGE_ID=` values from `/etc/os-release`. The string passed here will be used to name Boot Loader Specification entries, or the directories the kernel image and initial RAM disk images are placed into. Note that while `$KERNEL_INSTALL_ENTRY_TOKEN` and `$KERNEL_INSTALL_MACHINE_ID` are often set to the same value, the latter is guaranteed to be a valid 32 character ID in lowercase hexadecimals while the former can be any short string. The entry token to use is read from `/etc/kernel/entry-token`, if it exists. Otherwise, a few possible candidates below `$BOOT` are checked for Boot Loader Specification Type 1 entry directories, and if found the entry token is derived from that. If that is not successful, `$KERNEL_INSTALL_MACHINE_ID` is used as fallback. `$KERNEL_INSTALL_BOOT_ROOT` is set for the plugins to the absolute path of the root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and associated resources should be placed. This usually is the path where the XBOOTLDR partition or the ESP (EFI System Partition) are mounted, and also conceptually referred to as `$BOOT`. Can be overridden by setting `$BOOT_ROOT` (see below). `$KERNEL_INSTALL_LAYOUT=auto|bls|uki|other|...` is set for the plugins to specify the installation layout. Additional layout names may be defined by convention. If a plugin uses a special layout, it is encouraged to declare its own layout name and configure `layout=` in `install.conf` upon initial installation. The following values are currently understood: bls Standard [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#1 layout, compatible with `systemd-boot(7)`: entries in `$BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION[+TRIES].conf`, kernel and initrds under `$BOOT/ENTRY-TOKEN/KERNEL-VERSION/` Implemented by `90-loaderentry.install`. uki Standard [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#2 layout, compatible with `systemd-boot(7)`: unified kernel images under `$BOOT/EFI/Linux` as `$BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION[+TRIES].efi`. Implemented by `90-uki-copy.install`. other Some other layout not understood natively by `kernel-install`. auto Pick the layout automatically. If the kernel is a UKI set layout to `uki`. If not default to `bls` if `$BOOT/loader/entries.srel` with content `type1` or `$BOOT/ENTRY-TOKEN` exists, or `other` otherwise. Leaving layout blank has the same effect. This is the default. `$KERNEL_INSTALL_INITRD_GENERATOR` and `$KERNEL_INSTALL_UKI_GENERATOR` are set for plugins to select the initrd and/or UKI generator. This may be configured as `initrd_generator=` and `uki_generator=` in `install.conf`, see below. `$KERNEL_INSTALL_STAGING_AREA` is set for plugins to a path to a directory. Plugins may drop files in that directory, and they will be installed as part of the loader entry, based on the file name and extension: Files named `initrd*` will be installed as \s, and files named `microcode*` will be prepended before \s. `$KERNEL_INSTALL_ENTRY_NAME` is set for the plugins to the resolved entry name, derived by expanding specifiers in the entry name format string. This is the base name (without file extension) used for UKI files, loader entry configuration files, and similar. By default this is `ENTRY-TOKEN-KERNEL-VERSION`, matching the traditional naming. See `$KERNEL_INSTALL_ENTRY_NAME_FORMAT` below for details on the available specifiers. ## Environment variables understood by `kernel-install` `$KERNEL_INSTALL_CONF_ROOT` can be set to override the location of the configuration files read by `kernel-install`. When set, `install.conf`, `entry-token`, and other files will be read from this directory only. Note that this path is relative to the host, and in particular *symlinks in this directory are resolved relative to the host*, even if `--root=root` is used. This means that it is generally *not* correct to use this variable to specify a directory underneath \ if symlinks are used there. `$KERNEL_INSTALL_PLUGINS` can be set to override the list of plugins executed by `kernel-install`. The argument is a whitespace-separated list of paths. `KERNEL_INSTALL_PLUGINS=:` may be used to prevent any plugins from running. `$MACHINE_ID` can be set for `kernel-install` to override `$KERNEL_INSTALL_MACHINE_ID`, the machine ID. `$BOOT_ROOT` can be set for `kernel-install` to override `$KERNEL_INSTALL_BOOT_ROOT`, the installation location for boot entries. The last two variables may also be set in `install.conf`. Variables set in the environment take precedence over the values specified in the config file. `$KERNEL_INSTALL_ENTRY_NAME_FORMAT` can be set to configure the format string used to derive the entry name for boot loader entries and UKI files. The format string is expanded using specifier expansion. May also be configured as `entry_name_format=` in `install.conf`. The following specifiers are understood: | Specifier | Meaning | Details | |----|----|----| | `%e` | Entry token | The entry token, same as `$KERNEL_INSTALL_ENTRY_TOKEN`. | | `%v` | Kernel version | The kernel version being installed. Note that unlike the common specifier `%v` which expands to the currently running kernel version (i.e. `uname -r`), here it refers to the target kernel version passed to `kernel-install`. | Specifiers available in `$KERNEL_INSTALL_ENTRY_NAME_FORMAT` {.specifiers} The resolved entry name must be a valid filename (no path separators). Defaults to `%e-%v`, which produces the traditional `ENTRY-TOKEN-KERNEL-VERSION` naming. For example, setting `entry_name_format=%M_%A_%a` on a system with `IMAGE_ID=myos`, `IMAGE_VERSION=20250830`, and architecture `x86-64` would produce entry names like `myos_20250830_x86-64`. Note that the entry name is resolved at the time of each `kernel-install` invocation. If the format string uses specifiers that depend on mutable system state (e.g. `%M`, `%A`, `%H`), and that state changes between installing and removing a kernel, the `remove` operation may compute a different entry name than `add` did, leaving stale files on the boot partition. The `entry_name_format=` setting should therefore remain stable across a kernel's install/remove lifecycle. Additionally, the format should produce a unique name for each installed kernel, e.g. by including `%v` (kernel version) or `%A` (`IMAGE_VERSION`); otherwise installing multiple kernels will overwrite each other's boot entries. # Exit status If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise. # Files `/etc/kernel/install.d/*.install`; `/usr/lib/kernel/install.d/*.install` Drop-in files which are executed by `kernel-install`. `/etc/kernel/cmdline`; `/usr/lib/kernel/cmdline`; `/proc/cmdline` Specifies the kernel command line to use. The first of the files that is found will be used. Lines starting with the `#` character are ignored. When running in a container, `/proc/cmdline` is ignored. `$KERNEL_INSTALL_CONF_ROOT` may be used to override the search path; see below for details. `/etc/kernel/devicetree`; `/usr/lib/kernel/devicetree` Specifies the partial path to the file containing the device tree blob to install with the kernel and use at boot. The first of the files that is found will be used. `$KERNEL_INSTALL_CONF_ROOT` may be used to override the search path; see below for details. The `devicetree` file contains a path, and this path specifies a location relative to the kernel install tree. A set of locations is checked, including in particular `/usr/lib/modules/KERNEL_VERSION/dtb/`, which is the recommended location to place the dtb files under. For example, with `broadcom/bcm2711-rpi-4-b.dtb` in the `devicetree` file, the device tree blob for the Raspberry Pi 4 Model B would be installed, and the actual file would be `/usr/lib/modules/KERNEL_VERSION/dtb/broadcom/bcm2711-rpi-4-b.dtb`. `/etc/kernel/tries`; `/run/kernel/tries`; `/usr/lib/kernel/tries` Read by `90-loaderentry.install` and `90-uki-copy.install`. A numeric value is read from the first file found, and the generated entry file or UKI is named to include it as `$BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION+TRIES.conf` or `$BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION+TRIES.efi`, respectively. This is useful for boot loaders such as `systemd-boot(7)` which implement boot attempt counting with a counter embedded in the entry file name. A symlink to `/dev/null` disables boot counting, overriding files lower in the search order. `$KERNEL_INSTALL_CONF_ROOT` may be used to override the search path; see below for details. `/etc/kernel/entry-token` If this file exists it is read and used as "entry token" for this system, i.e. is used for naming Boot Loader Specification entries. See `$KERNEL_INSTALL_ENTRY_TOKEN` above for details. `$KERNEL_INSTALL_CONF_ROOT` may be used to override the search path; see below for details. `/etc/machine-id` The content of this file specifies the machine identification \. `/etc/os-release`; `/usr/lib/os-release` Read by `90-loaderentry.install`. If available, `PRETTY_NAME=` is read from these files and used as the title of the boot menu entry. Otherwise, `Linux KERNEL-VERSION` will be used. `/etc/kernel/install.conf`; `/run/kernel/install.conf`; `/usr/local/lib/kernel/install.conf`; `/usr/lib/kernel/install.conf`; `/etc/kernel/install.conf.d/*.conf`; `/run/kernel/install.conf.d/*.conf`; `/usr/local/lib/kernel/install.conf.d/*.conf`; `/usr/lib/kernel/install.conf.d/*.conf` Configuration file with options for `kernel-install`, as a series of `KEY=`\ assignments, compatible with shell syntax, following the same rules as described in `os-release(5)`. The first of the files that is found will be used. `$KERNEL_INSTALL_CONF_ROOT` may be used to override the search path; see below for details. Drop-in files may also be used to extend the configuration with overrides, see `systemd.unit(5)`. Currently, the following keys are supported: `MACHINE_ID=`, `BOOT_ROOT=`, `layout=`, `initrd_generator=`, `uki_generator=`, `entry_name_format=`. See the Environment variables section above for details. `/etc/kernel/uki.conf` Ini-style configuration file for `ukify(1)` which is only effective when `$KERNEL_INSTALL_LAYOUT` or `layout=` in `install.conf` is set to `uki` and `$KERNEL_INSTALL_UKI_GENERATOR` or `uki_generator=` in `install.conf` is set to `ukify`, or is unset. `$KERNEL_INSTALL_CONF_ROOT` may be used to override the search path; see below for details. `/usr/lib/modules/KERNEL-VERSION/` Location for installed kernel modules and other kernel related resources. For each locally installed kernel a directory named after the kernel version (`uname -r`) is kept. `/usr/lib/modules/KERNEL-VERSION/vmlinuz` Location for installed kernel images. This is the recommended location for OS package managers to install kernel images into (as applicable), from which `kernel-install add` then copies it into the final boot partition. For various cases listed above, if the `$KERNEL_INSTALL_CONF_ROOT` environment variable is set, it will override the search path. The files will be loaded *only* from the directory specified by the environment variable. When the variable is not set, the listed paths are tried in turn, and the first file that exists is used. # See Also `machine-id(5)`, `os-release(5)`, `depmod(8)`, `systemd-boot(7)`, `ukify(1)`, [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) [^1]: Nowadays actually CPIO archives used as an "initramfs", rather than "initrd". See `bootup(7)` for an explanation. # Notes Functions described here are available as a shared library, which can be compiled against and linked to with the `libsystemd` `pkg-config(1)` file. # libsystemd systemd libsystemd 3 libsystemd Functions for implementing services and interacting with systemd #include #include #include #include #include #include #include #include #include #include #include #include #include pkg-config --cflags --libs libsystemd # Description The `libsystemd` library provides functions that allow interacting with various interfaces provided by the `systemd(1)` service manager, as well as various other functions and constants useful for implementing services in general. See `sd-bus(3)`, `sd-bus-errors(3)`, `sd-daemon(3)`, `sd-device(3)`, `sd-event(3)`, `sd-hwdb(3)`, `sd-id128(3)`, `sd-journal(3)`, `sd-json(3)`, `sd-login(3)`, `sd-path(3)`, and `sd-varlink(3)` for information about different parts of the library interface. # Interface stability Strict backwards-compatibility is maintained for the API (application programming interface) and ABI (application binary interface). Symbol versioning is used, with symbols only added and never removed. # See Also `systemd(1)`, `libudev(3)`, `pkg-config(1)`, [Interface Portability and Stability Promise](https://systemd.io/PORTABILITY_AND_STABILITY/) # libudev systemd libudev 3 libudev API for enumerating and introspecting local devices \#include \ pkg-config --cflags --libs libudev # Description `libudev.h` provides an API to introspect and enumerate devices on the local system. This library is supported, but should not be used in new projects. Please see `sd-device(3)` for an equivalent replacement with a more modern API. All functions require a libudev context to operate. This context can be created via `udev_new(3)`. It is used to track library state and link objects together. No global state is used by libudev, everything is always linked to a udev context. To introspect a local device on a system, a udev device object can be created via `udev_device_new_from_syspath(3)` and friends. The device object allows one to query current state, read and write attributes and lookup properties of the device in question. To enumerate local devices on the system, an enumeration object can be created via `udev_enumerate_new(3)`. To monitor the local system for hotplugged or unplugged devices, a monitor can be created via `udev_monitor_new_from_netlink(3)`. Whenever libudev returns a list of objects, the `udev_list_entry(3)` API should be used to iterate, access and modify those lists. Furthermore, libudev also exports legacy APIs that should not be used by new software (and as such are not documented as part of this manual). This includes the hardware database known as `udev_hwdb` (please use the new `sd-hwdb(3)` API instead) and the `udev_queue` object to query the udev daemon (which should not be used by new software at all). # See Also `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_enumerate_new(3)`, `udev_monitor_new_from_netlink(3)`, `udev_list_entry(3)`, `systemd(1)`, `sd-device(3)`, `sd-hwdb(3)`, `pkg-config(1)` # loader.conf systemd loader.conf 5 loader.conf Configuration file for systemd-boot `ESP/loader/loader.conf` # Description `systemd-boot(7)` reads `ESP/loader/loader.conf`. This file configures whether the menu is shown and for how long, the font, audible beep, types of menu entries to show, the default choice, and some aspects of Secure Boot enrollment and firmware handling. See the list of available options below. The file uses UTF-8 encoding and consists of series of lines separated by "line feed" (i.e. ASCII code 10). Lines that are empty or start with the comment sign (`#`) are ignored. Other lines consist of an option name, followed by whitespace, and the option value. Boolean arguments may be written as `yes`/`y`/`true`/`t`/`on`/`1` or `no`/`n`/`false`/`f`/`off`/`0`. Note: `systemd-boot` will also read boot loader entry files, type \#1 (`ESP/loader/entries/*.conf` and `XBOOTLDR/loader/entries/*.conf`) and type \#2 (`ESP/EFI/Linux/*.uki` and `XBOOTLDR/EFI/Linux/*.uki`). Those files are described by the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification). Note: the behaviour of `systemd-boot` is also influenced by EFI variables. Some of the settings specified in this file can be overridden by those, for example the default boot menu entry or the menu timeouts. See `systemd-boot(7)` for details. # Options The following configuration are supported in `loader.conf`: default A glob pattern to select the default entry by id, which is the file name including literal suffix `.conf`. The default entry may be changed in the boot menu itself, in which case the name of the selected entry will be stored as an EFI variable, overriding this option. If set to `@saved` the chosen entry will be saved as an EFI variable on every boot and automatically selected the next time the boot loader starts. | Name | Description | |-------------------------------|--------------------------------| | auto-efi-default | EFI Default Loader | | auto-efi-shell | EFI Shell | | auto-osx | macOS | | auto-poweroff | Power Off The System | | auto-reboot | Reboot The System | | auto-reboot-to-firmware-setup | Reboot Into Firmware Interface | | auto-windows | Windows Boot Manager | Automatically detected entries will use the following names: Supported glob wildcard patterns are `?`, `*`, and `[…]` (including ranges). Note that these patterns use the same syntax as `glob(7)`, but do not support all features. In particular, set negation and named character classes are not supported. The matching is done case-insensitively on the entry ID (as shown by `bootctl list`). timeout How long the boot menu should be shown before the default entry is booted, in seconds. This may be changed in the boot menu itself and will be stored as an EFI variable in that case, overriding this option. If set to `menu-disabled` or `menu-hidden` or `0` (the default), no menu is shown and the default entry will be booted immediately. Unless `menu-disabled` is used, the menu can be shown by pressing and holding a key before systemd-boot is launched. Setting this to `menu-force` disables the timeout while always showing the menu. console-mode This option configures the resolution of the console. This may be changed in the boot menu itself and will be stored as an EFI variable in that case, overriding this option. Takes a number or one of the special values listed below. The following values may be used: 0 Standard UEFI 80x25 mode 1 80x50 mode, not supported by all devices 2 the first non-standard mode provided by the device firmware, if any auto Pick a suitable mode automatically using heuristics max Pick the highest-numbered available mode keep Keep the mode selected by firmware (the default) editor Takes a boolean argument. Enable (the default) or disable the editor. The editor should be disabled if the machine can be accessed by unauthorized persons. auto-entries Takes a boolean argument. Enable (the default) or disable entries for other boot entries found on the boot partition. In particular, this may be useful when loader entries are created to show replacement descriptions for those entries. auto-firmware A boolean controlling the presence of the `Reboot Into Firmware Interface` entry (enabled by default). If this is disabled, the firmware interface may still be reached by using the f key. auto-reboot A boolean controlling the presence of the `Reboot The System` entry (disabled by default). Even if this is disabled, the system may still be rebooted by pressing Shift+b. auto-poweroff A boolean controlling the presence of the `Power Off The System` entry (disabled by default). Even if this is disabled, the system may still be powered off by pressing Shift+o. beep Takes a boolean argument. If timeout enabled beep every second, otherwise beep n times when n-th entry in boot menu is selected (default disabled). Currently, only x86 is supported, where it uses the PC speaker. secure-boot-enroll Danger: this feature might soft-brick your device if used improperly. Controls enrollment of secure boot keys found on the ESP if the system is in setup mode: `if-safe` This is the default. Same behavior as `manual`, but will try to automatically enroll the key named `auto` if it is considered to be safe. Currently, this is only the case if the system is running inside a virtual machine. `manual` Boot entries for found secure boot keys are created that allow manual enrollment. `off` No action is taken. `force` Always enroll the `auto` key if found. Note that a warning message with a timeout will still be shown if this operation is unknown to be safe. The different sets of variables can be set up under `/loader/keys/NAME` where \ is the name that is going to be used as the name of the entry. This allows one to ship multiple sets of Secure Boot variables and choose which one to enroll at runtime. Supported Secure Boot variables are one database for authorized images, one for the key exchange key (KEK) and one for the platform key (PK). For more information, refer to the [UEFI specification](https://uefi.org/specifications), under Secure Boot and Driver Signing. Another resource that describe the interplay of the different variables is the [ EDK2 documentation](https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/uefi_secure_boot). A complete set of UEFI variable includes `db.auth`, `KEK.auth` and `PK.auth`. Note that these files need to be authenticated UEFI variables. See below for an example of how to generate them from regular X.509 keys. uuid=$(systemd-id128 new --uuid) for key in PK KEK db; do openssl req -new -x509 -subj "/CN=${key}/" -keyout "${key}.key" -out "${key}.pem" openssl x509 -outform DER -in "${key}.pem" -out "${key}.der" sbsiglist --owner "${uuid}" --type x509 --output "${key}.esl" "${key}.der" done # See also: Windows Secure Boot Key Creation and Management Guidance curl --location \ "https://go.microsoft.com/fwlink/p/?linkid=321192" -o ms-db-2011.der \ "https://go.microsoft.com/fwlink/p/?linkid=321185" -o ms-kek-2011.der \ "https://go.microsoft.com/fwlink/p/?linkid=321194" -o ms-uefi-db-2011.der \ "https://go.microsoft.com/fwlink/p/?linkid=2239776" -o ms-db-2023.der \ "https://go.microsoft.com/fwlink/p/?linkid=2239775" -o ms-kek-2023.der \ "https://go.microsoft.com/fwlink/p/?linkid=2239872" -o ms-uefi-db-2023.der sha1sum -c <>db.esl # Optionally add Microsoft UEFI certificates for firmware drivers / option ROMs and third-party # boot loaders (including shim). This is highly recommended on real hardware as not including this # may soft-brick your device (see next paragraph). cat ms-uefi-*.esl >>db.esl # Optionally add Microsoft KEK certificates. Recommended if either of the Microsoft keys is used as # the official UEFI revocation database is signed with this key. The revocation database can be # updated with fwupdmgr1. cat ms-kek-*.esl >>KEK.esl attr=NON_VOLATILE,RUNTIME_ACCESS,BOOTSERVICE_ACCESS,TIME_BASED_AUTHENTICATED_WRITE_ACCESS sbvarsign --attr "${attr}" --key PK.key --cert PK.pem --output PK.auth PK PK.esl sbvarsign --attr "${attr}" --key PK.key --cert PK.pem --output KEK.auth KEK KEK.esl sbvarsign --attr "${attr}" --key KEK.key --cert KEK.pem --output db.auth db db.esl This feature is considered dangerous because even if all the required files are signed with the keys being loaded, some files necessary for the system to function properly still won't be. This is especially the case with Option ROMs (e.g. for storage controllers or graphics cards). See [Secure Boot and Option ROMs](https://github.com/Foxboron/sbctl/wiki/FAQ#option-rom) for more details. secure-boot-enroll-action Specifies the action to take after the automatic enrollment of secure boot keys is completed. reboot Reboot the system after enrollment. This is the default. shutdown Shut down the system after enrollment. This option is only relevant if `secure-boot-enroll` is enabled. secure-boot-enroll-timeout-sec How long the warning should be shown in seconds before the key enrollment process starts. If set to `hidden` or `0`, no warning is shown and the keys will be enrolled immediately. The default timeout (if not set explicitly) is 15 seconds. This option is only relevant if `secure-boot-enroll` is enabled. reboot-for-bitlocker Work around BitLocker requiring a recovery key when the boot loader was updated (disabled by default). Try to detect BitLocker encrypted drives along with an active TPM. If both are found and Windows Boot Manager is selected in the boot menu, set the `BootNext` EFI variable and restart the system. The firmware will then start Windows Boot Manager directly, leaving the TPM PCRs in expected states so that Windows can unseal the encryption key. This allows `systemd-boot(7)` to be updated without having to provide the recovery key for BitLocker drive unlocking. Note that the PCRs that Windows uses can be configured with the `Configure TPM platform validation profile for native UEFI firmware configurations` group policy under `Computer Configuration\Administrative Templates\Windows Components\BitLocker Drive Encryption`. When Secure Boot is enabled, changing this to PCRs `0,2,7,11` should be safe. The TPM key protector needs to be removed and then added back for the PCRs on an already encrypted drive to change. If PCR 4 is not measured, this setting can be disabled to speed up booting into Windows. reboot-on-error Controls auto reboot in case the selected entry fails to start. `yes` Reboot the system if the selected boot entry failed to start. `no` Don't reboot - pass control back to EFI firmware. `auto` Perform the reboot if and only if boot counting is enabled for this entry and the tries left counter wasn't already at 0. This is the default, as it is typically a safe option, that ensures a clean measurement log on each boot attempt, but also does not risk an unbounded reboot loop. log-level Controls the log level used by `systemd-boot(7)`. Valid values are `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, and `debug`. If unspecified, `info` will be used, unless one has already been configured via an SMBIOS Type 11 string, see `smbios-type-11(7)`. Note that the configured level will only be used after `loader.conf` has been parsed, so log messages generated before that point may be unaffected by this setting. # Example # /boot/efi/loader/loader.conf timeout 0 default 01234567890abcdef1234567890abdf0-* editor no The menu will not be shown by default (the menu can still be shown by pressing and holding a key during boot). One of the entries with files with a name starting with `01234567890abcdef1234567890abdf0-` will be selected by default. If more than one entry matches, the one with the highest priority will be selected (generally the one with the highest version number). The editor will be disabled, so it is not possible to alter the kernel command line. # See Also `systemd-boot(7)`, `bootctl(1)` # locale.conf systemd locale.conf 5 locale.conf Configuration file for locale settings `/etc/locale.conf` # Description The `/etc/locale.conf` file configures system-wide locale settings. It is read at early boot by `systemd(1)`. The format of `locale.conf` is a newline-separated list of environment-like shell-compatible variable assignments, ignoring comments and empty lines. It is possible to source the configuration from shell scripts, however, beyond mere variable assignments, no shell features are supported, allowing applications to read the file without implementing a shell compatible execution engine. See `os-release(5)` for a detailed description of the format. Note that the kernel command line options `locale.LANG=`, `locale.LANGUAGE=`, `locale.LC_CTYPE=`, `locale.LC_NUMERIC=`, `locale.LC_TIME=`, `locale.LC_COLLATE=`, `locale.LC_MONETARY=`, `locale.LC_MESSAGES=`, `locale.LC_PAPER=`, `locale.LC_NAME=`, `locale.LC_ADDRESS=`, `locale.LC_TELEPHONE=`, `locale.LC_MEASUREMENT=`, `locale.LC_IDENTIFICATION=` may be used to override the locale settings at boot. The locale settings configured in `/etc/locale.conf` are system-wide and are inherited by every service or user, unless overridden or unset by individual programs or users. Depending on the operating system, other configuration files might be checked for locale configuration as well, however only as fallback. `/etc/locale.conf` can be updated using `systemd-localed.service(8)`. `localectl(1)` may be used to alter the settings in this file during runtime from the command line. Use `systemd-firstboot(1)` to customize them on mounted (but not booted) system images. # Options The following locale settings may be set using `/etc/locale.conf`: `LANG=`, `LANGUAGE=`, `LC_CTYPE=`, `LC_NUMERIC=`, `LC_TIME=`, `LC_COLLATE=`, `LC_MONETARY=`, `LC_MESSAGES=`, `LC_PAPER=`, `LC_NAME=`, `LC_ADDRESS=`, `LC_TELEPHONE=`, `LC_MEASUREMENT=`, `LC_IDENTIFICATION=`. Note that `LC_ALL` may not be configured in this file. For details about the meaning and semantics of these settings, refer to `locale(7)`. # Example
German locale with English messages
`/etc/locale.conf`: # Custom settings LANG=de_DE.UTF-8 LC_MESSAGES=en_US.UTF-8
# See Also `systemd(1)`, `locale(7)`, `localectl(1)`, `systemd-localed.service(8)`, `systemd-firstboot(1)` # localectl systemd localectl 1 localectl Control the system locale and keyboard layout settings localectl OPTIONS COMMAND # Description `localectl` may be used to query and change the system locale and keyboard layout settings. It communicates with `systemd-localed(8)` to modify files such as `/etc/locale.conf` and `/etc/vconsole.conf`. The system locale controls the language settings of system services and of the UI before the user logs in, such as the display manager, as well as the default for users after login. The keyboard settings control the keyboard layout used on the text console and of the graphical UI before the user logs in, such as the display manager, as well as the default for users after login. Note that the changes performed using this tool might require the initrd to be rebuilt to take effect during early system boot. The initrd is not rebuilt automatically by `localectl`, this task has to be performed manually, usually by reinstalling the distribution's kernel package. Note that `systemd-firstboot(1)` may be used to initialize the system locale for mounted (but not booted) system images. # Commands The following commands are understood: `status` Show current settings of the system locale and keyboard mapping. If no command is specified, this is the implied default. `set-locale LOCALE`; `set-locale VARIABLE=LOCALE…` Set the system locale. This takes one locale such as `en_US.UTF-8`, or takes one or more locale assignments such as `LANG=de_DE.utf8`, `LC_MESSAGES=en_GB.utf8`, and so on. If one locale without variable name is provided, then `LANG=` locale variable will be set. See `locale(7)` for details on the available settings and their meanings. Use `list-locales` for a list of available locales (see below). `list-locales` List available locales useful for configuration with `set-locale`. `set-keymap MAP [TOGGLEMAP]` Set the system keyboard mapping for the console and X11. This takes a mapping name (such as "de" or "us"), and possibly a second one to define a toggle keyboard mapping. Unless `--no-convert` is passed, the selected setting is also applied as the default system keyboard mapping of X11, after converting it to the closest matching X11 keyboard mapping. Use `list-keymaps` for a list of available keyboard mappings (see below). `list-keymaps` List available keyboard mappings for the console, useful for configuration with `set-keymap`. `set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]]` Set the system default keyboard mapping for X11 and the virtual console. This takes a keyboard mapping name (such as `de` or `us`), and possibly a model, variant, and options, see `kbd(4)` for details. Unless `--no-convert` is passed, the selected setting is also applied as the system console keyboard mapping, after converting it to the closest matching console keyboard mapping. `list-x11-keymap-models`; `list-x11-keymap-layouts`; `list-x11-keymap-variants [LAYOUT]`; `list-x11-keymap-options` List available X11 keymap models, layouts, variants and options, useful for configuration with `set-keymap`. The command `list-x11-keymap-variants` optionally takes a layout parameter to limit the output to the variants suitable for the specific layout. # Options The following options are understood: `-l`; `--full` Do not ellipsize the output. `--no-convert` If `set-keymap` or `set-x11-keymap` is invoked and this option is passed, then the keymap will not be converted from the console to X11, or X11 to console, respectively. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `locale(7)`, `locale.conf(5)`, `vconsole.conf(5)`, `loadkeys(1)`, `kbd(4)`, [ The XKB Configuration Guide ](http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html), `systemctl(1)`, `systemd-localed.service(8)`, `systemd-firstboot(1)` # localtime systemd localtime 5 localtime Local timezone configuration file `/etc/localtime` -\> `../usr/share/zoneinfo/…` # Description The `/etc/localtime` file configures the system-wide timezone of the local system that is used by applications for presentation to the user. It should be an absolute or relative symbolic link pointing to `/usr/share/zoneinfo/`, followed by a timezone identifier such as `Europe/Berlin` or `Etc/UTC`. The resulting link should lead to the corresponding binary `tzfile(5)` timezone data for the configured timezone. Because the timezone identifier is extracted from the symlink target name of `/etc/localtime`, this file may not be a normal file or hardlink. If `/etc/localtime` is missing, the default `UTC` timezone is used. The timezone may be overridden for individual programs by using the `$TZ` environment variable. See `environ(7)`. You may use `timedatectl(1)` to change the settings of this file from the command line during runtime. Use `systemd-firstboot(1)` to initialize the time zone on mounted (but not booted) system images. # See Also `systemd(1)`, `tzset(3)`, `localtime(3)`, `timedatectl(1)`, `systemd-timedated.service(8)`, `systemd-firstboot(1)` # loginctl systemd loginctl 1 loginctl Control the systemd login manager loginctl OPTIONS COMMAND NAME # Description `loginctl` may be used to introspect and control the state of the `systemd(1)` login manager `systemd-logind.service(8)`. # Commands The following commands are understood: ## Session Commands `list-sessions` List current sessions. The JSON format output can be toggled using `--json=` or `-j` option. `session-status` \[\…\] Show terse runtime status information about one or more sessions, followed by the most recent log data from the journal. Takes one or more session identifiers as parameters. If no session identifiers are passed, the status of the caller's session is shown. This function is intended to generate human-readable output. If you are looking for computer-parsable output, use `show-session` instead. `show-session` \[\…\] Show properties of one or more sessions or the manager itself. If no argument is specified, properties of the manager will be shown. If a session ID is specified, properties of the session are shown. Specially, if the given ID is `self`, the session to which the `loginctl` process belongs is used. If `auto`, the current session is used as with `self` if exists, and falls back to the current user's graphical session. By default, empty properties are suppressed. Use `--all` to show those too. To select specific properties to show, use `--property=`. This command is intended to be used whenever computer-parsable output is required. Use `session-status` if you are looking for formatted human-readable output. `activate` \[\\] Activate a session. This brings a session into the foreground if another session is currently in the foreground on the respective seat. Takes a session identifier as argument. If no argument is specified, the session of the caller is put into foreground. `lock-session` \[\…\]; `unlock-session` \[\…\] Activates/deactivates the screen lock on one or more sessions, if the session supports it. Takes one or more session identifiers as arguments. If no argument is specified, the session of the caller is locked/unlocked. `lock-sessions`; `unlock-sessions` Activates/deactivates the screen lock on all current sessions supporting it. `terminate-session` \… Terminates a session. This kills all processes of the session and deallocates all resources attached to the session. If the argument is specified as empty string the session invoking the command is terminated. `kill-session` \… Send a signal to one or more processes of the session. Use `--kill-whom=` to select which process to kill. Use `--signal=` to select the signal to send. If the argument is specified as empty string the signal is sent to the session invoking the command. ## User Commands `list-users` List currently logged in users. The JSON format output can be toggled using `--json=` or `-j` option. `user-status` \[\…\] Show terse runtime status information about one or more logged in users, followed by the most recent log data from the journal. Takes one or more user names or numeric user IDs as parameters. If no parameters are passed, the status is shown for the user of the session of the caller. This function is intended to generate human-readable output. If you are looking for computer-parsable output, use `show-user` instead. `show-user` \[\…\] Show properties of one or more users or the manager itself. If no argument is specified, properties of the manager will be shown. If a user is specified, properties of the user are shown. By default, empty properties are suppressed. Use `--all` to show those too. To select specific properties to show, use `--property=`. This command is intended to be used whenever computer-parsable output is required. Use `user-status` if you are looking for formatted human-readable output. `enable-linger` \[\…\]; `disable-linger` \[\…\] Enable/disable user lingering for one or more users. If enabled for a specific user, a user manager is spawned for the user at boot and kept around after logouts. This allows users who are not logged in to run long-running services. Takes one or more user names or numeric UIDs as argument. If no argument is specified, enables/disables lingering for the user of the session of the caller. See also `KillUserProcesses=` setting in `logind.conf(5)`. `terminate-user` \… Terminates all sessions of a user. This kills all processes of all sessions of the user and deallocates all runtime resources attached to the user. If the argument is specified as empty string the sessions of the user invoking the command are terminated. `kill-user` \… Send a signal to all processes of a user. Use `--signal=` to select the signal to send. If the argument is specified as empty string the signal is sent to the sessions of the user invoking the command. ## Seat Commands `list-seats` List currently available seats on the local system. The JSON format output can be toggled using `--json=` or `-j` option. `seat-status` \[\…\] Show terse runtime status information about one or more seats. Takes one or more seat names as parameters. If no seat names are passed the status of the caller's session's seat is shown. This function is intended to generate human-readable output. If you are looking for computer-parsable output, use `show-seat` instead. `show-seat` \[\…\] Show properties of one or more seats or the manager itself. If no argument is specified, properties of the manager will be shown. If a seat is specified, properties of the seat are shown. By default, empty properties are suppressed. Use `--all` to show those too. To select specific properties to show, use `--property=`. This command is intended to be used whenever computer-parsable output is required. Use `seat-status` if you are looking for formatted human-readable output. `attach` \ \… Persistently attach one or more devices to a seat. The devices should be specified via device paths in the `/sys/` file system. To create a new seat, attach at least one graphics card to a previously unused seat name. Seat names may consist only of a–z, A–Z, 0–9, `-` and `_` and must be prefixed with `seat`. To drop assignment of a device to a specific seat, just reassign it to a different seat, or use `flush-devices`. `flush-devices` Removes all device assignments previously created with `attach`. After this call, only automatically generated seats will remain, and all seat hardware is assigned to them. `terminate-seat` \… Terminates all sessions on a seat. This kills all processes of all sessions on the seat and deallocates all runtime resources attached to them. # Options The following options are understood: `-p`; `--property=` When showing session/user/seat properties, limit display to certain properties as specified as argument. If not specified, all set properties are shown. The argument should be a property name, such as `Sessions`. If specified more than once, all properties with the specified names are shown. `--value` When showing session/user/seat properties, only print the value, and skip the property name and `=`. `-a`; `--all` When showing session/user/seat properties, show all properties regardless of whether they are set or not. `-l`; `--full` Do not ellipsize process tree entries. `--kill-whom=` When used with `kill-session`, choose which processes to kill. Takes one of `leader` or `all`, to select whether to kill only the leader process of the session or all processes of the session. If omitted, defaults to `all`. `-s`; `--signal=` When used with `kill-session` or `kill-user`, choose which signal to send to selected processes. Must be one of the well known signal specifiers, such as `SIGTERM`, `SIGINT` or `SIGSTOP`. If omitted, defaults to `SIGTERM`. The special value `help` will list the known values and the program will exit immediately, and the special value `list` will list known values along with the numerical signal numbers and the program will exit immediately. `-n`; `--lines=` When used with `user-status` and `session-status`, controls the number of journal lines to show, counting from the most recent ones. Takes a positive integer argument. Defaults to 10. `-o`; `--output=` When used with `user-status` and `session-status`, controls the formatting of the journal entries that are shown. For the available choices, see `journalctl(1)`. Defaults to `short`. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Examples
Querying user status
$ loginctl user-status fatima (1005) Since: Sat 2016-04-09 14:23:31 EDT; 54min ago State: active Sessions: 5 *3 Unit: user-1005.slice ├─user@1005.service … ├─session-3.scope … └─session-5.scope ├─3473 login -- fatima └─3515 -zsh Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session): session opened for user fatima by LOGIN(uid=0) Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima There are two sessions, 3 and 5. Session 3 is a graphical session, marked with a star. The tree of processing including the two corresponding scope units and the user manager unit are shown.
# See Also `systemd(1)`, `systemctl(1)`, `systemd-logind.service(8)`, `logind.conf(5)` # machine-id systemd machine-id 5 machine-id Local machine ID configuration file `/etc/machine-id` # Description The `/etc/machine-id` file contains the unique machine ID of the local system that is set during installation or boot. The machine ID is a single newline-terminated, hexadecimal, 32-character, lowercase ID. When decoded from hexadecimal, this corresponds to a 16-byte/128-bit value. This ID may not be all zeros. The machine ID is usually generated from a random source during system installation or first boot and stays constant for all subsequent boots. Optionally, for stateless systems, it is generated during runtime during early boot if necessary. The machine ID may be set, for example when network booting, with the `systemd.machine_id=` kernel command line parameter or by passing the option `--machine-id=` to systemd. An ID specified in this manner has higher priority and will be used instead of the ID stored in `/etc/machine-id`. The machine ID does not change based on local or network configuration or when hardware is replaced. Due to this and its greater length, it is a more useful replacement for the `gethostid(3)` call that POSIX specifies. This machine ID adheres to the same format and logic as the D-Bus machine ID. This ID uniquely identifies the host. It should be considered "confidential", and must not be exposed in untrusted environments, in particular on the network. If a stable unique identifier that is tied to the machine is needed for some application, the machine ID or any part of it must not be used directly. Instead the machine ID should be hashed with a cryptographic, keyed hash function, using a fixed, application-specific key. That way the ID will be properly unique, and derived in a constant way from the machine ID but there will be no way to retrieve the original machine ID from the application-specific one. The `sd_id128_get_machine_app_specific(3)` API provides an implementation of such an algorithm. # Initialization Each machine should have a non-empty ID in normal operation. The ID of each machine should be unique. To achieve those objectives, `/etc/machine-id` can be initialized in a few different ways. For normal operating system installations, where a custom image is created for a specific machine, `/etc/machine-id` should be populated during installation. `systemd-machine-id-setup(1)` may be used by installer tools to initialize the machine ID at install time, but `/etc/machine-id` may also be written using any other means. For operating system images which are created once and used on multiple machines, for example for containers or in the cloud, `/etc/machine-id` should be either missing or an empty file in the generic file system image (the difference between the two options is described under "First Boot Semantics" below). An ID will be generated during boot and saved to this file if possible. Having an empty file in place is recommended because it allows a temporary file to be bind-mounted over the real file, in case the image is used read-only and when `/etc` is mounted read-only in the early boot. Also see [Safely Building Images](https://systemd.io/BUILDING_IMAGES). `systemd-firstboot(1)` may be used to initialize `/etc/machine-id` on mounted (but not booted) system images. When a machine is booted with `systemd(1)` the ID of the machine will be established. If `systemd.machine_id=` or `--machine-id=` options (see first section) are specified, this value will be used. Otherwise, the value in `/etc/machine-id` will be used. If this file is empty or missing, `systemd` will attempt to use the D-Bus machine ID from `/var/lib/dbus/machine-id`, the value of the kernel command line option `container_uuid`, the KVM DMI `product_uuid` or the devicetree `vm,uuid` (on KVM systems), the Xen hypervisor `uuid`, and finally a randomly generated UUID. `systemd.machine_id=firmware` can be set to generate the machine ID from the firmware. After the machine ID is established, `systemd(1)` will attempt to save it to `/etc/machine-id`. If this fails, it will attempt to bind-mount a temporary file over `/etc/machine-id`. It is an error if the file system is read-only and does not contain a (possibly empty) `/etc/machine-id` file. `systemd-machine-id-commit.service(8)` will attempt to write the machine ID to the file system if `/etc/machine-id` or `/etc/` are read-only during early boot but become writable later on. # First Boot Semantics `/etc/machine-id` is used to decide whether a boot is the first one. The rules are as follows: 1. The kernel command argument `systemd.condition_first_boot=` may be used to override the autodetection logic, see `kernel-command-line(7)`. 2. Otherwise, if `/etc/machine-id` does not exist, this is a first boot. During early boot, `systemd` will write `uninitialized\n` to this file and overmount a temporary file which contains the actual machine ID. Later (after `first-boot-complete.target` has been reached), the real machine ID will be written to disk. 3. If `/etc/machine-id` contains the string `uninitialized`, a boot is also considered the first boot. The same mechanism as above applies. 4. If `/etc/machine-id` exists and is empty, a boot is *not* considered the first boot. `systemd` will still bind-mount a file containing the actual machine-id over it and later try to commit it to disk (if `/etc/` is writable). 5. If `/etc/machine-id` already contains a valid machine-id, this is not a first boot. If according to the above rules a first boot is detected, units with `ConditionFirstBoot=yes` will be run and `systemd` will perform additional initialization steps, in particular presetting units. # Relation to OSF UUIDs Note that the machine ID historically is not an OSF UUID as defined by [RFC 4122](https://tools.ietf.org/html/rfc4122), nor a Microsoft GUID; however, starting with systemd v30, newly generated machine IDs do qualify as Variant 1 Version 4 UUIDs, as per RFC 4122. In order to maintain compatibility with existing installations, an application requiring a strictly RFC 4122 compliant UUID should decode the machine ID, and then (non-reversibly) apply the following operations to turn it into a valid RFC 4122 Variant 1 Version 4 UUID. With `id` being an unsigned character array: /* Set UUID version to 4 --- truly random generation */ id[6] = (id[6] & 0x0F) | 0x40; /* Set the UUID variant to DCE */ id[8] = (id[8] & 0x3F) | 0x80; (This code is inspired by `generate_random_uuid()` of `drivers/char/random.c` from the Linux kernel sources.) # History The simple configuration file format of `/etc/machine-id` originates in the `/var/lib/dbus/machine-id` file introduced by D-Bus. In fact, this latter file might be a symlink to `/etc/machine-id`. # See Also `systemd(1)`, `systemd-machine-id-setup(1)`, `gethostid(3)`, `hostname(5)`, `machine-info(5)`, `os-release(5)`, `sd-id128(3)`, `sd_id128_get_machine(3)`, `systemd-firstboot(1)` # machine-info systemd machine-info 5 machine-info Local machine information file `/etc/machine-info` # Description The `/etc/machine-info` file contains machine metadata. The format of `machine-info` is a newline-separated list of environment-like shell-compatible variable assignments, ignoring comments and empty lines. It is possible to source the configuration from shell scripts, however, beyond mere variable assignments no shell features are supported, allowing applications to read the file without implementing a shell compatible execution engine. See `os-release(5)` for a detailed description of the format. `/etc/machine-info` contains metadata about the machine that is set by the user or administrator. The settings configured here have the highest precedence. When not set, appropriate values may be determined automatically, based on the information about the hardware or other configuration files. It is thus completely fine for this file to not be present. You may use `hostnamectl(1)` to change the settings of this file from the command line. # Options The following machine metadata parameters may be set using `/etc/machine-info`: ## Machine Information `PRETTY_HOSTNAME=` A pretty human-readable UTF-8 machine identifier string. This should contain a name like `Lennart's Laptop` which is useful to present to the user and does not suffer by the syntax limitations of internet domain names. If possible, the internet hostname as configured in `/etc/hostname` should be kept similar to this one. Example: if this value is `Lennart's Computer` an Internet hostname of `lennarts-computer` might be a good choice. If this parameter is not set, an application should fall back to the Internet hostname for presentation purposes. `ICON_NAME=` An icon identifying this machine according to the [XDG Icon Naming Specification](https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html). If this parameter is not set, an application should fall back to `computer` or a similar icon name. `CHASSIS=` The chassis type. Currently, the following chassis types are defined: `desktop`, `laptop`, `convertible`, `server`, `tablet`, `handset`, `watch`, and `embedded`, as well as the special chassis types `vm` and `container` for virtualized systems that lack an immediate physical chassis. Note that most systems allow detection of the chassis type automatically (based on firmware information or suchlike). This setting should only be used to override a misdetection or to manually configure the chassis type where automatic detection is not available. `DEPLOYMENT=` Describes the system deployment environment. One of the following is suggested: `development`, `integration`, `staging`, `testing`, `production`. `LOCATION=` Describes the system location if applicable and known. Takes a human-friendly, free-form string. This may be as generic as `Berlin, Germany` or as specific as `Left Rack, 2nd Shelf`. `TAGS=` A colon-separated list of tags attached to this machine. Tags are labels used to classify and group machines for management purposes, for example to identify the role a machine plays in a deployment (`company.role=webserver`, `company.role=database`), the fleet or organizational unit it belongs to, or any other administrator-defined attribute. Example: `TAGS=company.role=webserver:company.division=frontend:company.location=berlin`. Each individual tag must be 1…255 characters long and may consist only of the ASCII alphanumeric characters, `-`, `.` and `=`. The first character may not be `-`, `.` or `=`, and the last character may not be `-` or `.` (unless it takes the parameterized form, see below). A tag may optionally be parameterized with a value, in the form `key=value`. The first `=` separates the key from the value; any further `=` characters are part of the value. The key (the part before the first `=`) follows the same restrictions as an unparameterized tag, in particular it may not be empty and may not end in `-` or `.`. The value (the part after the first `=`) may be empty and is otherwise unrestricted within the allowed character set. Example: `TAGS=company.role=webserver:company.env=production:company.location=berlin`. In interfaces that assign tags, the same key may not be assigned more than one value: `company.role=webserver:company.role=database` is refused (but a key may coexist with the corresponding unparameterized tag, e.g. `company.role:company.role=webserver`). When tags are read from the config file, invalid tags are ignored, and if the same key is nonetheless assigned more than once, the assignment specified last takes effect. It is recommended for tags to be namespaced. In particular, tags given by an organization or company should be prefixed with some identifier for the organization before the first dot. Personal or purely local tags do not need to be namespaced. The configured tags may be matched against with the `ConditionMachineTag=` and `AssertMachineTag=` unit settings, see `systemd.unit(5)` for details. They may be queried and changed with the `tags` command of `hostnamectl(1)`. Tags may also be declared in `machine-tags.d/` drop-in directories, see `machine-tags.d(5)`, and applied with `hostnamectl tags --apply`. `HARDWARE_VENDOR=` Specifies the hardware vendor. If unspecified, the hardware vendor set in DMI or `hwdb(7)` will be used. `HARDWARE_MODEL=` Specifies the hardware model. If unspecified, the hardware model set in DMI or `hwdb(7)` will be used. `HARDWARE_SKU=` Specifies the hardware SKU (Stock-Keeping Unit). If unspecified, the hardware SKU set in DMI will be used. `HARDWARE_VERSION=` Specifies the hardware version. If unspecified, the hardware version set in DMI will be used. ## Custom Fields Operating system vendors and systemd administrators may extend the file format and introduce new fields. It is highly recommended to prefix new fields with an OS-specific name in order to avoid name clashes. Applications reading this file must ignore unknown fields. Example: `_LOCAL_EMERGENCY_CONTACT="user@example.org"`. # Example PRETTY_HOSTNAME="Lennart's Tablet" ICON_NAME=computer-tablet CHASSIS=tablet DEPLOYMENT=production TAGS=room=kitchen:company.location=berlin:company.role=personal # See Also `systemd(1)`, `os-release(5)`, `hostname(5)`, `machine-id(5)`, `hostnamectl(1)`, `machine-tags.d(5)`, `systemd-hostnamed.service(8)` # machine-tags.d systemd machine-tags.d 5 machine-tags.d Configure machine tags `/etc/machine-tags.d/*.tags`, `/run/machine-tags.d/*.tags`, `/usr/local/lib/machine-tags.d/*.tags`, `/usr/lib/machine-tags.d/*.tags` # Description The files in the above directories declare machine tags to be added or removed from the list of tags in the `TAGS=` field of `machine-info(5)`. See that page for the details of how tags are defined and used. Those files are read and applied by `systemd-hostnamed.service(8)` when requested via `hostnamectl tags --apply`, see `hostnamectl(1)`, or directly via the `io.systemd.Hostname.ApplyTags()` call. The resulting tag list is stored in `/etc/machine-info`, thus applying the same configuration repeatedly has no further effect. Note: when `machine-tags.d/` files are used, direct management of tags through `hostnamectl tags …` or by editing the `/etc/machine-info` file directly are *not recommended*. Please use one approach or the other. During boot, the configuration is applied automatically by `systemd-machine-tags.service(8)`. This allows OS vendors, image builders and system extensions (see `systemd-sysext(8)`) to declare tags in a drop-in directory hierarchy, instead of setting them imperatively. # Configuration Format Each file contains a list of entries separated by whitespace (spaces, tabs, or newlines). Empty lines and comments (lines starting with `#` or `;`) are ignored. An entry without prefix (or, equivalently, prefixed with `+`) adds a tag. An entry prefixed with `-` removes matching tags. The pattern may be a literal tag value, or a shell-style glob, see `glob(7)`. For example, `-vendor.install.*` removes all tags starting with `vendor.install.`, `-company.role=*` removes any value assigned to the `company.role` key, and `-*` removes all tags. Removing a tag that is not set has no effect. Entries are applied in the order they appear, across all files in the order described below. A tag may hence be removed by a glob and added back by a later entry. When a parameterized tag `key=value` is added and a different value is already assigned to the same key, the previous assignment is replaced. Each tag must be a valid machine tag, see `machine-info(5)` for the syntax. Invalid entries are ignored with a warning, and the remaining entries are still applied. # Configuration Directories and Precedence Configuration files are read from directories in `/etc/`, `/run/`, `/usr/local/lib/`, and `/usr/lib/`, in order of precedence, as listed in the SYNOPSIS section above. Files must have the `.tags` extension. Files in `/etc/` override files with the same name in `/run/`, `/usr/local/lib/`, and `/usr/lib/`. Files in `/run/` override files with the same name under `/usr/`. All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in, following the usual semantics of systemd configuration files. Empty files and symlinks to `/dev/null` mask files in directories with lower priority. Note that masking or removing a file only affects future applications of the configuration. Tags that were applied earlier remain configured until they are removed explicitly, for example with a `-` entry in another file, or with `hostnamectl tags`. # Examples
/usr/lib/machine-tags.d/20-vendor.tags example:
# Tags declared by the OS vendor vendor.role=webserver vendor.env=production vendor.region=eu
/etc/machine-tags.d/70-local.tags example:
# Drop the vendor's environment and region tags, but keep the role, and add a local tag -vendor.env=* -vendor.region=* local.rack=7
After `hostnamectl tags --apply`, the configured tags include `local.rack=7` and `vendor.role=webserver`, in addition to any tags that were configured before. # See Also `systemd(1)`, `hostnamectl(1)`, `machine-info(5)`, `systemd-hostnamed.service(8)`, `systemd-machine-tags.service(8)`, `systemd.unit(5)` # machinectl systemd machinectl 1 machinectl Control the systemd machine manager machinectl OPTIONS COMMAND NAME # Description `machinectl` may be used to introspect and control the state of the `systemd(1)` virtual machine and container registration manager `systemd-machined.service(8)`. `machinectl` may be used to execute operations on machines and images. Machines in this sense are considered running instances of: - Virtual Machines (VMs) that virtualize hardware to run full operating system (OS) instances (including their kernels) in a virtualized environment on top of the host OS. - Containers that share the hardware and OS kernel with the host OS, in order to run OS userspace instances on top the host OS. - The host system itself. Machines are identified by names that follow the same rules as UNIX and DNS hostnames. For details, see below. Machines are instantiated from disk or file system images that frequently — but not necessarily — carry the same name as machines running from them. Images in this sense may be: - Directory trees containing an OS, including the top-level directories `/usr/`, `/etc/`, and so on. - btrfs subvolumes containing OS trees, similar to regular directory trees. - Binary "raw" disk image files containing MBR or GPT partition tables and Linux file systems. - Similarly, block devices containing MBR or GPT partition tables and file systems. - The file system tree of the host OS itself. Images may be downloaded, imported and exported via the `importctl(1)` tool. # Commands The following commands are understood: ## Machine Commands `list` List currently running (online) virtual machines and containers. To enumerate machine images that can be started, use `list-images` (see below). Note that this command hides the special `.host` machine by default. Use the `--all` switch to show it. `status` \… Show runtime status information about one or more virtual machines and containers, followed by the most recent log data from the journal. This function is intended to generate human-readable output. If you are looking for computer-parsable output, use `show` instead. Note that the log data shown is reported by the virtual machine or container manager, and frequently contains console output of the machine, but not necessarily journal contents of the machine itself. `show` \[\…\] Show properties of one or more registered virtual machines or containers or the manager itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified, properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use `--all` to show those too. To select specific properties to show, use `--property=`. This command is intended to be used whenever computer-parsable output is required, and does not print the control group tree or journal entries. Use `status` if you are looking for formatted human-readable output. `start` \… Start a container as a system service, using `systemd-nspawn(1)`. This starts `systemd-nspawn@.service`, instantiated for the specified machine name, similar to the effect of `systemctl start` on the service name. `systemd-nspawn` looks for a container image by the specified name in `/var/lib/machines/` (and other search paths, see below) and runs it. Use `list-images` (see below) for listing available container images to start. Note that `systemd-machined.service(8)` also interfaces with a variety of other container and VM managers, `systemd-nspawn` is just one implementation of it. Most of the commands available in `machinectl` may be used on containers or VMs controlled by other managers, not just `systemd-nspawn`. Starting VMs and container images on those managers requires manager-specific tools. To interactively start a container on the command line with full access to the container's console, please invoke `systemd-nspawn` directly. To stop a running container use `machinectl poweroff`. `login` \[\\] Open an interactive terminal login session in a container or on the local host. If an argument is supplied, it refers to the container machine to connect to. If none is specified, or the container name is specified as the empty string, or the special machine name `.host` (see below) is specified, the connection is made to the local host instead. This will create a TTY connection to a specific container or the local host and asks for the execution of a getty on it. Note that this is only supported for containers running `systemd(1)` as init system. This command will open a full login prompt on the container or the local host, which then asks for username and password. Use `shell` (see below) or `systemd-run(1)` with the `--machine=` switch to directly invoke a single command, either interactively or in the background. `shell` \[\[\@\]\ \[\ \[\…\]\]\] Open an interactive shell session in a container or on the local host. The first argument refers to the container machine to connect to. If none is specified, or the machine name is specified as the empty string, or the special machine name `.host` (see below) is specified, the connection is made to the local host instead. This works similarly to `login`, but immediately invokes a user process. This command runs the specified executable with the specified arguments, or the default shell for the user if none is specified, or `/bin/sh` if no default shell is found. By default, `--uid=`, or by prefixing the machine name with a username and an `@` character, a different user may be selected. Use `--setenv=` to set environment variables for the executed process. Note that `machinectl shell` does not propagate the exit code/status of the invoked shell process. Use `systemd-run` instead if that information is required (see below). Using the `shell` command without arguments (thus invoking the executed shell or command on the local host), is in many ways similar to a `su(1)` session, but, unlike `su`, completely isolates the new session from the originating session, so that it shares no process or session properties and is in a clean well-defined state. It will be tracked in a new utmp, login, audit, security, and keyring sessions, and will not inherit any environment variables or resource limits, among other properties. Note that `systemd-run(1)` with its `--machine=` switch may be used in place of the `machinectl shell` command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit, as well as access to runtime and exit code/status information of the invoked shell process. In particular, use `systemd-run`'s `--wait` switch to propagate exit status information of the invoked process. Use `systemd-run`'s `--pty` switch to acquire an interactive shell, similarly to `machinectl shell`. In general, `systemd-run` is preferable for scripting purposes. However, note that `systemd-run` might require higher privileges than `machinectl shell`. `enable` \…; `disable` \… Enable or disable a container as a system service to start at system boot, using `systemd-nspawn(1)`. This enables or disables `systemd-nspawn@.service`, instantiated for the specified machine name, similarly to the effect of `systemctl enable` or `systemctl disable` on the service name. This command implicitly reloads the system manager configuration after completing the operation. Note that this command does not implicitly start or power off the containers that are being operated on. If this is desired, combine the command with the `--now` switch. `poweroff` \… Power off one or more machines. For VMs managed by `systemd-vmspawn(1)`, this sends an ACPI powerdown request via QMP. For containers, this sends SIGRTMIN+4 to the container's init process, which causes systemd-compatible init systems to shut down cleanly. This operation does not work on containers that do not run a `systemd(1)`-compatible init system, such as sysvinit. Use `stop` as alias for `poweroff`. Use `terminate` (see below) to immediately terminate a machine without cleanly shutting it down. `reboot` \… Reboot one or more machines. For VMs managed by `systemd-vmspawn(1)`, this sends a system reset request via QMP. For containers, this sends SIGINT to the container's init process, which is roughly equivalent to pressing Ctrl+Alt+Del on a non-containerized system, and is compatible with containers running any system manager. Use `restart` as alias for `reboot`. `pause` \… Pause one or more machines. For VMs managed by `systemd-vmspawn(1)`, this freezes vCPU execution at the hypervisor level — the guest operating system is not notified and does not observe an ACPI suspend. From the guest's perspective time simply stops until the machine is resumed with `resume`. `resume` \… Resume one or more previously paused machines. This restarts execution after a `pause`. `terminate` \… Immediately terminates a virtual machine or container, without cleanly shutting it down. This kills all processes of the virtual machine or container and deallocates all resources attached to that instance. Use `poweroff` to issue a clean shutdown request. `kill` \… Send a signal to one or more processes of the virtual machine or container. This means processes as seen by the host, not the processes inside the virtual machine or container. Use `--kill-whom=` to select which process to kill. Use `--signal=` to select the signal to send. `bind` \ \ \[\\] Bind mounts a file or directory from the host into the specified container. The first path argument is the source file or directory on the host, the second path argument is the destination file or directory in the container. When the latter is omitted, the destination path in the container is the same as the source path on the host. When combined with the `--read-only` switch, a read-only bind mount is created. When combined with the `--mkdir` switch, the destination path is first created before the mount is applied. Note that this option is currently only supported for `systemd-nspawn(1)` containers, and only if user namespacing (`--private-users`) is not used. This command supports bind mounting directories, regular files, device nodes, `AF_UNIX` socket nodes, as well as FIFOs. `bind-volume` \ \ Acquire a storage volume from a `storagectl(1)` provider and attach it to the running machine. \ is a string of the form `PROVIDER:VOLUME[:CONFIG][:K=V,…]`, identical in grammar to the `--bind-volume=` argument of `systemd-vmspawn(1)`. The attached volume is identified by the name `PROVIDER:VOLUME` and may be detached at runtime via `unbind-volume`. Currently only supported for `systemd-vmspawn` machines that expose an `io.systemd.MachineInstance` control socket. `unbind-volume` \ \ Detach a storage volume from the running machine. \ is the `PROVIDER:VOLUME` identifier that was specified at `bind-volume` time. Volumes that were attached at machine startup (e.g. via `--bind-volume=` on `systemd-vmspawn(1)`) cannot be detached and will fail with `io.systemd.MachineInstance.StorageImmutable`. `copy-to` \ \ \[\\] `--force` Copies files or directories from the host system into a running container. Takes a container name, followed by the source path on the host and the destination path in the container. If the destination path is omitted, the same as the source path is used. If host and container share the same user and group namespace, file ownership by numeric user ID and group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root user and group (UID/GID 0). `copy-from` \ \ \[\\] `--force` Copies files or directories from a container into the host system. Takes a container name, followed by the source path in the container and the destination path on the host. If the destination path is omitted, the same as the source path is used. If host and container share the same user and group namespace, file ownership by numeric user ID and group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root user and group (UID/GID 0). ## Image Commands `list-images` Show a list of locally installed container and VM images. This enumerates all raw disk images and container directories and subvolumes in `/var/lib/machines/` (and other search paths, see below). Use `start` (see above) to run a container off one of the listed images. Note that, by default, containers whose name begins with a dot (`.`) are not shown. To show these too, specify `--all`. Note that a special image `.host` always implicitly exists and refers to the image the host itself is booted from. `image-status` \[\…\] Show terse status information about one or more container or VM images. This function is intended to generate human-readable output. Use `show-image` (see below) to generate computer-parsable output instead. `show-image` \[\…\] Show properties of one or more registered virtual machine or container images, or the manager itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified, properties of this virtual machine or container image are shown. By default, empty properties are suppressed. Use `--all` to show those too. To select specific properties to show, use `--property=`. This command is intended to be used whenever computer-parsable output is required. Use `image-status` if you are looking for formatted human-readable output. `edit` \ Edit the settings file of the specified machines. For the format of the settings file, refer to `systemd.nspawn(5)`. If an existing settings file of the given machine cannot be found, `edit` automatically create a new settings file from scratch under `/etc/systemd/nspawn/`. `cat` \ Show the settings file of the specified machines. `clone` \ \ Clones a container or VM image. The arguments specify the name of the image to clone and the name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume images with this command, if the underlying file system supports this. Note that cloning a container or VM image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to file system limitations. Note that this command leaves hostname, machine ID and all other settings that could identify the instance unmodified. The original image and the cloned copy will hence share these credentials, and it might be necessary to manually change them in the copy. If combined with the `--read-only` switch a read-only cloned image is created. `rename` \ \ Renames a container or VM image. The arguments specify the name of the image to rename and the new name of the image. `read-only` \ \[\\] Marks or (unmarks) a container or VM image read-only. Takes a VM or container image name, followed by a boolean as arguments. If the boolean is omitted, positive is implied, i.e. the image is marked read-only. `remove` \… Removes one or more container or VM images. The special image `.host`, which refers to the host's own directory tree, may not be removed. `set-limit` \[\\] \ Sets the maximum size in bytes that a specific container or VM image, or all images, may grow up to on disk (disk quota). Takes either one or two parameters. The first, optional parameter refers to a container or VM image name. If specified, the size limit of the specified image is changed. If omitted, the overall size limit of the sum of all images stored locally is changed. The final argument specifies the size limit in bytes, possibly suffixed by the usual K, M, G, T units. If the size limit shall be disabled, specify `-` as size. Note that per-container size limits are only supported on btrfs file systems. `clean` Remove hidden VM or container images (or all). This command removes all hidden machine images from `/var/lib/machines/`, i.e. those whose name begins with a dot. Use `machinectl list-images --all` to see a list of all machine images, including the hidden ones. When combined with the `--all` switch removes all images, not just hidden ones. This command effectively empties `/var/lib/machines/`. Note that commands such as `importctl pull-tar` or `importctl pull-raw` usually create hidden, read-only, unmodified machine images from the downloaded image first, before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are reused multiple times. Use `machinectl clean` to remove old, hidden images created this way. # Options The following options are understood: `-p`; `--property=` When showing machine or image properties, limit the output to certain properties as specified by the argument. If not specified, all set properties are shown. The argument should be a property name, such as `Name`. If specified more than once, all properties with the specified names are shown. `--value` When printing properties with `show`, only print the value, and skip the property name and `=`. `-a`; `--all` When showing machine or image properties, show all properties regardless of whether they are set or not. When listing VM or container images, do not suppress images beginning in a dot character (`.`). When cleaning VM or container images, remove all images, not just hidden ones. `-l`; `--full` Do not ellipsize process tree entries or table. This implies `--max-addresses=full`. `--kill-whom=` When used with `kill`, choose which processes to kill. Must be one of `leader`, `supervisor`, or `all` to select whether to kill only the leader process of the machine, the supervisor process of the machine, or all processes of the machine. If omitted, defaults to `all`. `--uid=` When used with the `shell` command, chooses the user ID to open the interactive shell session as. If the argument to the `shell` command also specifies a user name, this option is ignored. If the name is not specified in either way, `root` will be used by default. Note that this switch is not supported for the `login` command (see below). `-E NAME[=VALUE]`; `--setenv=NAME[=VALUE]` When used with the `shell` command, sets an environment variable for the executed shell. This option may be used more than once to set multiple variables. When `=` and \ are omitted, the value of the variable with the same name in the program environment will be used. Note that this option is not supported for the `login` command. `--mkdir` When used with `bind`, creates the destination file or directory before applying the bind mount. Note that even though the name of this option suggests that it is suitable only for directories, this option also creates the destination file node to mount over if the object to mount is not a directory, but a regular file, device node, socket or FIFO. `--read-only` When used with `bind`, creates a read-only bind mount. When used with `clone` a read-only container or VM image is created. `-n`; `--lines=` When used with `status`, controls the number of journal lines to show, counting from the most recent ones. Takes a positive integer argument. Defaults to 10. `-o`; `--output=` When used with `status`, controls the formatting of the journal entries that are shown. For the available choices, see `journalctl(1)`. Defaults to `short`. `--runner=``nspawn`\|`vmspawn` When operating on machines choose whether to use `systemd-nspawn(1)` or `systemd-vmspawn(1)`. By default `systemd-nspawn(1)` is used. `-V` `-V` is a shorthand for `--runner=vmspawn`. `--now` When used with `enable` or `disable`, the containers will also be started or powered off. The start or poweroff operation is only carried out when the respective enable or disable operation has been successful. `--force` Replace target file when copying files. `--max-addresses=` When used with the `list-machines` command, limits the number of IP addresses shown for every machine. Defaults to 1. All addresses can be requested with `all`. If the limit is 0, the address column is not shown. Otherwise, if the machine has more addresses than shown, `…` follows the last address. `-q`; `--quiet` Suppresses additional informational output while running. `-M`; `--machine=` Connect to `systemd-machined.service(8)` running in a local container, to perform the specified operation within the container. # Machine and Image Names The `machinectl` tool operates on machines and images whose names must be chosen following strict rules. Machine names must be suitable for use as hostnames following a conservative subset of DNS and UNIX/Linux semantics. Specifically, they must consist of one or more non-empty label strings, separated by dots. No leading or trailing dots are allowed. No sequences of multiple dots are allowed. The label strings may only consist of alphanumeric characters as well as the dash. The maximum length of a machine name is 64 characters. A special machine with the name `.host` refers to the running host system itself. This is useful for execution operations or inspecting the host system as well. Note that `machinectl list` will not show this special machine unless the `--all` switch is specified. Requirements on image names are less strict, however, they must be valid UTF-8, must be suitable as file names (hence not be the single or double dot, and not include a slash), and may not contain control characters. Since many operations search for an image by the name of a requested machine, it is recommended to name images in the same strict fashion as machines. A special image with the name `.host` refers to the image of the running host system. It hence conceptually maps to the special `.host` machine name described above. Note that `machinectl list-images` will not show this special image either, unless `--all` is specified. # Files and Directories Machine images are preferably stored in `/var/lib/machines/`, but are also searched for in `/usr/local/lib/machines/` and `/usr/lib/machines/`. For compatibility reasons, the directory `/var/lib/container/` is searched, too. Note that images stored below `/usr/` are always considered read-only. It is possible to symlink machines images from other directories into `/var/lib/machines/` to make them available for control with `machinectl`. Note that some image operations are only supported, efficient or atomic on btrfs file systems. Disk images are understood by `systemd-nspawn(1)` and `machinectl` in three formats: - A simple directory tree, containing the files and directories of the container to boot. - Subvolumes (on btrfs file systems), which are similar to the simple directories, described above. However, they have additional benefits, such as efficient cloning and quota reporting. - "Raw" disk images, i.e. binary images of disks with a GPT or MBR partition table. Images of this type are regular files with the suffix `.raw`. See `systemd-nspawn(1)` for more information on image formats, in particular its `--directory=` and `--image=` options. # Examples # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-machined.service(8)`, `systemd-nspawn(1)`, `systemd.special(7)`, `importctl(1)`, `tar(1)`, `xz(1)`, `gzip(1)`, `bzip2(1)`, `zstd(1)` # modules-load.d systemd modules-load.d 5 modules-load.d Configure kernel modules to load at boot `/etc/modules-load.d/*.conf`, `/run/modules-load.d/*.conf`, `/usr/local/lib/modules-load.d/*.conf`, `/usr/lib/modules-load.d/*.conf` # Description `systemd-modules-load.service(8)` reads files from the above directories which contain kernel modules to load during boot in a static list. Each configuration file is named in the style of `/etc/modules-load.d/program.conf`. Note that it is usually a better idea to rely on the automatic module loading by PCI IDs, USB IDs, DMI IDs or similar triggers encoded in the kernel modules themselves instead of static configuration like this. In fact, most modern kernel modules are prepared for automatic loading already. # Configuration Format The configuration files should simply contain a list of kernel module names to load, separated by newlines. Empty lines and lines whose first non-whitespace character is \# or ; are ignored. # Example
/etc/modules-load.d/virtio-net.conf example:
# Load virtio-net.ko at boot virtio-net
# See Also `systemd(1)`, `systemd-modules-load.service(8)`, `systemd-delta(1)`, `modprobe(8)` # networkctl systemd networkctl 1 networkctl Query or modify the status of network links networkctl OPTIONS COMMAND LINK # Description `networkctl` may be used to query or modify the state of the network links as seen by `systemd-networkd`. Please refer to `systemd-networkd.service(8)` for an introduction to the basic concepts, functionality, and configuration syntax. # Commands The following commands are understood: `list` \[\\] Show a list of existing links and their status. If one or more \s are specified, only links matching one of them are shown. If no further arguments are specified shows all links, otherwise just the specified links. Produces output similar to: IDX LINK TYPE OPERATIONAL SETUP 1 lo loopback carrier unmanaged 2 eth0 ether routable configured 3 virbr0 ether no-carrier unmanaged 4 virbr0-nic ether off unmanaged 4 links listed. The operational status is one of the following: missing The device is missing. off The device is powered down. no-carrier The device is powered up, but does not yet have a carrier. dormant The device has a carrier, but is not yet ready for normal traffic. degraded-carrier One of the bonding or bridge slave network interfaces is in off, no-carrier, or dormant state, and the master interface has no address. carrier The link has carrier, or for bond or bridge master, all bonding or bridge slave network interfaces are enslaved to the master. degraded The link has carrier and addresses valid on the local link configured. For bond or bridge master this means that not all slave network interfaces have carrier but at least one does. enslaved The link has carrier and is enslaved to bond or bridge master network interface. routable The link has carrier and routable address configured. For bond or bridge master it is not necessary for all slave network interfaces to have carrier, but at least one must. The setup status is one of the following: pending `systemd-udevd(8)` is still processing the link, we do not yet know if we will manage it. initialized `systemd-udevd(8)` has processed the link, but we do not yet know if we will manage it. configuring Configuration for the link is being retrieved or the link is being configured. configured Link has been configured successfully. unmanaged `systemd-networkd` is not handling the link. failed `systemd-networkd` failed to configure the link. linger The link is gone, but has not yet been dropped by `systemd-networkd`. `status` \[\\] Show information about the specified links: type, state, kernel module driver, hardware and IP address, configured DNS servers, etc. If one or more \s are specified, only links matching one of them are shown. When no links are specified, an overall network status is shown. Also see the option `--all`. Produces output similar to: ● State: routable Online state: online Address: 10.193.76.5 on eth0 192.168.122.1 on virbr0 169.254.190.105 on eth0 fe80::5054:aa:bbbb:cccc on eth0 Gateway: 10.193.11.1 (CISCO SYSTEMS, INC.) on eth0 DNS: 8.8.8.8 8.8.4.4 In the overall network status, the online state depends on the individual online state of all required links. Managed links are required for online by default. In this case, the online state is one of the following: unknown All links have unknown online status (i.e. there are no required links). offline All required links are offline. partial Some, but not all, required links are online. online All required links are online. `dhcp-lease` \ \[\\]\>\] … Show the DHCP message of the acquired lease (i.e. the received DHCPACK message). Takes an interface name and optional DHCP option codes. If no option code is specified, both the DHCP message header and all options are shown. If one or more option codes are specified, only the specified options are shown. When called with the `--json=` option, the entire DHCP message is shown in JSON format. In that case, any specified option codes are ignored. By default, each option is displayed in a human-readable format, depending on the option. For example, DNS server addresses are shown as a list of IP addresses (e.g. `192.0.2.1`), and the lease time is shown as a human-readable duration (e.g. `8h`). Each option code may optionally be followed by a formatter, separated by a colon (e.g. `42:address`). This can be useful if the default formatting is not appropriate. The following formatters are supported: `auto` Use the default formatting. `hex` Show the raw bytes in hexadecimal, separated by colons. `flag` Treat the option as having zero-length data and display `yes`. `bool` Treat the option as a 1-byte boolean and display `yes` or `no`. `uint8` Treat the option as a 1-byte unsigned integer. `uint16` Treat the option as a 2-byte unsigned integer. `time` Treat the option as a 4-byte time value in seconds and display it as a human-readable duration. `string` Treat the option as a string. `address` Treat the option as one or more IPv4 addresses and display them in human-readable form. Produces output similar to: $ networkctl dhcp-lease eth0 Header: KEY VALUE Hardware Type: ETHER Hardware Address: 41:42:43:31:32:33 Client Address: 192.0.2.123 Server Address: 192.0.2.1 Options: CODE NAME DATA 1 subnet mask 255.255.255.0 3 router 192.0.2.1 6 domain name server 192.0.2.1 12 hostname test-node 15 domain name lan 28 broadcast address 192.0.2.255 42 NTP server 192.0.2.11 192.0.2.12 51 lease time 1d 53 message type 5 54 server identifier 192.0.2.1 58 renewal time 11h 5min 38s 59 rebinding time 20h 5min 38s 119 domain search hoge.example.com foo.example.com `lldp` \[\\] Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more \s are specified only neighbors on those interfaces are shown. Otherwise, shows discovered neighbors on all interfaces. Note that for this feature to work, `LLDP=` must be turned on for the specific interface, see `systemd.network(5)` for details. Produces output similar to: LINK SYSTEM-NAME SYSTEM-DESCRIPTION CHASSIS-ID PORT-ID PORT-DESCRIPTION CAPS enp0s25 GS1900 - 00:e0:4c:00:00:00 2 Port #2 ..b........ Capability Flags: o - Other; p - Repeater; b - Bridge; w - WLAN Access Point; r - Router; t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN; s - Service VLAN, m - Two-port MAC Relay (TPMR) 1 neighbor(s) listed. `label` Show numerical address labels that can be used for address selection. This is the same information that `ip-addrlabel(8)` shows. See [RFC 3484](https://tools.ietf.org/html/rfc3484) for a discussion of address labels. Produces output similar to: Prefix/Prefixlen Label ::/0 1 fc00::/7 5 fec0::/10 11 2002::/16 2 3ffe::/16 12 2001:10::/28 7 2001::/32 6 ::ffff:0.0.0.0/96 4 ::/96 3 ::1/128 0 `delete` \ Deletes virtual netdevs. Takes interface name or index number. `up` \ Bring devices up. Takes interface name or index number. `down` \ Bring devices down. Takes interface name or index number. `renew` \ Renew dynamic configurations e.g. addresses received from DHCPv4 and DHCPv6 servers. When the DHCPv6 client runs in the information request mode, the information, e.g. DNS servers, is requested again. Takes interface name or index number. `forcerenew` \ Send a FORCERENEW message to all connected clients, triggering DHCP reconfiguration. Takes interface name or index number. `reconfigure` \ Reconfigure network interfaces. Takes interface name or index number. Note that this does not reload `.netdev` or `.network` corresponding to the specified interface. So, if you edit config files, it is necessary to call `networkctl reload` first to apply new settings. `reload` Reload `.netdev` and `.network` files. If a new or modified `.netdev` file is found, then the corresponding netdev is created or updated, respectively. Note, if the corresponding interface already exists, then some of new settings may not be applied. E.g., VLAN ID cannot be changed after the interface was created, so changing \[VLAN\] `Id=` will not take effect if the matching VLAN interface already exists. To apply such settings, the interfaces need to be removed manually before reload. Also note that even if a `.netdev` file is removed, `systemd-networkd(8)` does not remove the existing netdev corresponding to the file. If a new, modified, or removed `.network` file is found, then all interfaces that matched the file are reconfigured. This reconfiguration step can be skipped by passing `--no-reconfigure`, in which case only config files are reloaded from disk without reconfiguring any network interfaces. Use `networkctl reconfigure` afterwards to selectively apply config changes per interface. `edit` \\|\<@DEVICE\>… Edit network configuration files, which include `.network`, `.netdev`, and `.link` files. If no network config file matching the given name is found, a new one will be created under `/etc/` or `/run/`, depending on whether `--runtime` is specified. Specially, if the name is prefixed by `@`, it will be treated as a network interface, and editing will be performed on the network config files associated with it. Additionally, the interface name can be suffixed with `:network` (default), `:link`, or `:netdev`, in order to choose the type of network config to operate on. If `--drop-in=` is specified, edit the drop-in file instead of the main configuration file. Unless `--no-reload` is specified, `systemd-networkd(8)` will be reloaded after the edit of the `.network` or `.netdev` files finishes. The same applies for `.link` files and `systemd-udevd(8)`. Note that the changed link settings are not automatically applied after reloading. To achieve that, trigger uevents for the corresponding interface. Refer to `systemd.link(5)` for more information. If `--stdin` is specified, the new content will be read from standard input. In this mode, the old content of the file is discarded. `cat` \[\\|\<@DEVICE\>…\] Show network configuration files. This command honors the `@` prefix in a similar way as `edit`, with support for an additional suffix `:all` for showing all types of configuration files associated with the interface at once. When no argument is specified, `networkd.conf(5)` and its drop-in files will be shown. `mask` \… Mask network configuration files, which include `.network`, `.netdev`, and `.link` files. A symlink of the given name will be created under `/etc/` or `/run/`, depending on whether `--runtime` is specified, that points to `/dev/null`. If a non-empty config file with the specified name exists under the target directory or a directory with higher priority (e.g. `--runtime` is used while an existing config resides in `/etc/`), the operation is aborted. This command honors `--no-reload` in the same way as `edit`. `unmask` \… Unmask network configuration files, i.e. reverting the effect of `mask`. Note that this command operates regardless of the scope of the directory, i.e. `--runtime` is of no effect. This command honors `--no-reload` in the same way as `edit` and `mask`. `persistent-storage` \ Notify `systemd-networkd.service(8)` that the persistent storage for the service is ready. This is called by `systemd-networkd-persistent-storage.service`. Usually, this command should not be called manually by users or administrators. # Options The following options are understood: `-a` `--all` Show all links with `status`. `-s` `--stats` Show link statistics with `status`. `-l`; `--full` Do not ellipsize the output. `-n`; `--lines=` When used with `status`, controls the number of journal lines to show, counting from the most recent ones. Takes a positive integer argument. Defaults to 10. `--drop-in=NAME` When used with `edit`, edit the drop-in file \ instead of the main configuration file. `--no-reload` When used with `edit`, `mask`, or `unmask`, `systemd-networkd.service(8)` or `systemd-udevd.service(8)` will not be reloaded after the operation finishes. `--no-reconfigure` When used with `reload`, only reload config files from disk without reconfiguring any network interfaces. This may be useful to avoid reconfiguring multiple interfaces simultaneously when multiple `.network` files are updated, or when an updated `.network` file is applied to multiple interfaces. Use `networkctl reconfigure` afterwards to apply changes selectively per interface. `--runtime` When used with `edit` or `mask`, operate on the file under `/run/` instead of `/etc/`. `--stdin` When used with `edit`, the contents of the file will be read from standard input and the editor will not be launched. In this mode, the old contents of the file are automatically replaced. This is useful to "edit" configuration from scripts, especially so that drop-in directories are created and populated in one go. Multiple drop-ins may be "edited" in this mode with `--drop-in=`, and the same contents will be written to all of them. Otherwise, exactly one main configuration file is expected. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd-networkd.service(8)`, `systemd.network(5)`, `systemd.netdev(5)`, `ip(8)` # networkd.conf systemd networkd.conf 5 networkd.conf networkd.conf.d Global Network configuration files `/etc/systemd/networkd.conf`, `/run/systemd/networkd.conf`, `/usr/local/lib/systemd/networkd.conf`, `/usr/lib/systemd/networkd.conf`, `/etc/systemd/networkd.conf.d/*.conf`, `/run/systemd/networkd.conf.d/*.conf`, `/usr/local/lib/systemd/networkd.conf.d/*.conf`, `/usr/lib/systemd/networkd.conf.d/*.conf` # Description These configuration files control global network parameters. # \[Network\] Section Options The following options are available in the \[Network\] section: `SpeedMeter=` Takes a boolean. If set to yes, then `systemd-networkd` measures the traffic of each interface, and `networkctl status INTERFACE` shows the measured speed. Defaults to no. `SpeedMeterIntervalSec=` Specifies the time interval to calculate the traffic speed of each interface. If `SpeedMeter=no`, the value is ignored. Defaults to 10sec. `ManageForeignRoutingPolicyRules=` A boolean. When true, `systemd-networkd` will remove rules that are not configured in .network files (except for rules with protocol `kernel`). When false, it will not remove any foreign rules, keeping them even if they are not configured in a .network file. Defaults to yes. `ManageForeignRoutes=` A boolean. When true, `systemd-networkd` will remove routes that are not configured in .network files (except for routes with protocol `kernel`, `dhcp` when `KeepConfiguration=` is true or `dhcp`, and `static` when `KeepConfiguration=` is true or `static`). When false, it will not remove any foreign routes, keeping them even if they are not configured in a .network file. Defaults to yes. `ManageForeignNextHops=` A boolean. When true, `systemd-networkd` will remove nexthops that are not configured in .network files (except for routes with protocol `kernel`). When false, it will not remove any foreign nexthops, keeping them even if they are not configured in a .network file. Defaults to yes. `RouteTable=` Defines the route table name. Takes a whitespace-separated list of the pairs of route table name and number. The route table name and number in each pair are separated with a colon, i.e., `name:number`. The route table name must not be `default`, `main`, or `local`, as these route table names are predefined with route table number 253, 254, and 255, respectively. The route table number must be an integer in the range 1…4294967295, except for predefined numbers 253, 254, and 255. This setting can be specified multiple times. If an empty string is specified, then the list specified earlier are cleared. Defaults to unset. `IPv4Forwarding=` Configures IPv4 packet forwarding for the system. Takes a boolean value. This controls the `net.ipv4.conf.default.forwarding` and `net.ipv4.conf.all.forwarding` sysctl options. See [IP Sysctl](https://docs.kernel.org/networking/ip-sysctl.html) for more details about the sysctl options. Defaults to unset and the sysctl options will not be changed. If an interface is configured with a .network file that enables `IPMasquerade=` for IPv4 (that is, `ipv4` or `both`), this setting is implied unless explicitly specified. See `IPMasquerade=` in `systemd.network(5)` for more details. `IPv6Forwarding=` Configures IPv6 packet forwarding for the system. Takes a boolean value. This controls the `net.ipv6.conf.default.forwarding` and `net.ipv6.conf.all.forwarding` sysctl options. See [IP Sysctl](https://docs.kernel.org/networking/ip-sysctl.html) for more details about the sysctl options. Defaults to unset and the sysctl options will not be changed. If an interface is configured with a .network file that enables `IPMasquerade=` for IPv6 (that is, `ipv6` or `both`), this setting is implied unless explicitly specified. See `IPMasquerade=` in `systemd.network(5)` for more details. `IPv6PrivacyExtensions=` Specifies the default value for per-network `IPv6PrivacyExtensions=`. Takes a boolean or the special values `prefer-public` and `kernel`. See for details in `systemd.network(5)`. Defaults to `no`. `UseDomains=` Specifies the network- and protocol-independent default value for the same settings in \[IPv6AcceptRA\], \[DHCPv4\], and \[DHCPv6\] sections below. Takes a boolean, or the special value `route`. See the same setting in `systemd.network(5)`. Defaults to `no`. # \[IPv6AcceptRA\] Section Options This section configures the default setting of the Neighbor Discovery. The following options are available in the \[IPv6AcceptRA\] section: `UseDomains=` Specifies the network-independent default value for the same setting in the \[IPv6AcceptRA\] section in `systemd.network(5)`. Takes a boolean, or the special value `route`. When unspecified, the value specified in the \[Network\] section in `networkd.conf(5)`, which defaults to `no`, will be used. # \[IPv6AddressLabel\] Section Options An \[IPv6AddressLabel\] section accepts the following keys. Specify multiple \[IPv6AddressLabel\] sections to configure multiple address labels. IPv6 address labels are used for address selection. See [RFC 3484](https://tools.ietf.org/html/rfc3484). Precedence is managed by userspace, and only the label itself is stored in the kernel. `Label=` The label for the prefix, an unsigned integer in the range 0…4294967294. 0xffffffff is reserved. This setting is mandatory. `Prefix=` IPv6 prefix is an address with a prefix length, separated by a slash `/` character. This setting is mandatory. # \[DHCPv4\] Section Options This section configures the default configurations of DHCPv4 client. If the DHCPv4 client is enabled on an interface, then the configurations below will be used by default unless explicitly specified in the corresponding `.network` file. See also `systemd.network(5)`. The following options are understood: `ClientIdentifier=` Specifies the default DHCPv4 client identifier to be used. Takes one of `mac` or `duid`. If set to `mac`, the MAC address of each link will be used. If set to `duid`, an RFC4361-compliant Client ID, which is the combination of IAID and DUID, is used. IAID can be configured by `IAID=` in each matching `.network` file. DUID can be configured by `DUIDType=` and `DUIDRawData=`. Defaults to `duid`. `DUIDType=` Specifies how the DUID should be generated. See [RFC 3315](https://tools.ietf.org/html/rfc3315#section-9) for a description of all the options. This takes an integer in the range 0…65535, or one of the following string values: `vendor` If `DUIDType=vendor`, then the DUID value will be generated using `43793` as the vendor identifier (systemd) and hashed contents of `machine-id(5)`. This is the default if `DUIDType=` is not specified. `uuid` If `DUIDType=uuid`, and `DUIDRawData=` is not set, then the product UUID is used as a DUID value. If a system does not have valid product UUID, then an application-specific `machine-id(5)` is used as a DUID value. About the application-specific machine ID, see `sd_id128_get_machine_app_specific(3)`. `link-layer-time[:TIME]`; `link-layer` If `link-layer-time` or `link-layer` is specified, then the MAC address of the interface is used as a DUID value. The value `link-layer-time` can take additional time value after a colon, e.g. `link-layer-time:2018-01-23 12:34:56 UTC`. The default time value is `2000-01-01 00:00:00 UTC`. In all cases, `DUIDRawData=` can be used to override the actual DUID value that is used. `DUIDRawData=` Specifies the DHCP DUID value as a single newline-terminated, hexadecimal string, with each byte separated by `:`. The DUID that is sent is composed of the DUID type specified by `DUIDType=` and the value configured here. The DUID value specified here overrides the DUID that `systemd-networkd.service(8)` generates from the machine ID. To configure DUID per-network, see `systemd.network(5)`. The configured DHCP DUID should conform to the specification in [RFC 3315](http://tools.ietf.org/html/rfc3315#section-9), [RFC 6355](http://tools.ietf.org/html/rfc6355). To configure IAID, see `systemd.network(5)`.
A `DUIDType=vendor` with a custom value
DUIDType=vendor DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00 This specifies a 14 byte DUID, with the type DUID-EN (`00:02`), enterprise number 43793 (`00:00:ab:11`), and identifier value `f9:2a:c2:77:29:f9:5c:00`.
`UseDomains=` Same as the one in the \[IPv6AcceptRA\] section, but applied for DHCPv4 protocol. # \[DHCPv6\] Section Options This section configures the default configurations of DHCPv6 client. If the DHCPv6 client is enabled on an interface, then the configurations below will be used by default unless explicitly specified in the corresponding `.network` file. See also `systemd.network(5)`. The following options are understood: `DUIDType=`; `DUIDRawData=` As in the \[DHCPv4\] section. `UseDomains=` As in the \[DHCPv4\] section. # \[DHCPRelay\] Section Options The \[DHCPRelay\] section contains host-wide settings for the DHCP relay agent. `ServerAddress=` Specifies the IPv4 address of the upstream DHCP server. This is required for the host to act as a DHCP relay agent. `OverrideServerIdentifier=` Takes a boolean value. When enabled, the Server Identifier Override sub-option and the Relay Agent Flags sub-option in the Relay Agent Information option will be appended to the DHCP message forwarded to the upstream DHCP server. Defaults to false. `RemoteId=` Specifies the remote ID, which is typically used by DHCP servers to identify the DHCP relay agent. Takes a data type and data separated with a colon (`type:value`). The type takes one of `uint8`, `uint16`, `uint32`, `ipv4address`, `ipv6address`, or `string`. Special characters in the data string may be escaped using [C-style escapes](https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences). If unset, a UUID generated from the local machine ID will be used. `ExtraOption=` Specifies an extra sub-option in the Relay Agent Information option, which is appended to DHCP messages forwarded to the upstream DHCP server. Takes a sub-option code, data type, and data separated with a colon (`code:type:value`). The code is an integer in 1…254. See `RemoteId=` in the above for the acceptable type and data. This setting can be specified multiple times. When an empty string is specified, all previous assignments are cleared. Defaults to unset, and no extra sub-option will be appended. # \[DHCPServer\] Section Options This section configures the default setting of the DHCP server. The following options are available in the \[DHCPServer\] section: `PersistLeases=` Specifies the default value for per-network `PersistLeases=`. Takes a boolean or special value `runtime`. See for details in `systemd.network(5)`. Defaults to `yes`. # See Also `systemd(1)`, `systemd.network(5)`, `systemd-networkd.service(8)`, `machine-id(5)`, `sd_id128_get_machine_app_specific(3)` # nss-myhostname systemd nss-myhostname 8 nss-myhostname libnss_myhostname.so.2 Hostname resolution for the locally configured system hostname `libnss_myhostname.so.2` # Description `nss-myhostname` is a plug-in module for the GNU Name Service Switch (NSS) functionality of the GNU C Library (`glibc`), primarily providing hostname resolution for the locally configured system hostname as returned by `gethostname(2)`. The precise hostnames resolved by this module are: - The local, configured hostname is resolved to all locally configured IP addresses ordered by their scope, or — if none are configured — the IPv4 address 127.0.0.2 (which is on the local loopback) and the IPv6 address ::1 (which is the local host). - The hostnames `localhost` and `localhost.localdomain` (as well as any hostname ending in `.localhost` or `.localhost.localdomain`) are resolved to the IP addresses 127.0.0.1 and ::1. - The hostname `_gateway` is resolved to all current default routing gateway addresses, ordered by their metric. This assigns a stable hostname to the current gateway, useful for referencing it independently of the current network configuration state. - The hostname `_outbound` is resolved to the local IPv4 and IPv6 addresses that are most likely used for communication with other hosts. This is the preferred source addresses of default gateways if specified, or determined by requesting a routing decision to the configured default gateways from the kernel and then using the local IP addresses selected by this decision. This hostname is only available if there is at least one local default gateway configured. This assigns a stable hostname to the local outbound IP addresses, useful for referencing them independently of the current network configuration state. Various software relies on an always-resolvable local hostname. When using dynamic hostnames, this is traditionally achieved by patching `/etc/hosts` at the same time as changing the hostname. This is problematic since it requires a writable `/etc/` file system and is fragile because the file might be edited by the administrator at the same time. With `nss-myhostname` enabled, changing `/etc/hosts` is unnecessary, and on many systems, the file becomes entirely optional. To activate the NSS modules, add `myhostname` to the line starting with `hosts:` in `/etc/nsswitch.conf`. It is recommended to place `myhostname` after `files` and before `dns`. This resolves well-known hostnames like `localhost` and the machine hostnames locally. It is consistent with the behaviour of `nss-resolve`, and still allows overriding via `/etc/hosts`. Please keep in mind that `nss-myhostname` (and `nss-resolve`) also resolve in the other direction — from locally attached IP addresses to hostnames. If you rely on that lookup being provided by DNS, you might want to order things differently. # Example Here is an example `/etc/nsswitch.conf` file that enables `nss-myhostname` correctly: passwd: files systemd group: files [SUCCESS=merge] systemd shadow: files systemd gshadow: files systemd hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns networks: files protocols: db files services: db files ethers: db files rpc: db files netgroup: nis To test, use `glibc`'s `getent(1)` tool: $ getent ahosts `hostname` ::1 STREAM omega ::1 DGRAM ::1 RAW 127.0.0.2 STREAM 127.0.0.2 DGRAM 127.0.0.2 RAW In this case, the local hostname is `omega`. # See Also `systemd(1)`, `nss-systemd(8)`, `nss-resolve(8)`, `nss-mymachines(8)`, `nsswitch.conf(5)`, `getent(1)` # nss-mymachines systemd nss-mymachines 8 nss-mymachines libnss_mymachines.so.2 Hostname resolution for local container instances `libnss_mymachines.so.2` # Description `nss-mymachines` is a plug-in module for the GNU Name Service Switch (NSS) functionality of the GNU C Library (`glibc`), providing hostname resolution for the names of containers running locally that are registered with `systemd-machined.service(8)`. The container names are resolved to the IP addresses of the specific container, ordered by their scope. This functionality only applies to containers using network namespacing (see the description of `--private-network` in `systemd-nspawn(1)`). Note that the name that is resolved is the one registered with `systemd-machined`, which may be different than the hostname configured inside of the container. Note that this NSS module only makes available names of the containers running immediately below the current system context. It does not provide host name resolution for containers running side-by-side with the invoking system context, or containers further up or down the container hierarchy. Or in other words, on the host system it provides host name resolution for the containers running immediately below the host environment. When used inside a container environment however, it will not be able to provide name resolution for containers running on the host (as those are siblings and not children of the current container environment), but instead only for nested containers running immediately below its own container environment. To activate the NSS module, add `mymachines` to the line starting with `hosts:` in `/etc/nsswitch.conf`. It is recommended to place `mymachines` before the `resolve` or `dns` entry of the `hosts:` line of `/etc/nsswitch.conf` in order to make sure that its mappings are preferred over other resolvers such as DNS. # Configuration in `/etc/nsswitch.conf` Here is an example `/etc/nsswitch.conf` file that enables `nss-mymachines` correctly: passwd: files systemd group: files [SUCCESS=merge] systemd shadow: files systemd gshadow: files systemd hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns networks: files protocols: db files services: db files ethers: db files rpc: db files netgroup: nis # Example: Mappings provided by `nss-mymachines` The container `rawhide` is spawned using `systemd-nspawn(1)`: # systemd-nspawn -M rawhide --boot --network-veth --private-users=pick Spawning container rawhide on /var/lib/machines/rawhide. Selected user namespace base 20119552 and range 65536. ... $ machinectl --max-addresses=3 MACHINE CLASS SERVICE OS VERSION ADDRESSES rawhide container systemd-nspawn fedora 30 169.254.40.164 fe80::94aa:3aff:fe7b:d4b9 $ ping -c1 rawhide PING rawhide(fe80::94aa:3aff:fe7b:d4b9%ve-rawhide (fe80::94aa:3aff:fe7b:d4b9%ve-rawhide)) 56 data bytes 64 bytes from fe80::94aa:3aff:fe7b:d4b9%ve-rawhide (fe80::94aa:3aff:fe7b:d4b9%ve-rawhide): icmp_seq=1 ttl=64 time=0.045 ms ... $ ping -c1 -4 rawhide PING rawhide (169.254.40.164) 56(84) bytes of data. 64 bytes from 169.254.40.164 (169.254.40.164): icmp_seq=1 ttl=64 time=0.064 ms ... # machinectl shell rawhide /sbin/ip a Connected to machine rawhide. Press ^] three times within 1s to exit session. 1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 ... 2: host0@if21: mtu 1500 qdisc noqueue state UP group default qlen 1000 link/ether 96:aa:3a:7b:d4:b9 brd ff:ff:ff:ff:ff:ff link-netnsid 0 inet 169.254.40.164/16 brd 169.254.255.255 scope link host0 valid_lft forever preferred_lft forever inet6 fe80::94aa:3aff:fe7b:d4b9/64 scope link valid_lft forever preferred_lft forever Connection to machine rawhide terminated. # See Also `systemd(1)`, `systemd-machined.service(8)`, `machinectl(1)`, `nss-systemd(8)`, `nss-resolve(8)`, `nss-myhostname(8)`, `nsswitch.conf(5)`, `getent(1)` # nss-resolve systemd nss-resolve 8 nss-resolve libnss_resolve.so.2 Hostname resolution via systemd-resolved.service `libnss_resolve.so.2` # Description `nss-resolve` is a plug-in module for the GNU Name Service Switch (NSS) functionality of the GNU C Library (`glibc`) enabling it to resolve hostnames via the `systemd-resolved(8)` local network name resolution service. It replaces the `nss-dns` plug-in module that traditionally resolves hostnames via DNS. To activate the NSS module, add `resolve [!UNAVAIL=return]` to the line starting with `hosts:` in `/etc/nsswitch.conf`. Specifically, it is recommended to place `resolve` early in `/etc/nsswitch.conf`'s `hosts:` line. It should be before the `files` entry, since `systemd-resolved` supports `/etc/hosts` internally, but with caching. To the contrary, it should be after `mymachines`, to give hostnames given to local VMs and containers precedence over names received over DNS. Finally, we recommend placing `dns` somewhere after `resolve`, to fall back to `nss-dns` if `systemd-resolved.service` is not available. Note that `systemd-resolved` will synthesize DNS resource records in a few cases, for example for `localhost` and the current local hostname, see `systemd-resolved(8)` for the full list. This duplicates the functionality of `nss-myhostname(8)`, but it is still recommended (see examples below) to keep `nss-myhostname` configured in `/etc/nsswitch.conf`, to keep those names resolvable if `systemd-resolved` is not running. Please keep in mind that `nss-myhostname` (and `nss-resolve`) also resolve in the other direction — from locally attached IP addresses to hostnames. If you rely on that lookup being provided by DNS, you might want to order things differently. Communication between `nss-resolve` and `systemd-resolved.service` takes place via the `/run/systemd/resolve/io.systemd.Resolve` `AF_UNIX` socket. # Environment variables `$SYSTEMD_NSS_RESOLVE_VALIDATE` Takes a boolean argument. When false, cryptographic validation of resource records via DNSSEC will be disabled. This may be useful for testing, or when system time is known to be unreliable. `$SYSTEMD_NSS_RESOLVE_SYNTHESIZE` Takes a boolean argument. When false, synthetic records, e.g. for the local host name, will not be returned. See section SYNTHETIC RECORDS in `systemd-resolved.service(8)` for more information. This may be useful to query the "public" resource records, independent of the configuration of the local machine. `$SYSTEMD_NSS_RESOLVE_CACHE` Takes a boolean argument. When false, the cache of previously queried records will not be used by `systemd-resolved(8)`. `$SYSTEMD_NSS_RESOLVE_ZONE` Takes a boolean argument. When false, answers using locally registered public LLMNR/mDNS resource records will not be returned. `$SYSTEMD_NSS_RESOLVE_TRUST_ANCHOR` Takes a boolean argument. When false, answers using locally configured trust anchors will not be used. `$SYSTEMD_NSS_RESOLVE_NETWORK` Takes a boolean argument. When false, answers will be returned without using the network, i.e. either from local sources or the cache in `systemd-resolved(8)`. `$SYSTEMD_NSS_RESOLVE_INTERFACE` Takes an interface name or index as an argument. When specified, answers will only be obtained from name servers belonging to the specified interface. # Example Here is an example `/etc/nsswitch.conf` file that enables `nss-resolve` correctly: passwd: files systemd group: files [SUCCESS=merge] systemd shadow: files systemd gshadow: files systemd hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns networks: files protocols: db files services: db files ethers: db files rpc: db files netgroup: nis # See Also `systemd(1)`, `systemd-resolved(8)`, `nss-systemd(8)`, `nss-myhostname(8)`, `nss-mymachines(8)`, `nsswitch.conf(5)`, `systemd.syntax(7)` # nss-systemd systemd nss-systemd 8 nss-systemd libnss_systemd.so.2 UNIX user and group name resolution for user/group lookup via Varlink `libnss_systemd.so.2` # Description `nss-systemd` is a plug-in module for the GNU Name Service Switch (NSS) functionality of the GNU C Library (`glibc`), providing UNIX user and group name resolution for services implementing the [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API), such as the system and service manager `systemd(1)` (for its `DynamicUser=` feature, see `systemd.exec(5)` for details), `systemd-homed.service(8)`, or `systemd-machined.service(8)`. This module also ensures that the root and nobody users and groups (i.e. the users/groups with the UIDs/GIDs 0 and 65534) remain resolvable at all times, even if they are not listed in `/etc/passwd` or `/etc/group`, or if these files are missing. This module preferably utilizes `systemd-userdbd.service(8)` for resolving users and groups, but also works without the service running. To activate the NSS module, add `systemd` to the lines starting with `passwd:`, `group:`, `shadow:` and `gshadow:` in `/etc/nsswitch.conf`. It is recommended to place `systemd` after the `files` entry of the `/etc/nsswitch.conf` lines so that `/etc/passwd`, `/etc/group`, `/etc/shadow` and `/etc/gshadow` based mappings take precedence. # Static Drop-In JSON User/Group Records Besides user/group records acquired via the aforementioned Varlink IPC interfaces and the synthesized root and nobody accounts, this module also makes user and group accounts available to the system that are defined in static drop-in files in the `/etc/userdb/`, `/run/userdb/`, `/run/host/userdb/` and `/usr/lib/userdb/` directories. This is a simple mechanism to provide static user and group records via JSON drop-in files. Such user records should be defined in the format described by the [JSON User Records](https://systemd.io/USER_RECORD) specification and be placed in one of the aforementioned directories under a file name composed of the user name suffixed with `.user`, with a world-readable access mode. A symlink named after the user record's UID formatted in decimal and suffixed with `.user` pointing to the primary record file should be created as well, in order to allow both lookups by username and by UID. Privileged user record data (e.g. hashed UNIX passwords) may optionally be provided as well, in a pair of separate companion files with the `.user-privileged` suffix. The data should be stored in a regular file named after the user name, suffixed with `.user-privileged`, and a symlink pointing to it, named after the used numeric UID formatted in decimal with the same suffix. These companion files should not be readable to anyone but root. Example: -rw-r--r--. 1 root root 723 May 10 foobar.user -rw-------. 1 root root 123 May 10 foobar.user-privileged lrwxrwxrwx. 1 root root 19 May 10 4711.user -> foobar.user lrwxrwxrwx. 1 root root 19 May 10 4711.user-privileged -> foobar.user-privileged Similarly, group records following the format described in [JSON Group Record](https://systemd.io/GROUP_RECORD) may be defined, using the file suffixes `.group` and `.group-privileged`. The primary user/group record files (i.e. those with the `.user` and `.group` suffixes) should not contain the `privileged` section as described in the specifications. The privileged user/group record files (i.e. those with the `.user-privileged` and `.group-privileged` suffixes) should contain this section, exclusively. In addition to the two types of user record files and the two types of group record files there's a fifth type of file that may be placed in the searched directories: files that indicate membership of users in groups. Specifically, for every pair of user/group where the user shall be a member of a group a file named `username:groupname.membership` must be created, i.e. the textual UNIX user name, followed by a colon, followed by the textual UNIX group name, suffixed by `.membership`. The contents of these files are currently not read, however it is recommended to create them containing an empty JSON object (i.e. `{}`). The mere existence of these files is enough to affect a user/group membership. If a program provides user and/or group record files in the searched directories, it must always also create such files, both for primary and auxiliary group memberships. Note that static user/group records generally do not override conflicting records in `/etc/passwd` or `/etc/group` or other account databases. In fact, before dropping in these files a reasonable level of care should be taken to avoid user/group name and UID/GID conflicts. The `systemd-userdb-load-credentials.service` service automatically runs at boot and installs these files from user records passed in via system credentials. See `userdbctl(1)` and `systemd.system-credentials(7)` for details. # Configuration in `/etc/nsswitch.conf` Here is an example `/etc/nsswitch.conf` file that enables `nss-systemd` correctly: passwd: files systemd group: files [SUCCESS=merge] systemd shadow: files systemd gshadow: files systemd hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns networks: files protocols: db files services: db files ethers: db files rpc: db files netgroup: nis # Example: Mappings provided by `systemd-machined.service` The container `rawhide` is spawned using `systemd-nspawn(1)`: # systemd-nspawn -M rawhide --boot --network-veth --private-users=pick Spawning container rawhide on /var/lib/machines/rawhide. Selected user namespace base 20119552 and range 65536. ... $ machinectl --max-addresses=3 MACHINE CLASS SERVICE OS VERSION ADDRESSES rawhide container systemd-nspawn fedora 30 169.254.40.164 fe80::94aa:3aff:fe7b:d4b9 $ getent passwd vu-rawhide-0 vu-rawhide-81 vu-rawhide-0:*:20119552:65534:vu-rawhide-0:/:/usr/sbin/nologin vu-rawhide-81:*:20119633:65534:vu-rawhide-81:/:/usr/sbin/nologin $ getent group vg-rawhide-0 vg-rawhide-81 vg-rawhide-0:*:20119552: vg-rawhide-81:*:20119633: $ ps -o user:15,pid,tty,command -e|grep '^vu-rawhide' vu-rawhide-0 692 ? /usr/lib/systemd/systemd vu-rawhide-0 731 ? /usr/lib/systemd/systemd-journald vu-rawhide-192 734 ? /usr/lib/systemd/systemd-networkd vu-rawhide-193 738 ? /usr/lib/systemd/systemd-resolved vu-rawhide-0 742 ? /usr/lib/systemd/systemd-logind vu-rawhide-81 744 ? /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only vu-rawhide-0 746 ? /usr/sbin/sshd -D ... vu-rawhide-0 752 ? /usr/lib/systemd/systemd --user vu-rawhide-0 753 ? (sd-pam) vu-rawhide-0 1628 ? login -- zbyszek vu-rawhide-1000 1630 ? /usr/lib/systemd/systemd --user vu-rawhide-1000 1631 ? (sd-pam) vu-rawhide-1000 1637 pts/8 -zsh # See Also `systemd(1)`, `systemd.exec(5)`, `nss-resolve(8)`, `nss-myhostname(8)`, `nss-mymachines(8)`, `systemd-userdbd.service(8)`, `systemd-homed.service(8)`, `systemd-machined.service(8)`, `userdbctl(1)`, `systemd.system-credentials(7)`, `nsswitch.conf(5)`, `getent(1)` # oomctl systemd oomctl 1 oomctl Analyze the state stored in systemd-oomd oomctl OPTIONS COMMAND # Description `oomctl` may be used to get information about the various contexts read in by the `systemd(1)` userspace out-of-memory (OOM) killer, `systemd-oomd(8)`. # Commands The following commands are understood: `dump` Show the current state of the cgroups and system contexts stored by `systemd-oomd`. # Options The following options are understood: # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-oomd.service(8)`, `oomd.conf(5)` # oomd.conf systemd oomd.conf 5 oomd.conf oomd.conf.d Global systemd-oomd configuration files `/etc/systemd/oomd.conf`, `/run/systemd/oomd.conf`, `/usr/local/lib/systemd/oomd.conf`, `/usr/lib/systemd/oomd.conf`, `/etc/systemd/oomd.conf.d/*.conf`, `/run/systemd/oomd.conf.d/*.conf`, `/usr/local/lib/systemd/oomd.conf.d/*.conf`, `/usr/lib/systemd/oomd.conf.d/*.conf` # Description These files configure the various parameters of the `systemd(1)` userspace out-of-memory (OOM) killer, `systemd-oomd.service(8)`. See `systemd.syntax(7)` for a general description of the syntax. # Prekill event `systemd-oomd` supports notifying external components before killing a control group. This is done by sending a notification over varlink to all sockets found in `/run/systemd/oomd.prekill.hook/` folder. Each socket should implement the `io.systemd.oom.Prekill` interface. The notification contains the control group path to allow the hook to identify which control group is being killed. This allows external components to perform any necessary cleanup or logging before the control group is terminated. The hook is not intended as a way to avoid the kill, but rather as a notification mechanism. Note that this is a privileged option as, even if it has a timeout, is synchronous and delays the kill, so use with care. The typically preferable mechanism to process memory pressure is to do what [Resource Pressure Handling](https://systemd.io/PRESSURE) describes which is unprivileged, asynchronous and does not delay the kill. # OOM Rulesets `systemd-oomd` supports custom rulesets that define conditions and actions for OOM handling on a per-unit basis. Ruleset files use the `.oomrule` extension and are loaded from `/etc/systemd/oomd/rules.d/`, `/run/systemd/oomd/rules.d/`, `/usr/local/lib/systemd/oomd/rules.d/`, and `/usr/lib/systemd/oomd/rules.d/`. Units opt into rulesets via the `OOMRules=` setting in `systemd.resource-control(5)`, which takes a space-separated list of ruleset names (the file name without the `.oomrule` extension). Each ruleset file contains a `[Rule]` section with the following options. At least one of `MemoryPressureAbove=` or `SwapUsageMax=` must be configured; rulesets with no conditions are ignored. If both are set, the conditions are combined with AND, i.e. the action is only triggered when both thresholds are exceeded simultaneously. `MemoryPressureAbove=` Sets the memory pressure threshold above which the rule's action will be triggered. The memory pressure represents the fraction of time in a 10 second window in which all tasks in the control group were delayed (PSI `full avg10`). Takes a value specified in percent (when suffixed with `%`), permille (`‰`) or permyriad (`‱`), between 0% and 100%, inclusive. If unset, this condition is not evaluated. A value of `100%` can never be exceeded and is therefore rejected with a warning; a value of `0%` makes the condition true on any observed pressure, which is usually not useful. `SwapUsageMax=` Sets the system-wide swap usage threshold above which the rule's action will be triggered. Takes a value specified in percent (when suffixed with `%`), permille (`‰`) or permyriad (`‱`), between 0% and 100%, inclusive. If unset, this condition is not evaluated. A value of `100%` can never be exceeded and is therefore rejected with a warning; a value of `0%` fires as soon as any swap is in use, which is usually not useful. `Action=` Specifies the action to take when the rule's conditions are met. Takes one of `kill-all`, `kill-by-pgscan`, or `kill-by-swap`. This setting is mandatory; rulesets without `Action=` are ignored. - `kill-all` sends `SIGKILL` to every process in the unit's cgroup hierarchy, including any descendant cgroups. - `kill-by-pgscan` selects and kills the descendant cgroup with the highest recent page scan (reclaim) rate. - `kill-by-swap` selects and kills the descendant cgroup with the highest swap usage. `LastingSec=` Sets the duration the conditions must be continuously met before the action is taken. Takes a time span value, see `systemd.time(7)` for details on the permitted syntax. Defaults to 0, i.e. the action is taken immediately when the conditions are met. # \[OOM\] Section Options The following options are available in the \[OOM\] section: `SwapUsedLimit=` Sets the limit for memory and swap usage on the system before `systemd-oomd` will take action. If the fraction of memory used and the fraction of swap used on the system are both more than what is defined here, `systemd-oomd` will act on eligible descendant control groups with swap usage greater than 5% of total swap, starting from the ones with the highest swap usage. Which control groups are monitored and what action gets taken depends on what the unit has configured for `ManagedOOMSwap=`. Takes a value specified in percent (when suffixed with "%"), permille ("‰") or permyriad ("‱"), between 0% and 100%, inclusive. Defaults to 90%. `DefaultMemoryPressureLimit=` Sets the limit for memory pressure on the unit's control group before `systemd-oomd` will take action. A unit can override this value with `ManagedOOMMemoryPressureLimit=`. The memory pressure for this property represents the fraction of time in a 10 second window in which all tasks in the control group were delayed. For each monitored control group, if the memory pressure on that control group exceeds the limit set for longer than the duration set by `DefaultMemoryPressureDurationSec=`, `systemd-oomd` will act on eligible descendant control groups, starting from the ones with the most reclaim activity to the least reclaim activity. Which control groups are monitored and what action gets taken depends on what the unit has configured for `ManagedOOMMemoryPressure=`. Takes a fraction specified in the same way as `SwapUsedLimit=` above. Defaults to 60%. `DefaultMemoryPressureDurationSec=` Sets the amount of time a unit's control group needs to have exceeded memory pressure limits before `systemd-oomd` will take action. A unit can override this value with `ManagedOOMMemoryPressureDurationSec=`. Memory pressure limits are defined by `DefaultMemoryPressureLimit=` and `ManagedOOMMemoryPressureLimit=`. Must be set to 0, or at least 1 second. Defaults to 30 seconds when unset or 0. `PrekillHookTimeoutSec=` Sets the amount of time `systemd-oomd` will wait for pre-kill hooks to complete, before proceeding with the control group termination. Pre-kill hooks work by placing varlink socket to `/run/systemd/oomd.prekill.hook/` folder. Each socket should implement interface for notification to work. `systemd-oomd` sends a notification before killing a control group for each discovered socket. The timeout is intended to be global and not per hook. If all hooks return earlier, the kill is performed as soon as possible. The timeout must be at least 1s. Defaults to 0, which means `systemd-oomd` will not wait and no notifications will be sent. # See Also `systemd(1)`, `systemd.resource-control(5)`, `systemd-oomd.service(8)`, `oomctl(1)` # org.freedesktop.LogControl1 systemd org.freedesktop.LogControl1 5 org.freedesktop.LogControl1 D-Bus interface to query and set logging configuration # Introduction org.freedesktop.LogControl1 is a generic interface that is intended to be used by any daemon which allows the log level and target to be set over D-Bus. It is implemented by various daemons that are part of the `systemd(1)` suite. It is assumed that those settings are global for the whole program, so a fixed object path is used. The interface should always be available under the path `/org/freedesktop/LogControl1`. # Description The following interface is exposed: node /org/freedesktop/LogControl1 { interface org.freedesktop.LogControl1 { properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite s LogLevel = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite s LogTarget = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s SyslogIdentifier = '...'; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Properties `LogLevel` describes the `syslog(3)`-style log-level, and should be one of `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, `debug`, in order of increasing verbosity. `LogTarget` describes the log target (mechanism). It should be one of `console` (log to the console or standard output), `kmsg` (log to the kernel ring buffer), `journal` (log to the journal natively, see `systemd-journald.service(8)`), `syslog` (log using the `syslog(3)` call). > [!CAUTION] > The `LogLevel` and `LogTarget` properties are supposed to be writable. Care should be taken to ensure that only appropriately privileged clients can modify them. `SyslogIdentifier` is a read-only property that shows the "syslog identifier". It is a short string that identifies the program that is the source of log messages that is passed to the `syslog(3)` call. # Tools `journalctl` option `-p`/`--priority=` may be used to filter log messages by log level, option `-t`/`--identifier=` may be used to by the syslog identifier, and filters like `_TRANSPORT=syslog`, `_TRANSPORT=journal`, and `_TRANSPORT=kernel` may be used to filter messages by the mechanism through which they reached `systemd-journald`. `systemctl log-level` and `systemctl log-target` verbs may be used to query and set the `LogLevel` and `LogTarget` properties of the service manager. `systemctl service-log-level` and `systemctl service-log-target` may similarly be used for individual services. (Services must have the `BusName=` property set and must implement the interface described here. See `systemd.service(5)` for details about `BusName=`.) # Example
Create a simple listener on the bus that implements LogControl1
This creates a simple server on the bus. It implements the LogControl1 interface by providing the required properties and allowing to set the writable ones. It logs at the configured log level using `sd_journal_print(3)`. Note that when porting this example to other D-Bus libraries it might be necessary to add manual client privilege checks, as they typically do not default to the restrictive defaults of sd-bus, where unprivileged access to properties is controlled via the `SD_BUS_VTABLE_UNPRIVILEGED` flag that is opt-in rather than opt-out.
# See Also `systemd(1)`, `journalctl(1)`, `systemctl(1)`, `systemd.service(5)`, `syslog(3)` # org.freedesktop.home1 systemd org.freedesktop.home1 5 org.freedesktop.home1 The D-Bus interface of systemd-homed # Introduction `systemd-homed.service(8)` is a system service which may be used to create, remove, change or inspect home areas. This page describes the D-Bus interface. # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/home1 { interface org.freedesktop.home1.Manager { methods: GetHomeByName(in s user_name, out u uid, out s home_state, out u gid, out s real_name, out s home_directory, out s shell, out o bus_path); GetHomeByUID(in u uid, out s user_name, out s home_state, out u gid, out s real_name, out s home_directory, out s shell, out o bus_path); GetUserRecordByName(in s user_name, out s user_record, out b incomplete, out o bus_path); GetUserRecordByUID(in u uid, out s user_record, out b incomplete, out o bus_path); ListHomes(out a(susussso) home_areas); ActivateHome(in s user_name, in s secret); ActivateHomeIfReferenced(in s user_name, in s secret); @org.freedesktop.systemd1.Privileged("true") DeactivateHome(in s user_name); RegisterHome(in s user_record); AdoptHome(in s image_path, in t flags); UnregisterHome(in s user_name); CreateHome(in s user_record); CreateHomeEx(in s user_record, in a{sh} blobs, in t flags); RealizeHome(in s user_name, in s secret); RemoveHome(in s user_name); @org.freedesktop.systemd1.Privileged("true") FixateHome(in s user_name, in s secret); AuthenticateHome(in s user_name, in s secret); UpdateHome(in s user_record); UpdateHomeEx(in s user_record, in a{sh} blobs, in t flags); ResizeHome(in s user_name, in t size, in s secret); ChangePasswordHome(in s user_name, in s new_secret, in s old_secret); @org.freedesktop.systemd1.Privileged("true") LockHome(in s user_name); @org.freedesktop.systemd1.Privileged("true") UnlockHome(in s user_name, in s secret); AcquireHome(in s user_name, in s secret, in b please_suspend, out h send_fd); @org.freedesktop.systemd1.Privileged("true") RefHome(in s user_name, in b please_suspend, out h send_fd); @org.freedesktop.systemd1.Privileged("true") RefHomeUnrestricted(in s user_name, in b please_suspend, out h send_fd); @org.freedesktop.systemd1.Privileged("true") ReleaseHome(in s user_name); ListSigningKeys(out a(sst) keys); GetSigningKey(in s name, out s der, out t flags); AddSigningKey(in s name, in s pem, in t flags); RemoveSigningKey(in s name, in t flags); @org.freedesktop.systemd1.Privileged("true") LockAllHomes(); @org.freedesktop.systemd1.Privileged("true") DeactivateAllHomes(); @org.freedesktop.systemd1.Privileged("true") Rebalance(); properties: readonly a(sso) AutoLogin = [...]; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `GetHomeByName()` returns basic user information (a minimal subset of the full user record), provided a user name. The information supplied more or less matches what `getpwnam(3)` returns: the numeric UID and GID, the real name, home directory and shell. In addition it returns a state identifier describing the state the user's home directory is in, as well as a bus path referring to the bus object encapsulating the user record and home directory. This object implements the `org.freedesktop.home1.Home` interface documented below. This method, and most others in this interface that take user names, will try to use the caller's home area if the specified user name is an empty string. `GetHomeByUID()` is similar to `GetHomeByName()` but acquires the information based on the numeric UID of the user. `GetUserRecordByName()` is also similar to `GetHomeByName()` but returns the full JSON user record data instead of the broken down records. An additional returned boolean indicates whether the record is complete or not. A record is considered complete when its `privileged` section is included, and incomplete if it was removed (see [JSON User Records](https://systemd.io/USER_RECORD) for details about the various sections of a user record). Generally, only privileged clients and clients running under the identity of the user itself get access to the `privileged` section and will thus see complete records. `GetUserRecordByUID()` is similar to `GetUserRecordByName()` but returns the user record matching the specified numeric UID. `ListHomes()` returns an array of all locally managed users. The array contains the same fields `GetHomeByName()` returns: user name, numeric UID, state, numeric GID, real name, home directory, shell and bus path of the matching bus object. `ActivateHome()` activates (i.e. mounts) the home directory of the specified user. The second argument shall contain a user record consisting only of a `secret` section (all other sections should be stripped, see [JSON User Records](https://systemd.io/USER_RECORD) for details), and should contain only the secret credentials necessary for unlocking the home directory. Typically a client would invoke this function first with an entirely empty record (which is possibly sufficient if single-factor authentication with a plugged-in security token is configured), and would then retry with a record populated with more information, depending on the returned error code, in case more credentials are necessary. This function is synchronous and returns only after the home directory was fully activated (or the operation failed), which might take some time. Clients must be prepared for that, and typically should extend the D-Bus method call timeout accordingly. This method is equivalent to the `Activate()` method on the `org.freedesktop.home1.Home` interface documented below, but may be called on the manager object and takes a user name as additional argument, instead. `ActivateHomeIfReferenced()` is identical to `ActivateHome()`. However, the call only succeeds if the home directory is currently referenced. Useful in conjunction with `RefHomeUnrestricted()`, which allows creating a reference to a home directory even if the home directory is not active. `DeactivateHome()` deactivates (i.e. unmounts) the home directory of the specified user. It is equivalent to the `Deactivate()` method on the `org.freedesktop.home1.Home` interface documented below. `RegisterHome()` registers a new home directory locally. It receives the JSON user record as only argument (which typically excludes the `secret` section). Registering a home directory just makes the user record known to the system, it does not create a home directory or such (which is expected to exist already, or created later). This operation is useful to register home directories locally that are not located where `systemd-homed.service` would find them automatically. `AdoptHome()` also registers a new home directory locally. It takes a path to a home directory itself, and will register it locally. This only works for `*.home` and `*.homedir/` home directories. This operation is done automatically for all such home areas showing up in `/home/`, but may be requested explicitly with this call for directories elsewhere. The `flags` must be set to zero, currently. `UnregisterHome()` unregisters an existing home directory. It takes a user name as argument and undoes what `RegisterHome()` does. It does not attempt to remove the home directory itself, it just unregisters it with the local system. Note that if the home directory is placed where `systemd-homed.service` looks for home directories anyway this call will only undo fixation (see below), but the record will remain known to `systemd-homed.service` and be listed among known records. Since the user record is embedded into the home directory this operation generally does not discard data belonging to the user or their record. This method is equivalent to `Unregister()` on the `org.freedesktop.home1.Home` interface. `CreateHome()` registers and creates a new home directory. This takes a fully specified JSON user record as argument (including the `secret` section). This registers the user record locally and creates a home directory matching it, depending on the settings specified in the record in combination with local configuration. `CreateHomeEx()` is like `CreateHome()`, but it allows the home directory to be created with a pre-populated blob directory (see [User Record Blob Directories](https://systemd.io/USER_RECORD_BLOB_DIRS) for more info). This can be done via the dictionary passed as the `blobs` argument to this method: the values are open file descriptors to regular files, and the keys are the filenames that should contain their respective file's data in the blob directory. Note that for security reasons, the file descriptors passed into this method must have enough privileges to read their target file and thus cannot be `O_PATH`; this is done to ensure the caller is actually permitted to read the file they are asking to publish in the blob directories. If the user record passed as the first argument contains a `blobManifest` field it will be enforced; otherwise, a `blobManifest` field will be generated and inserted into the record. The `flags` argument may be used for future expansion, but for now pass 0. `RealizeHome()` creates a home directory whose user record is already registered locally. This takes a user name plus a user record consisting only of the `secret` section. Invoking `RegisterHome()` followed by `RealizeHome()` is mostly equivalent to calling `CreateHome()`, except that the latter combines the two in atomic fashion. This method is equivalent to `Realize()` on the `org.freedesktop.home1.Home` interface. `RemoveHome()` unregisters a user record locally, and removes the home directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to `Remove()` on the `org.freedesktop.home1.Home` interface. `FixateHome()` `fixates` an automatically discovered home directory. `systemd-homed.service` automatically discovers home directories dropped in our plugged in and adds them to the runtime list of user records it manages. A user record discovered that way may be `fixated`, in which case it is copied out of the home directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract additional (typically previously encrypted) user record data from the home directory. A home directory mus be fixated before it can be logged into. This method call takes a user name and a JSON user record consisting only of the `secret` section as argument. This method is equivalent to `Fixate()` on the `org.freedesktop.home1.Home` interface. `AuthenticateHome()` checks passwords or other authentication credentials associated with the home directory. It takes a user name and a JSON user record consisting only of the `secret` section as argument. Note that many of the other method calls authenticate the user first, in order to execute some other operation. This method call only authenticates and executes no further operation. Like `ActivateHome()` it is usually first invoked with an empty JSON user record, which is then populated for subsequent tries with additional authentication data supplied. This method is equivalent to `Authenticate()` on the `org.freedesktop.home1.Home` interface. `UpdateHome()` updates a locally registered user record. Takes a fully specified JSON user record as argument (possibly including the `secret` section). A user with a matching name and realm must be registered locally already, and the last change timestamp of the newly supplied record must be newer than the previously existing user record. Note this operation updates the user record only, it does not propagate passwords/authentication tokens from the user record to the storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then the password of the underlying storage updated using `ChangePasswordHome()` as well as the storage resized using `ResizeHome()`. This method is equivalent to `Update()` on the `org.freedesktop.home1.Home` interface. `UpdateHomeEx()` is like `UpdateHome()`, but it allows for changes to the blob directory (see [User Record Blob Directories](https://systemd.io/USER_RECORD_BLOB_DIRS) for more info). The `blobs` argument works in the same way as `CreateHomeEx()`, so check there for details. The new blob directory contents passed into this method will completely replace the user's existing blob directory. The `flags` argument can be used to further customize the behavior of this method via flags defined as follows: #define SD_HOMED_UPDATE_OFFLINE (UINT64_C(1) << 0) When `SD_HOMED_UPDATE_OFFLINE` (0x01) is set, no attempt is made to update the copies of the user record and blob directory that are embedded into the home directory. Changes will be stored, however, and may be propagated into the home directory the next time it is reconciled (most likely when the user next logs in). Note that any changes made with this flag set may be lost if the home area has a newer record, which can happen if the home area is updated on another machine after this method call. This method is equivalent to `UpdateEx()` on the `org.freedesktop.home1.Home` interface. `ResizeHome()` resizes the storage associated with a user record. Takes a user name, a disk size in bytes, and optionally a user record consisting only of the `secret` section as arguments. If the size is specified as `UINT64_MAX` the storage is resized to the size already specified in the user record. Typically, if the user record is updated using `UpdateHome()` above this is used to propagate the size configured there-in down to the underlying storage back-end. This method is equivalent to `Resize()` on the `org.freedesktop.home1.Home` interface. `ChangePasswordHome()` changes the passwords/authentication tokens of a home directory. Takes a user name, and two JSON user record objects, each consisting only of the `secret` section, for the old and for the new passwords/authentication tokens. If the user record with the new passwords/authentication token data is specified as empty the existing user record's settings are propagated down to the home directory storage. This is typically used after a user record is updated using `UpdateHome()` in order to propagate the secrets/authentication tokens down to the storage. Background: depending on the backend the user's authentication credentials are stored at multiple places: the user record kept on the host, the user record kept in the home directory and the encrypted LUKS volume slot. If the home directory is used on a different machined temporarily, and the password is changed there, and then is moved back to the original host, the passwords of the three might get out of sync. By issuing `ChangePasswordHome()` the three locations are updated to match the newest information. This method is equivalent to `ChangePassword()` on the `org.freedesktop.home1.Home` interface. `LockHome()` temporarily suspends access to a home directory, flushing out any cryptographic keys from memory. This is only supported on some back-ends, and is usually done during system suspend, in order to effectively secure home directories while the system is sleeping. Takes a user name as single argument. If an application attempts to access a home directory while it is locked it will typically freeze until the home directory is unlocked again. This method is equivalent to `Lock()` on the `org.freedesktop.home1.Home` interface. `UnlockHome()` undoes the effect of `LockHome()`. Takes a user name and a user record consisting only of the `secret` section as arguments. This method is equivalent to `Unlock()` on the `org.freedesktop.home1.Home` interface. `AcquireHome()` activates or unlocks a home directory in a reference counted mode of operation. Takes a user name and user record consisting only of `secret` section as argument. If the home directory is not active yet, it is activated. If it is currently locked it is unlocked. After completion a reference to the activation/unlocking of the home directory is returned via a file descriptor. When the last client which acquired such a file descriptor closes it the home directory is automatically deactivated again. This method is typically invoked when a user logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home directory can be unmounted automatically again in a robust fashion, when the user logs out. The third argument is a boolean which indicates whether the client invoking the call is able to automatically re-authenticate when the system comes back from suspending. It should be set by all clients that implement a secure lock screen running outside of the user's context, that is brought up when the system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home directory. If a home directory has at least one client with an open reference to the home directory that does not support this it is not suspended automatically at system suspend, otherwise it is. This method is equivalent to `Acquire()` on the `org.freedesktop.home1.Home` interface. `RefHome()` is similar to `AcquireHome()` but takes no user record with `secret` section, i.e. will take an additional reference to an already activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the home directory is not already activated. This method is equivalent to `Ref()` on the `org.freedesktop.home1.Home` interface. `RefHomeUnrestricted()` is identical to `RefHome()` but succeeds even if the home area is not active currently. This is useful on conjunction with `ActivateHomeIfReferenced()`. `ReleaseHome()` releases a home directory again, if all file descriptors referencing it are already closed, that where acquired through `AcquireHome()` or `RefHome()`. Note that this call does not actually cause the deactivation of the home directory (which happens automatically when the last referencing file descriptor is closed), but is simply a synchronization mechanism that allows delaying of the user session's termination until any triggered deactivation is completed. This method is equivalent to `Release()` on the `org.freedesktop.home1.Home` interface. `LockAllHomes()` locks all active home directories that only have references that opted into automatic suspending during system suspend. This is usually invoked automatically shortly before system suspend. `DeactivateAllHomes()` deactivates all home areas that are currently active. This is usually invoked automatically shortly before system shutdown. `Rebalance()` synchronously rebalances free disk space between home areas. This only executes an operation if at least one home area using the LUKS2 backend is active and has rebalancing enabled, and is otherwise a NOP. `ListSigningKeys()` acquires a list of installed home area signing keys. Returns an array of key names with their PEM encoded public key data. Each entry also comes with a flags value which is currently unused and should be ignored by clients. `GetSigningKey()` acquires the PEM encoded public part of the specified home area signing key of the specified name. Also returns a currently unused flags value that should be ignored. The `flags` parameter must be set to zero, currently. `AddSigningKey()` adds a new key to the list of home area signing keys. Takes a name string (free-form, suitable as filename, with suffix `.public`), the PEM encoded public key data and a currently unused flags value that must be zero. The `flags` parameter must be set to zero, currently. `RemoveSigningKey()` removes a key from the list of home area signing keys. Takes the name of the key to remove and a currently unused flags value that must be zero. The `flags` parameter must be set to zero, currently. ## Properties `AutoLogin` exposes an array of structures consisting of user name, seat name and object path of an home directory object. All locally managed users that have the `autoLogin` field set are listed here, with the seat name they are associated with. A display manager may watch this property and pre-fill the login screen with the users exposed this way. # The Home Object node /org/freedesktop/home1/home { interface org.freedesktop.home1.Home { methods: Activate(in s secret); ActivateIfReferenced(in s secret); @org.freedesktop.systemd1.Privileged("true") Deactivate(); Unregister(); Realize(in s secret); Remove(); @org.freedesktop.systemd1.Privileged("true") Fixate(in s secret); Authenticate(in s secret); Update(in s user_record); UpdateEx(in s user_record, in a{sh} blobs, in t flags); Resize(in t size, in s secret); ChangePassword(in s new_secret, in s old_secret); @org.freedesktop.systemd1.Privileged("true") Lock(); @org.freedesktop.systemd1.Privileged("true") Unlock(in s secret); @org.freedesktop.systemd1.Privileged("true") Acquire(in s secret, in b please_suspend, out h send_fd); @org.freedesktop.systemd1.Privileged("true") Ref(in b please_suspend, out h send_fd); @org.freedesktop.systemd1.Privileged("true") RefUnrestricted(in b please_suspend, out h send_fd); @org.freedesktop.systemd1.Privileged("true") Release(); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UserName = '...'; readonly u UID = ...; readonly (suusss) UnixRecord = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s State = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly (sb) UserRecord = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.DBus.ObjectManager { ... }; }; ## Methods `Activate()`, `ActivateIfReferenced()`, `Deactivate()`, `Unregister()`, `Realize()`, `Remove()`, `Fixate()`, `Authenticate()`, `Update()`, `UpdateEx()`, `Resize()`, `ChangePassword()`, `Lock()`, `Unlock()`, `Acquire()`, `Ref()`, `RefUnrestricted()`, `Release()`, operate like their matching counterparts on the `org.freedesktop.home1.Manager` interface (see above). The main difference is that they are methods of the home directory objects, and hence carry no additional user name parameter. Which of the two flavors of methods to call depends on the handles to the user known on the client side: if only the user name is known, it is preferable to use the methods on the manager object since they operate with user names only. Clients can also easily operate on their own home area by using the methods on the manager object with an empty string as the user name. If the client has the home's object path already acquired in some way, however, it is preferable to operate on the `org.freedesktop.home1.Home` objects instead. ## Properties `UserName` contains the user name of the user account/home directory. `UID` contains the numeric UNIX UID of the user account. `UnixRecord` contains a structure encapsulating the six fields a struct passwd typically contains (the password field is suppressed). `State` exposes the current state home the home directory. `UserRecord` contains the full JSON user record string of the user account. # History ## The Manager Object `ActivateHomeIfReferenced()`, `RefHomeUnrestricted()`, `CreateHomeEx()`, and `UpdateHomeEx()` were added in version 256. `AdoptHome()`, `ListSigningKeys()`, `GetSigningKey()`, `AddSigningKey()`, and `RemoveSigningKey()` were added in version 258. ## Home Objects `ActivateIfReferenced()`, `RefUnrestricted()`, and `UpdateEx()` were added in version 256. # See Also `systemd(1)`, `systemd-homed.service(8)`, `homectl(1)` # org.freedesktop.hostname1 systemd org.freedesktop.hostname1 5 org.freedesktop.hostname1 The D-Bus interface of systemd-hostnamed # Introduction `systemd-hostnamed.service(8)` is a system service that can be used to control the hostname and related machine metadata from user programs. This page describes the hostname semantics and the D-Bus interface. # The D-Bus API The service exposes the following interfaces on the bus: node /org/freedesktop/hostname1 { interface org.freedesktop.hostname1 { methods: SetHostname(in s hostname, in b interactive); SetStaticHostname(in s hostname, in b interactive); SetPrettyHostname(in s hostname, in b interactive); SetIconName(in s icon, in b interactive); SetChassis(in s chassis, in b interactive); SetDeployment(in s deployment, in b interactive); SetLocation(in s location, in b interactive); SetTags(in as tags); AddAndRemoveTags(in as add, in as remove); GetProductUUID(in b interactive, out ay uuid); GetHardwareSerial(out s serial); Describe(out s json); GetMachineInfo(in s field, out s value); properties: readonly s Hostname = '...'; readonly s StaticHostname = '...'; readonly s PrettyHostname = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s DefaultHostname = '...'; readonly s HostnameSource = '...'; readonly s IconName = '...'; readonly s Chassis = '...'; readonly s Deployment = '...'; readonly s Location = '...'; readonly as Tags = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KernelName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KernelRelease = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KernelVersion = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s OperatingSystemPrettyName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s OperatingSystemFancyName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s OperatingSystemCPEName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t OperatingSystemSupportEnd = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HomeURL = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s OperatingSystemImageID = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s OperatingSystemImageVersion = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HardwareVendor = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HardwareModel = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HardwareSKU = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HardwareVersion = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s FirmwareVersion = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s FirmwareVendor = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t FirmwareDate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay MachineID = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay BootID = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u VSockCID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ChassisAssetTag = '...'; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; Whenever the hostname or other metadata is changed via the daemon, `PropertyChanged` signals are sent out to subscribed clients. Changing a hostname using this interface is authenticated via [polkit](https://www.freedesktop.org/software/polkit/docs/latest/). # Semantics The `StaticHostname` property exposes the "static" hostname configured in `/etc/hostname`. It is not always in sync with the current hostname as returned by the `gethostname(3)` system call. If no static hostname is configured this property will be the empty string. When `systemd(1)` or `systemd-hostnamed.service(8)` set the hostname, this static hostname *has the highest priority*. The `Hostname` property exposes the actual hostname configured in the kernel via `sethostname(2)`. It can be different from the static hostname. This property is never empty. The `PrettyHostname` property exposes the *pretty hostname* which is a free-form UTF-8 hostname for presentation to the user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync. E.g. when the former is `Lennart’s Computer` the latter should be `lennarts-computer`. If no pretty hostname is set this setting will be the empty string. Applications should then find a suitable fallback, such as the dynamic hostname. The `DefaultHostname` property exposes the default hostname (configured through `os-release(5)`, or a fallback set at compilation time). The `HostnameSource` property exposes the origin of the currently configured hostname. One of `static` (set from `/etc/hostname`), `transient` (a non-permanent hostname from an external source), `default` (the value from `os-release` or the compiled-in fallback). The `IconName` property exposes the *icon name* following the XDG icon naming spec. If not set, information such as the chassis type (see below) is used to find a suitable fallback icon name (i.e. `computer-laptop` vs. `computer-desktop` is picked based on the chassis information). If no such data is available, the empty string is returned. In that case an application should fall back to a replacement icon, for example `computer`. If this property is set to the empty string, the automatic fallback name selection is enabled again. The `Chassis` property exposes a *chassis type*, one of the currently defined chassis types: `desktop`, `laptop`, `server`, `tablet`, `handset`, as well as the special chassis types `vm` and `container` for virtualized systems. Note that in most cases the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if it could not be auto-detected. Set this property to the empty string to reenable the automatic detection of the chassis type from firmware information. The `Tags` property exposes a list of *machine tags*: short labels that may be used to classify and group machines for management purposes, for example to identify the role a machine plays in a deployment, the fleet or organizational unit it belongs to, or any other administrator-defined attribute. Each individual tag is 1…255 characters long and consists only of the ASCII alphanumeric characters, `-` and `.`. The tags are stored as a colon-separated list in the `TAGS=` field of `/etc/machine-info`, see `machine-info(5)` for details. If no tags are configured this property is the empty list. Note that `systemd-hostnamed` starts only on request and terminates after a short idle period. This effectively means that `PropertyChanged` messages are not sent out for changes made directly on the files (as in: administrator edits the files with vi). This is the intended behavior: manual configuration changes should require manual reloading. The transient (dynamic) hostname exposed by the `Hostname` property maps directly to the kernel hostname. This hostname should be assumed to be highly dynamic, and hence should be watched directly, without depending on `PropertyChanged` messages from `systemd-hostnamed`. To accomplish this, open `/proc/sys/kernel/hostname` and `poll(3)` for `SIGHUP` which is triggered by the kernel every time the hostname changes. Again: this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) hostname. Applications may read the hostname data directly if hostname change notifications are not necessary. Use `gethostname(2)`, `/etc/hostname` (possibly with per-distribution fallbacks), and `machine-info(5)` for that. For more information on these files and syscalls see the respective man pages. `KernelName`, `KernelRelease`, and `KernelVersion` expose the kernel name (e.g. `Linux`), release (e.g. `5.0.0-11`), and version (i.e. the build number, e.g. `#11`) as reported by `uname(2)`. `OperatingSystemPrettyName`, `OperatingSystemFancyName`, `OperatingSystemCPEName`, and `HomeURL` expose the `PRETTY_NAME=`, `FANCY_NAME=`, `CPE_NAME=` and `HOME_URL=` fields from `os-release(5)`. The purpose of those properties is to allow remote clients to access this information over D-Bus. Local clients can access the information directly. `MachineID` expose the 128bit machine ID, see `machine-id(5)` for details. `BootID` expose the 128bit boot ID, as per `/proc/sys/kernel/random/boot_id`. `VSockCID` exposes the system's local `AF_VSOCK` CID (Context Identifier, i.e. address) for the system, if one is available in the virtual machine environment. Set to `UINT32_MAX` otherwise. See `vsock(7)` for details. `OperatingSystemSupportEnd` exposes when the OS' vendor support ends, if this information is known. It's an unsigned 64bit value, in µs since the UNIX epoch, UTC. If this information is not known carries the value 2^64-1, i.e. `UINT64_MAX`. `OperatingSystemImageID` and `OperatingSystemImageVersion` expose the OS image name and version if available, or contain empty strings otherwise. This mostly corresponds to the `IMAGE_ID=` and `IMAGE_VERSION=` fields of the `os-release` file. `HardwareVendor`, `HardwareModel`, `HardwareSKU`, and `HardwareVersion` expose vendor information about the hardware of the system. The stock keeping unit (SKU) describes a distinct type of hardware for sale, purchase or inventory management. The SKU and version are only available if they deviate from the model and among each other. Thereby the version is more specific and only available if it differs from the model and SKU. If no such information can be determined these properties are set to empty strings. `FirmwareVersion` and `FirmwareVendor` expose information about the system's firmware, i.e. a version string and a vendor name. If no such information can be determined these properties are set to empty strings. `FirmwareDate` exposes the firmware build date, if that information is known. It's an unsigned 64bit value, in µs since the UNIX epoch, UTC. If not known `UNIT64_MAX`. `ChassisAssetTag` exposes an unique identifier of the system chassis. If this information is not known this property is set to an empty string. ## Methods `SetHostname()` sets the transient (dynamic) hostname, which is used if no static hostname is set. This value must be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces. An empty string will unset the transient hostname. `SetStaticHostname()` sets the static hostname which is exposed by the `StaticHostname` property. When called with an empty argument, the static configuration in `/etc/hostname` is removed. Since the static hostname has the highest priority, calling this function usually affects also the `Hostname` property and the effective hostname configured in the kernel. `SetPrettyHostname()` sets the pretty hostname which is exposed by the `PrettyHostname` property. `SetIconName()`, `SetChassis()`, `SetDeployment()`, and `SetLocation()` set the properties `IconName` (the name of the icon representing for the machine), `Chassis` (the machine form factor), `Deployment` (the system deployment environment), and `Location` (physical system location), respectively. `SetTags()` sets the machine tags exposed by the `Tags` property. It takes a list of strings, each of which must be a valid machine tag (1…255 ASCII alphanumeric characters, `-` and `.`). Passing an empty list removes the `TAGS=` field from `/etc/machine-info`. `AddAndRemoveTags()` incrementally updates the `Tags` property instead of replacing it. It takes two lists of machine tags: the tags in `add` are added to the current list, and any tags matching the patterns in `remove` are dropped from it (the resulting list is `(current ∪ add) \ remove`, sorted and deduplicated). A `key=value` tag in `add` replaces any assignment of the same key in the current list. This is useful when several independent agents each manage a subset of the tags without racing on a read-modify-write of the full list. Each tag to add must be a valid machine tag, as for `SetTags()`. `PrettyHostname`, `IconName`, `Chassis`, `Deployment`, `Location`, and `Tags` are stored in `/etc/machine-info`. See `machine-info(5)` for the semantics of those settings. `GetProductUUID()` returns the "product UUID" as exposed by the kernel based on DMI information in `/sys/class/dmi/id/product_uuid`. Reading the file directly requires root privileges, and this method allows access to unprivileged clients through the polkit framework. `GetHardwareSerial()` returns the "hardware serial" as exposed by the kernel based on DMI information. Reading the file directly requires root privileges, and this method allows access to unprivileged clients through the polkit framework. `Describe()` returns a JSON representation of all properties in one. `GetMachineInfo()` returns the value of the given field from `/etc/machine-info`. For well-known fields, this method reads values from the same internal cache used by the corresponding D-Bus property getters, but returns only the raw `/etc/machine-info` values (i.e. without property-level fallback logic such as DMI/chassis-based detection). Custom (non-standard) fields are read directly from the file. An error is returned if the field name is empty, invalid, or not set in the file. ## Security The `interactive` boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required. The polkit action for `SetHostname()` is org.freedesktop.hostname1.set-hostname. For `SetStaticHostname()` and `SetPrettyHostname()` it is org.freedesktop.hostname1.set-static-hostname. For `SetIconName()`, `SetChassis()`, `SetDeployment()`, `SetLocation()`, `SetTags()` and `AddAndRemoveTags()` it is org.freedesktop.hostname1.set-machine-info. # Recommendations Here are three examples that show how the pretty hostname and the icon name should be used: - When registering DNS-SD services: use the pretty hostname in the service name, and pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon on each service. This is especially useful for WebDAV applications or UPnP media sharing. - Set the bluetooth name to the pretty hostname. - When your file browser has a "Computer" icon, replace the name with the pretty hostname if set, and the icon with the icon name, if it is set. To properly handle name lookups with changing local hostnames without having to edit `/etc/hosts`, we recommend using `systemd-hostnamed` in combination with `nss-myhostname(8)`. Here are some recommendations to follow when generating a static (internet) hostname from a pretty name: - Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them, or replace them with `-`. - It's probably safer to not use any non-ASCII chars, even if DNS allows this in some way these days. In fact, restrict your charset to `a-zA-Z0-9` and `-`. Strip other chars, or try to replace them in some smart way with chars from this set, for example `ä` → `ae`, and use `-` as the replacement for all punctuation characters and whitespace. - Try to avoid creating repeated `-`, as well as `-` as the first or last char. - Limit the hostname to 63 chars, which is the length of a DNS label. - If after stripping special chars the empty string is the result, you can pass this as-is to `systemd-hostnamed` in which case it will automatically use a suitable fallback. - Uppercase characters should be replaced with their lowercase equivalents. Note that while `systemd-hostnamed` applies some checks to the hostname you pass they are much looser than the recommendations above. For example, `systemd-hostnamed` will also accept `_` in the hostname, but we recommend not using this to avoid clashes with DNS-SD service types. Also `systemd-hostnamed` allows longer hostnames, but because of the DNS label limitations, we recommend not making use of this. Here are a couple of example conversions: - `Lennart's PC` → `lennarts-pc` - `Müllers Computer` → `muellers-computer` - `Voran!` → `voran` - `Es war einmal ein Männlein` → `es-war-einmal-ein-maennlein` - `Jawoll. Ist doch wahr!` → `jawoll-ist-doch-wahr` - `レナート` → `localhost` - `...zack!!! zack!...` → `zack-zack` Of course, an already valid internet hostname label you enter and pass through this conversion should stay unmodified, so that users have direct control of it, if they want — by simply ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet name. # Examples
Introspect org.freedesktop.hostname1 on the bus
$ gdbus introspect --system \ --dest org.freedesktop.hostname1 \ --object-path /org/freedesktop/hostname1
# History ## The D-Bus API `FirmwareVersion` and `GetHardwareSerial()` were added in version 251. `OperatingSystemSupportEnd`, `FirmwareVendor`, and `FirmwareDate` were added in version 253. `MachineID`, `BootID` and `VSockCID` were added in version 256. `ChassisAssetTag`, `OperatingSystemImageID`, `OperatingSystemImageVersion`, `HardwareSKU`, and `HardwareVersion` were added in version 258. `OperatingSystemFancyName` was added in version 260. `GetMachineInfo()`, `Tags` and `SetTags()` were added in version 261. `AddAndRemoveTags()` was added in version 262. # See Also `systemd(1)`, `systemd-hostnamed.service(8)`, `hostnamectl(1)`, David Zeuthen's original Fedora [Feature page about xdg-hostname](https://fedoraproject.org/wiki/Features/BetterHostname) # org.freedesktop.import1 systemd org.freedesktop.import1 5 org.freedesktop.import1 The D-Bus interface of systemd-importd # Introduction `systemd-importd.service(8)` is a system service which may be used to import, export and download disk images. These images can be used by tools such as `systemd-nspawn(1)` to run local containers. The service is used as the backend for `importctl pull-raw`, `importctl pull-tar` and related commands. This page describes the D-Bus interface. Note that `systemd-importd.service(8)` is mostly a small companion service for `systemd-machined.service(8)`. Many operations to manipulate local container and VM images are hence available via the `systemd-machined` D-Bus API, c.f. `org.freedesktop.machine1(5)`. # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/import1 { interface org.freedesktop.import1.Manager { methods: ImportTar(in h fd, in s local_name, in b force, in b read_only, out u transfer_id, out o transfer_path); ImportTarEx(in h fd, in s local_name, in s class, in t flags, out u transfer_id, out o transfer_path); ImportRaw(in h fd, in s local_name, in b force, in b read_only, out u transfer_id, out o transfer_path); ImportRawEx(in h fd, in s local_name, in s class, in t flags, out u transfer_id, out o transfer_path); ImportFileSystem(in h fd, in s local_name, in b force, in b read_only, out u transfer_id, out o transfer_path); ImportFileSystemEx(in h fd, in s local_name, in s class, in t flags, out u transfer_id, out o transfer_path); ExportTar(in s local_name, in h fd, in s format, out u transfer_id, out o transfer_path); ExportTarEx(in s local_name, in s class, in h fd, in s format, in t flags, out u transfer_id, out o transfer_path); ExportRaw(in s local_name, in h fd, in s format, out u transfer_id, out o transfer_path); ExportRawEx(in s local_name, in s class, in h fd, in s format, in t flags, out u transfer_id, out o transfer_path); PullTar(in s url, in s local_name, in s verify_mode, in b force, out u transfer_id, out o transfer_path); PullTarEx(in s url, in s local_name, in s class, in s verify_mode, in t flags, out u transfer_id, out o transfer_path); PullRaw(in s url, in s local_name, in s verify_mode, in b force, out u transfer_id, out o transfer_path); PullRawEx(in s url, in s local_name, in s class, in s verify_mode, in t flags, out u transfer_id, out o transfer_path); PullOci(in s ref, in s local_name, in s class, in t flags, out u transfer_id, out o transfer_path); ListTransfers(out a(usssdo) transfers); ListTransfersEx(in s class, in t flags, out a(ussssdo) transfers); CancelTransfer(in u transfer_id); ListImages(in s class, in t flags, out a(ssssbtttttt) images); signals: TransferNew(u transfer_id, o transfer_path); TransferRemoved(u transfer_id, o transfer_path, s result); }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `ImportTar()`/`ImportTarEx()` and `ImportRaw()`/`ImportRawEx()` import a disk image and place it into the image directory. The first argument should be a file descriptor (opened for reading) referring to the tar or raw file to import. It should reference a file on disk, a pipe or a socket. When `ImportTar()`/`ImportTarEx()` is used the file descriptor should refer to a tar file, optionally compressed with `gzip(1)`, `zstd(1)`, `bzip2(1)`, or `xz(1)`. `systemd-importd` will detect the used compression scheme (if any) automatically. When `ImportRaw()`/`ImportRawEx()` is used the file descriptor should refer to a raw or qcow2 disk image containing an MBR or GPT disk label, also optionally compressed with gzip, zstd, bzip2 or xz. In either case, if the file is specified as a file descriptor on disk, progress information is generated for the import operation (as in that case we know the total size on disk). If a socket or pipe is specified, progress information is not available. The file descriptor argument is followed by a local name for the image. This should be a name suitable as a hostname and will be used to name the imported image below `/var/lib/machines/`. A tar import is placed as a directory tree or a `btrfs(8)` subvolume below the image directory under the specified name with no suffix appended. A raw import is placed as a file in the image directory with the `.raw` suffix appended. In case of `ImportTar()`/`ImportRaw()`, if the `force` argument is true, any pre-existing image with the same name is removed before starting the operation. Otherwise, the operation fails if an image with the same name already exists. The `read_only` argument controls whether to create a writable or read-only image. In case of `ImportTarEx()`/`ImportRawEx()` these boolean flags are provided via a 64bit flags parameter instead, with bit 0 mapping to the `force` parameter, and bit 1 mapping to `read_only`. The `class` parameter specifies the image class, and takes one of `machine`, `portable`, `sysext`, `confext`. All four methods return immediately after starting the import, with the import transfer ongoing. They return a pair of transfer identifier and object path, which may be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a simple numeric identifier, the object path references an org.freedesktop.import1.Transfer object, see below. Listen for a `TransferRemoved()` signal for the transfer ID in order to detect when a transfer is complete. The returned transfer object is useful to determine the current progress or log output of the ongoing import operation. `ExportTar()`/`ExportTarEx()` and `ExportRaw()`/`ExportRaw()` implement the reverse operation, and may be used to export a system image in order to place it in a tar or raw image. They take the machine name to export as their first parameter, followed by a file descriptor (opened for writing) where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The third argument specifies in which compression format to write the image. It takes one of `uncompressed`, `xz`, `bzip2`, `gzip` or `zstd`, depending on which compression scheme is required. The image written to the specified file descriptor will be a tar file in case of `ExportTar()`/`ExportTarEx()` or a raw disk image in case of `ExportRaw()`/`ExportRawEx()`. Note that currently raw disk images may not be exported as tar files, and vice versa. This restriction might be lifted eventually. The method returns a transfer identifier and object path for cancelling or tracking the export operation, similarly to `ImportTar()`/`ImportTarEx()` or `ImportRaw()`/`ImportRawEx()` as described above. `ExportTarEx()`/`ExportRawEx()` expect the image class as additional parameter, as well as a 64bit flags parameter that currently must be specified as zero. `PullTar()`/`PullTarEx()` and `PullRaw()`/`PullRawEx()` may be used to download, verify and import a system image from a URL. They take a URL argument which should point to a tar or raw file on the `http://` or `https://` protocols, possibly compressed with xz, bzip2, gzip or zstd. The second argument is a local name for the image. It should be suitable as a hostname, similarly to the matching argument of the `ImportTar()`/`ImportTarEx()` and `ImportRaw()`/`ImportRawEx()` methods above. The third argument indicates the verification mode for the image. It may be one of `no`, `checksum`, `signature`. `no` turns off any kind of verification of the image; `checksum` looks for a `SHA256SUM` file next to the downloaded image and verifies any SHA256 hash value in that file against the image; `signature` does the same but also tries to authenticate the `SHA256SUM` file via `gpg(8)` first. In case of `PullTar()`/`PullRaw()` the last argument indicates whether to replace a possibly pre-existing image with the same local name (if `true`), or whether to fail (if `false`). In case of `PullTarEx()`/`PullRawEx()` the last argument is a 64bit flags parameter, where bit 0 controls the `force` flag, bit 1 is a `read_only` flag that controls whether the created image shall be marked read-only, and bit 2 is a `keep_download` flag that indicates whether a pristine, read-only copy of the downloaded image shell be kept, in addition for the local copy of the image. The `…_Ex()` variants also expect an image class string (as above). Like the import and export calls above, these calls return a pair of transfer identifier and object path for the ongoing download. `PullOci()` is similar to `PullTarEx()` or `PullRawEx()` and may be used to download and import an OCI container image from an OCI registry. It takes an OCI container reference as argument. The second argument is a local name for the image (which will be generated as `systemd.mstack(7)` directory referencing the OCI layers). It should be suitable as a hostname, similarly to the matching argument of the `PullTar()`/`PullTarEx()` and `PullRaw()`/`PullRawEx()` methods above. The last argument is a 64bit flags parameter, where bit 0 controls the `force` flag, bit 1 is a `read_only` flag that controls whether the created image shall be marked read-only. Like the pull calls above, this call return a pair of transfer identifier and object path for the ongoing download. `ImportFileSystem()`/`ImportFileSystemEx()` are similar to `ImportTar()`/`ImportTarEx()` but import a directory tree. The first argument must refer to a directory file descriptor for the source hierarchy to import. `ListTransfers()`/`ListTransfersEx()` return a list of ongoing import, export or download operations as created with the six calls described above. They return an array of structures which consist of the numeric transfer identifier, a string indicating the operation (one of `import-tar`, `import-raw`, `export-tar`, `export-raw`, `pull-tar` or `pull-raw`), a string describing the remote file (in case of download operations this is the source URL, in case of import/export operations this is a short string describing the file descriptor passed in), a string with the local machine image name, the image class (only in case of `ListTransfersEx()`; one of `machine`, `portable`, `sysext`, `confext`), a progress value between 0.0 (for 0%) and 1.0 (for 100%), as well as the transfer object path. `CancelTransfer()` may be used to cancel an ongoing import, export or download operation. Simply specify the transfer identifier to cancel the ongoing operation. `ListImages()` returns a list of currently installed images. It takes a image class string and a flags parameter. The image class is either the empty string or specifies one of the four image classes, by which it will then filter. The flags parameter must be zero at this time. It returns an array of items, each describing one image. The item fields are in order: the image class, the local image name, the image type, the image path, the read-only flag, the creation and modification times (in microseconds since the UNIX epoch), as well as the current disk usage in bytes (both overall, and exclusive), as well as any size limit in bytes set on the image (both overall and exclusive). ## Signals The `TransferNew()` signal is generated each time a new transfer is started with the import, export or download calls described above. It carries the transfer ID and object path that have just been created. The `TransferRemoved()` signal is sent each time a transfer finishes, is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating the result of the operation, which is one of `done` (on success), `canceled` or `failed`. # The Transfer Object node /org/freedesktop/import1/transfer/_1 { interface org.freedesktop.import1.Transfer { methods: Cancel(); signals: LogMessage(u priority, s line); ProgressUpdate(d progress); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u Id = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Local = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Remote = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Type = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Verify = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly d Progress = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods The `Cancel()` method may be used to cancel the transfer. It takes no parameters. This method is pretty much equivalent to the `CancelTransfer()` method on the Manager interface (see above), but is exposed on the Transfer object itself instead of taking a transfer ID. ## Properties The `Id` property exposes the numeric transfer ID of the transfer object. The `Local`, `Remote` and `Type` properties expose the local container name of this transfer, the remote source (in case of download: the URL, in case of import/export: a string describing the file descriptor passed in), and the type of operation (see the Manager's `ListTransfer()` method above for an explanation of the possible values). The `Verify` property exposes the selected verification setting and is only defined for download operations (see above). The `Progress` property exposes the current progress of the transfer as a value between 0.0 and 1.0. To show a progress bar on screen we recommend to query this value in regular intervals, for example every 500 ms or so. ## Signals The `LogMessage()` signal is emitted for log messages generated by a transfer. It carries a pair of syslog log level integer and log string. The `ProgressUpdate()` signal is emitted in regular intervals when new download progress information is available for a transfer. It carries a double precision floating pointer number between 0.0 and 1.0 indicating the transfer progress. # Examples
Introspect org.freedesktop.import1.Manager on the bus
$ gdbus introspect --system \ --dest org.freedesktop.import1 \ --object-path /org/freedesktop/import1
Introspect org.freedesktop.import1.Transfer on the bus
$ gdbus introspect --system \ --dest org.freedesktop.import1 \ --object-path /org/freedesktop/import1/transfer/_1
# History ## The Manager Object `ImportTarEx()`, `ImportRawEx()`, `ImportFileSystemEx()`, `ExportTarEx()`, `ExportRawEx()`, `PullTarEx()`, `PullRawEx()`, `ListTransfersEx()`, `ListImages()` were added in version 256. `PullOci()` was added in version 260. ## Transfer Objects `ProgressUpdate()` was added in version 256. # See Also `systemd(1)`, `systemd-importd.service(8)`, `importctl(1)` # org.freedesktop.locale1 systemd org.freedesktop.locale1 5 org.freedesktop.locale1 The D-Bus interface of systemd-localed # Introduction `systemd-localed.service(8)` is a system service that can be used to control the system locale and keyboard mapping from user programs. This page describes the D-Bus interface. # The D-Bus API The service exposes the following interfaces on the bus: node /org/freedesktop/locale1 { interface org.freedesktop.locale1 { methods: SetLocale(in as locale, in b interactive); SetVConsoleKeyboard(in s keymap, in s keymap_toggle, in b convert, in b interactive); SetX11Keyboard(in s layout, in s model, in s variant, in s options, in b convert, in b interactive); properties: readonly as Locale = ['...', ...]; readonly s X11Layout = '...'; readonly s X11Model = '...'; readonly s X11Variant = '...'; readonly s X11Options = '...'; readonly s VConsoleKeymap = '...'; readonly s VConsoleKeymapToggle = '...'; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods If you set a new system locale all old system locale settings will be dropped and the new settings will be saved to disk. The locale will also be passed to the system manager, and subsequently started daemons will inherit the new system locale. Note that already running daemons will not learn about the new value. The `SetVConsoleKeyboard()` method may be used to set the key mapping for the virtual console. Similarly, `SetX11Keyboard()` may be used to set the default key mapping of any X11 servers. Note that `SetVConsoleKeyboard()` instantly applies the new key mapping to the console, while `SetX11Keyboard()` simply sets a default that may be used by later sessions. The boolean argument `convert` may be set to optionally convert the console keyboard configuration to X11 keyboard mappings and vice versa. If true and `SetVConsoleKeyboard()` is used, the nearest X11 keyboard setting for the chosen console setting is set. If true and `SetX11Keyboard()` is used, the nearest console keyboard setting for the chosen X11 setting is set. Hence, it is usually sufficient to call only one of the two functions. For graphical UIs that need to set the system keyboard mapping simply invoke `SetX11Keyboard()`, set `convert=true` and ignore `SetVConsoleKeyboard()`. Use the empty string for the keymap parameters you wish not to set. The `interactive` boolean parameters can be used to control whether [polkit](https://www.freedesktop.org/software/polkit/docs/latest/) should interactively ask the user for authentication credentials if required. ## Signals Whenever the system locale or keymap is changed via the daemon, `PropertyChanged` signals are sent out to clients which have subscribed. ## Properties The system locale is shown in the `Locale` property. It is an array containing environment-variable-assignment-like strings. The following strings are known: `LANG=`, `LC_CTYPE=`, `LC_NUMERIC=`, `LC_TIME=`, `LC_COLLATE=`, `LC_MONETARY=`, `LC_MESSAGES=`, `LC_PAPER=`, `LC_NAME=`, `LC_ADDRESS=`, `LC_TELEPHONE=`, `LC_MEASUREMENT=`, `LC_IDENTIFICATION=`. The `X11Layout`, `X11Model`, `X11Variant`, and `X11Options` properties show values configurable with `SetX11Keyboard()` described above (or `SetVConsoleKeyboard()` with `convert=true`). The `VConsoleKeymap` and `VConsoleKeymapToggle` properties show values configurable with `SetVConsoleKeyboard()` (or `SetX11Keyboard()` with `convert=true`). ## Security Changing the system locale or keymap using this interface is authenticated via polkit. The polkit action for `SetLocale()` is `org.freedesktop.locale1.set-locale`. The polkit action for `SetX11Keyboard()` and `SetVConsoleKeyboard()` is `org.freedesktop.locale1.set-keyboard`. # Examples
Introspect org.freedesktop.locale1 on the bus
$ gdbus introspect --system \ --dest org.freedesktop.locale1 \ --object-path /org/freedesktop/locale1
# Versioning These D-Bus interfaces follow [ the usual interface versioning guidelines](https://0pointer.de/blog/projects/versioning-dbus.html). # See Also `systemd(1)`, `systemd-localed.service(8)`, `localectl(1)` # org.freedesktop.login1 systemd org.freedesktop.login1 5 org.freedesktop.login1 The D-Bus interface of systemd-logind # Introduction `systemd-logind.service(8)` is a system service that keeps track of user logins and seats. The daemon provides both a C library interface as well as a D-Bus interface. The library interface may be used to introspect and watch the state of user logins and seats. The bus interface provides the same functionality but in addition may also be used to make changes to the system state. For more information please consult `sd-login(3)`. # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/login1 { interface org.freedesktop.login1.Manager { methods: GetSession(in s session_id, out o object_path); GetSessionByPID(in u pid, out o object_path); GetUser(in u uid, out o object_path); GetUserByPID(in u pid, out o object_path); GetSeat(in s seat_id, out o object_path); ListSessions(out a(susso) sessions); ListSessionsEx(out a(sussussbto) sessions); ListUsers(out a(uso) users); ListSeats(out a(so) seats); ListInhibitors(out a(ssssuu) inhibitors); @org.freedesktop.systemd1.Privileged("true") CreateSession(in u uid, in u pid, in s service, in s type, in s class, in s desktop, in s seat_id, in u vtnr, in s tty, in s display, in b remote, in s remote_user, in s remote_host, in a(sv) properties, out s session_id, out o object_path, out s runtime_path, out h fifo_fd, out u uid, out s seat_id, out u vtnr, out b existing); @org.freedesktop.systemd1.Privileged("true") CreateSessionWithPIDFD(in u uid, in h pidfd, in s service, in s type, in s class, in s desktop, in s seat_id, in u vtnr, in s tty, in s display, in b remote, in s remote_user, in s remote_host, in t flags, in a(sv) properties, out s session_id, out o object_path, out s runtime_path, out h fifo_fd, out u uid, out s seat_id, out u vtnr, out b existing); ReleaseSession(in s session_id); ActivateSession(in s session_id); ActivateSessionOnSeat(in s session_id, in s seat_id); LockSession(in s session_id); UnlockSession(in s session_id); LockSessions(); UnlockSessions(); KillSession(in s session_id, in s whom, in i signal_number); KillUser(in u uid, in i signal_number); TerminateSession(in s session_id); TerminateUser(in u uid); TerminateSeat(in s seat_id); SetUserLinger(in u uid, in b enable, in b interactive); AttachDevice(in s seat_id, in s sysfs_path, in b interactive); FlushDevices(in b interactive); PowerOff(in b interactive); PowerOffWithFlags(in t flags); Reboot(in b interactive); RebootWithFlags(in t flags); Halt(in b interactive); HaltWithFlags(in t flags); Suspend(in b interactive); SuspendWithFlags(in t flags); Hibernate(in b interactive); HibernateWithFlags(in t flags); HybridSleep(in b interactive); HybridSleepWithFlags(in t flags); SuspendThenHibernate(in b interactive); SuspendThenHibernateWithFlags(in t flags); Sleep(in t flags); CanPowerOff(out s result); CanReboot(out s result); CanHalt(out s result); CanSuspend(out s result); CanHibernate(out s result); CanHybridSleep(out s result); CanSuspendThenHibernate(out s result); CanSleep(out s result); ScheduleShutdown(in s type, in t usec); CancelScheduledShutdown(out b cancelled); Inhibit(in s what, in s who, in s why, in s mode, out h pipe_fd); CanRebootParameter(out s result); SetRebootParameter(in s parameter); CanRebootToFirmwareSetup(out s result); SetRebootToFirmwareSetup(in b enable); CanRebootToBootLoaderMenu(out s result); SetRebootToBootLoaderMenu(in t timeout); CanRebootToBootLoaderEntry(out s result); SetRebootToBootLoaderEntry(in s boot_loader_entry); SetWallMessage(in s wall_message, in b enable); signals: SecureAttentionKey(s seat_id, o object_path); SessionNew(s session_id, o object_path); SessionRemoved(s session_id, o object_path); UserNew(u uid, o object_path); UserRemoved(u uid, o object_path); SeatNew(s seat_id, o object_path); SeatRemoved(s seat_id, o object_path); PrepareForShutdown(b start); PrepareForShutdownWithMetadata(b start, a{sv} metadata); PrepareForSleep(b start); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite b EnableWallMessages = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite s WallMessage = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u NAutoVTs = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as KillOnlyUsers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as KillExcludeUsers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b KillUserProcesses = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s RebootParameter = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b RebootToFirmwareSetup = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t RebootToBootLoaderMenu = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s RebootToBootLoaderEntry = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as BootLoaderEntries = ['...', ...]; readonly b IdleHint = ...; readonly t IdleSinceHint = ...; readonly t IdleSinceHintMonotonic = ...; readonly s BlockInhibited = '...'; readonly s BlockWeakInhibited = '...'; readonly s DelayInhibited = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InhibitDelayMaxUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UserStopDelayUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SleepOperation = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandlePowerKey = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandlePowerKeyLongPress = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleRebootKey = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleRebootKeyLongPress = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleSuspendKey = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleSuspendKeyLongPress = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleHibernateKey = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleHibernateKeyLongPress = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleLidSwitch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleLidSwitchExternalPower = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleLidSwitchDocked = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleSecureAttentionKey = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t HoldoffTimeoutUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IdleAction = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t IdleActionUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b PreparingForShutdown = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a{sv} PreparingForShutdownWithMetadata = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b PreparingForSleep = ...; readonly (st) ScheduledShutdown = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s DesignatedMaintenanceTime = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b Docked = ...; readonly b LidClosed = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b OnExternalPower = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RemoveIPC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RuntimeDirectorySize = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RuntimeDirectoryInodesMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InhibitorsMax = ...; readonly t NCurrentInhibitors = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t SessionsMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t NCurrentSessions = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t StopIdleSessionUSec = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `GetSession()` may be used to get the session object path for the session with the specified ID. Similarly, `GetUser()` and `GetSeat()` get the user and seat objects, respectively. `GetSessionByPID()` and `GetUserByPID()` get the session/user object the specified PID belongs to if there is any. `ListSessions()` returns an array of all current sessions. The structures in the array consist of the following fields: `session id`, `user id`, `user name`, `seat id`, and `session object path`. If a session does not have a seat attached, the seat id field will be an empty string. `ListSessionsEx()` returns an array of all current sessions with more metadata than `ListSessions()`. The structures in the array consist of the following fields: `session id`, `user id`, `user name`, `seat id`, `leader pid`, `session class`, `tty name`, `idle hint`, `idle hint monotonic timestamp`, and `session object path`. `tty` and `seat id` fields could be empty, if the session has no associated tty or session has no seat attached, respectively. `ListUsers()` returns an array of all currently logged in users. The structures in the array consist of the following fields: user id, user name, user object path. `ListSeats()` returns an array of all currently available seats. The structure in the array consists of the following fields: seat id, seat object path. `ListInhibitors()` lists all currently active inhibitors. It returns an array of structures consisting of `what`, `who`, `why`, `mode`, `uid` (user ID), and `pid` (process ID). `CreateSession()`, `CreateSessionWithPIDFD()`, and `ReleaseSession()` may be used to open or close login sessions. These calls should *never* be invoked directly by clients. Creating/closing sessions is exclusively the job of PAM and its `pam_systemd(8)` module. `ActivateSession()` brings the session with the specified ID into the foreground. `ActivateSessionOnSeat()` does the same, but only if the seat id matches. `LockSession()` asks the session with the specified ID to activate the screen lock. `UnlockSession()` asks the session with the specified ID to remove an active screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from the respective session object which session managers are supposed to listen on. `LockSessions()` asks all sessions to activate their screen locks. This may be used to lock access to the entire machine in one action. Similarly, `UnlockSessions()` asks all sessions to deactivate their screen locks. `KillSession()` may be used to send a Unix signal to one or all processes of a session. As arguments it takes the session id, either the string `leader` or `all` and a signal number. If `leader` is passed only the session `leader` is killed. If `all` is passed all processes of the session are killed. `KillUser()` may be used to send a Unix signal to all processes of a user. As arguments it takes the user id and a signal number. `TerminateSession()`, `TerminateUser()`, `TerminateSeat()` may be used to forcibly terminate one specific session, all processes of a user, and all sessions attached to a specific seat, respectively. The session, user, and seat are identified by their respective IDs. `SetUserLinger()` enables or disables user lingering. If enabled, the runtime directory of a user is kept around and they may continue to run processes while logged out. If disabled, the runtime directory goes away as soon as they log out. `SetUserLinger()` expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the [polkit](https://www.freedesktop.org/software/polkit/docs/latest/) authorization interactivity (see below). Note that the user linger state is persistently stored on disk. `AttachDevice()` may be used to assign a specific device to a specific seat. The device is identified by its `/sys/` path and must be eligible for seat assignments. `AttachDevice()` takes three arguments: the seat id, the sysfs path, and a boolean for controlling polkit interactivity (see below). Device assignments are persistently stored on disk. To create a new seat, simply specify a previously unused seat id. For more information about the seat assignment logic see `sd-login(3)`. `FlushDevices()` removes all explicit seat assignments for devices, resetting all assignments to the automatic defaults. The only argument it takes is the polkit interactivity boolean (see below). `PowerOff()`, `Reboot()`, `Halt()`, `Suspend()`, and `Hibernate()` result in the system being powered off, rebooted, halted (shut down without turning off power), suspended (the system state is saved to RAM and the CPU is turned off), or hibernated (the system state is saved to disk and the machine is powered down). `HybridSleep()` results in the system entering a hybrid-sleep mode, i.e. the system is both hibernated and suspended. `SuspendThenHibernate()` results in the system being suspended, then later woken using an RTC timer and hibernated. The only argument is the polkit interactivity boolean `interactive` (see below). The main purpose of these calls is that they enforce polkit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged users. They also enforce inhibition locks for non-privileged users. `Sleep()` automatically selects the most suitable sleep operation supported by the machine. The candidate sleep operations to check for support can be configured through `SleepOperation=` setting in `logind.conf(5)`. UIs should expose these calls as the primary mechanism to poweroff/reboot/suspend/hibernate the machine. Methods `PowerOffWithFlags()`, `RebootWithFlags()`, `HaltWithFlags()`, `SuspendWithFlags()`, `HibernateWithFlags()`, `HybridSleepWithFlags()`, `SuspendThenHibernateWithFlags()`, and `Sleep()` take `flags` to allow for extendability, defined as follows: #define SD_LOGIND_ROOT_CHECK_INHIBITORS (UINT64_C(1) << 0) #define SD_LOGIND_KEXEC_REBOOT (UINT64_C(1) << 1) #define SD_LOGIND_SOFT_REBOOT (UINT64_C(1) << 2) #define SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP (UINT64_C(1) << 3) #define SD_LOGIND_SKIP_INHIBITORS (UINT64_C(1) << 4) When the `flags` is 0 then these methods behave just like the versions without flags. Since systemd version 257 inhibitors of type `block` are enforced on operations requested by both privileged and unprivileged users. Previously they were honoured only by unprivileged users, excluding the user owning the inhibitor. The latter behaviour is now available through the `block-weak` inhibitor lock type. `SD_LOGIND_ROOT_CHECK_INHIBITORS` (0x01) makes `block-weak` locks behave like regular `block` locks, i.e. ensures they are honoured for any user. A flag `SD_LOGIND_SKIP_INHIBITORS` (0x10) can be specified to bypass both `block` and `block-weak` inhibitors (it has no effect on `delay` inhibitors). When `SD_LOGIND_KEXEC_REBOOT` (0x02) is set, then `RebootWithFlags()` performs a kexec reboot if kexec kernel is loaded. When `SD_LOGIND_SOFT_REBOOT` (0x04) is set, or `SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP` (0x08) is set and a new root file system has been set up on `/run/nextroot/`, then `RebootWithFlags()` performs a userspace reboot only. `SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP` and `SD_LOGIND_KEXEC_REBOOT` can be combined, with soft-reboot having precedence. `SetRebootParameter()` sets a parameter for a subsequent reboot operation. See the description of `reboot` in `systemctl(1)` and `reboot(2)` for more information. `SetRebootToFirmwareSetup()`, `SetRebootToBootLoaderMenu()`, and `SetRebootToBootLoaderEntry()` configure the action to be taken from the boot loader after a reboot: respectively entering firmware setup mode, the boot loader menu, or a specific boot loader entry. See `systemctl(1)` for the corresponding command line interface. `CanPowerOff()`, `CanReboot()`, `CanHalt()`, `CanSuspend()`, `CanHibernate()`, `CanHybridSleep()`, `CanSuspendThenHibernate()`, `CanSleep()`, `CanRebootParameter()`, `CanRebootToFirmwareSetup()`, `CanRebootToBootLoaderMenu()`, and `CanRebootToBootLoaderEntry()` test whether the system supports the respective operation and whether the calling user is allowed to execute it. Returns one of `na`, `yes`, `no`, `challenge`, `inhibited`, `inhibitor-blocked`, and `challenge-inhibitor-blocked`. If `na` is returned, the operation is not available because hardware, kernel, or drivers do not support it. If `yes` is returned, the operation is supported and the user may execute the operation without further authentication. If `no` is returned, the operation is available but the user is not allowed to execute the operation. If `challenge` is returned, the operation is available but only after authorization. If `inhibited` is returned, the operation is normally available without authorization but is currently inhibited. The operation is available only if inhibitors are ignored and after authorization. If `inhibitor-blocked` is returned, the operation is normally available without authorization but is currently inhibited. While the inhibitor remains active, the user is not allowed to execute the operation. `challenge-inhibitor-blocked` is similar: the operation is normally available after authorization but a held inhibitor disallows the user from executing the operation. `ScheduleShutdown()` schedules a shutdown operation `type` at time `usec` in microseconds since the UNIX epoch. Alternatively, if `usec` `UINT64_MAX` and a maintenance window is configured, `systemd-logind` will use the next time of the maintenance window instead. `type` can be one of `poweroff`, `dry-poweroff`, `reboot`, `dry-reboot`, `halt`, and `dry-halt`. (The `dry-` variants do not actually execute the shutdown action.) `CancelScheduledShutdown()` cancels a scheduled shutdown. The output parameter `cancelled` is true if a shutdown operation was scheduled. Note that `usec` is a lower bound only: the shutdown operation is executed as soon as possible, but not before the specified time. A timestamp in the past is not an error, it simply means the operation is executed immediately. This is important, since a request to shut down immediately, or a very short time into the future, typically already refers to the past by the time it is processed. `SetWallMessage()` sets the wall message (the message that will be sent out to all terminals and stored in a `utmp(5)` record) for a subsequent scheduled shutdown operation. The parameter `wall_message` specifies the shutdown reason (and may be empty) which will be included in the shutdown message. The parameter `enable` specifies whether to print a wall message on shutdown. `Inhibit()` creates an inhibition lock. It takes four parameters: `what`, `who`, `why`, and `mode`. `what` is one or more of `shutdown`, `sleep`, `idle`, `handle-power-key`, `handle-suspend-key`, `handle-hibernate-key`, `handle-lid-switch`, separated by colons, for inhibiting poweroff/reboot, suspend/hibernate, the automatic idle logic, or hardware key handling. `who` should be a short human-readable string identifying the application taking the lock. `why` should be a short human-readable string identifying the reason why the lock is taken. Finally, `mode` is either `block` or `delay` which encodes whether the inhibit shall be consider mandatory or whether it should just delay the operation to a certain maximum time, while the `block-weak` and variants will create an inhibitor that is automatically ignored in some circumstances. The method returns a file descriptor. The lock is released the moment this file descriptor and all its duplicates are closed. For more information on the inhibition logic see [Inhibitor Locks](https://systemd.io/INHIBITOR_LOCKS). ## Signals Whenever the inhibition state or idle hint changes, `PropertyChanged` signals are sent out to clients which have subscribed. The `SecureAttentionKey()` signal is sent when the user presses Ctrl+Alt+Shift+Esc to request the login manager to display the greeter, for instance in the case of a deadlocked compositor. The `SessionNew()`, `SessionRemoved()`, `UserNew()`, `UserRemoved()`, `SeatNew()`, and `SeatRemoved()` signals are sent each time a session is created or removed, a user logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object path. The `PrepareForShutdown()`, `PrepareForShutdownWithMetadata()`, and `PrepareForSleep()` signals are sent right before (with the argument `true`) or after (with the argument `false`) the system goes down for reboot/poweroff and suspend/hibernate, respectively. This may be used by applications to save data on disk, release memory, or do other jobs that should be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After completion of this work they should release their inhibition locks in order to not delay the operation any further. For more information see [Inhibitor Locks](https://systemd.io/INHIBITOR_LOCKS). The `PrepareForShutdownWithMetadata()` signal additionally sends a list of key/value pair metadata fields. Currently it sends a `type` string which defines the type of shutdown. The type can be one of `power-off`, `reboot`, `halt`, `kexec` or `soft-reboot`. This signal is sent first, followed by `PrepareForShutdown()` (for backward compatibility). ## Properties Most properties simply reflect the configuration, see `logind.conf(5)`. This includes: `NAutoVTs`, `KillOnlyUsers`, `KillExcludeUsers`, `KillUserProcesses`, `IdleAction`, `InhibitDelayMaxUSec`, `InhibitorsMax`, `UserStopDelayUSec`, `HandlePowerKey`, `HandleSuspendKey`, `HandleHibernateKey`, `HandleLidSwitch`, `HandleLidSwitchExternalPower`, `HandleLidSwitchDocked`, `IdleActionUSec`, `HoldoffTimeoutUSec`, `RemoveIPC`, `RuntimeDirectorySize`, `RuntimeDirectoryInodesMax`, `InhibitorsMax`, and `SessionsMax`. The `IdleHint` property reflects the idle hint state of the system. If the system is idle it might get into automatic suspend or shutdown depending on the configuration. `IdleSinceHint` and `IdleSinceHintMonotonic` encode the timestamps of the last change of the idle hint boolean, in `CLOCK_REALTIME` and `CLOCK_MONOTONIC` timestamps, respectively, in microseconds since the epoch. The `BlockInhibited`, `BlockWeakInhibited`, and `DelayInhibited` properties encode the currently active locks of the respective modes. They are colon separated lists of `shutdown`, `sleep`, and `idle` (see above). `NCurrentSessions` and `NCurrentInhibitors` contain the number of currently registered sessions and inhibitors. The `BootLoaderEntries` property contains a list of boot loader entries. This includes boot loader entries defined in configuration and any additional loader entries reported by the boot loader. See `systemd-boot(7)` for more information. The `PreparingForShutdown` and `PreparingForSleep` boolean properties are true during the interval between the two `PrepareForShutdown()` and `PrepareForSleep()` signals respectively. The `PreparingForShutdownWithMetadata` property provides a list of key/value pair metadata fields. Currently it lists a `preparing` boolean that corresponds to the `PreparingForShutdown` property, and, if a shutdown is being prepared, it will also contain a `type` string which defines the type of shutdown. The type can be one of `power-off`, `reboot`, `halt`, `kexec` or `soft-reboot`. Note that these properties do not send out `PropertyChanged` signals. The `RebootParameter` property shows the value set with the `SetRebootParameter()` method described above. `ScheduledShutdown` shows the value pair set with the `ScheduleShutdown()` method described above. `RebootToFirmwareSetup`, `RebootToBootLoaderMenu`, and `RebootToBootLoaderEntry` are true when the resprective post-reboot operation was selected with `SetRebootToFirmwareSetup()`, `SetRebootToBootLoaderMenu()`, or `SetRebootToBootLoaderEntry()`. The `WallMessage` and `EnableWallMessages` properties reflect the shutdown reason and wall message enablement switch which can be set with the `SetWallMessage()` method described above. `Docked` is true if the machine is connected to a dock. `LidClosed` is true when the lid (of a laptop) is closed. `OnExternalPower` is true when the machine is connected to an external power supply. ## Security A number of operations are protected via the polkit privilege system. `SetUserLinger()` requires the org.freedesktop.login1.set-user-linger privilege. `AttachDevice()` requires org.freedesktop.login1.attach-device and `FlushDevices()` requires org.freedesktop.login1.flush-devices. `PowerOff()`, `Reboot()`, `Halt()`, `Suspend()`, `Hibernate()` require org.freedesktop.login1.power-off, org.freedesktop.login1.power-off-multiple-sessions, org.freedesktop.login1.power-off-ignore-inhibit, org.freedesktop.login1.reboot, org.freedesktop.login1.reboot-multiple-sessions, org.freedesktop.login1.reboot-ignore-inhibit, org.freedesktop.login1.halt, org.freedesktop.login1.halt-multiple-sessions, org.freedesktop.login1.halt-ignore-inhibit, org.freedesktop.login1.suspend, org.freedesktop.login1.suspend-multiple-sessions, org.freedesktop.login1.suspend-ignore-inhibit, org.freedesktop.login1.hibernate, org.freedesktop.login1.hibernate-multiple-sessions, org.freedesktop.login1.hibernate-ignore-inhibit, respectively depending on whether there are other sessions around or active inhibits are present. `HybridSleep()` and `SuspendThenHibernate()` use the same privileges as `Hibernate()`. `Sleep()` uses the inhibits of the auto-selected sleep operation. `SetRebootParameter()` requires org.freedesktop.login1.set-reboot-parameter. `SetRebootToFirmwareSetup()` requires org.freedesktop.login1.set-reboot-to-firmware-setup. `SetRebootToBootLoaderMenu()` requires org.freedesktop.login1.set-reboot-to-boot-loader-menu. `SetRebootToBootLoaderEntry()` requires org.freedesktop.login1.set-reboot-to-boot-loader-entry. `ScheduleShutdown()` and `CancelScheduledShutdown()` require the same privileges (listed above) as the immediate poweroff/reboot/halt operations. `Inhibit()` is protected via one of org.freedesktop.login1.inhibit-block-shutdown, org.freedesktop.login1.inhibit-delay-shutdown, org.freedesktop.login1.inhibit-block-sleep, org.freedesktop.login1.inhibit-delay-sleep, org.freedesktop.login1.inhibit-block-idle, org.freedesktop.login1.inhibit-handle-power-key, org.freedesktop.login1.inhibit-handle-suspend-key, org.freedesktop.login1.inhibit-handle-hibernate-key, org.freedesktop.login1.inhibit-handle-lid-switch depending on the lock type and mode taken. The `interactive` boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required. # Seat Objects node /org/freedesktop/login1/seat/seat0 { interface org.freedesktop.login1.Seat { methods: Terminate(); ActivateSession(in s session_id); SwitchTo(in u vtnr); SwitchToNext(); SwitchToPrevious(); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Id = '...'; readonly (so) ActiveSession = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CanTTY = ...; readonly b CanGraphical = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(so) Sessions = [...]; readonly b IdleHint = ...; readonly t IdleSinceHint = ...; readonly t IdleSinceHintMonotonic = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `Terminate()` and `ActivateSession()` work similarly to `TerminateSeat()` and `ActivationSessionOnSeat()` on the Manager object. `SwitchTo()` switches to the session on the virtual terminal `vtnr`. `SwitchToNext()` and `SwitchToPrevious()` switch to, respectively, the next and previous sessions on the seat in the order of virtual terminals. If there is no active session, they switch to, respectively, the first and last session on the seat. ## Signals Whenever `ActiveSession`, `Sessions`, `CanGraphical`, `CanTTY`, or the idle state changes, `PropertyChanged` signals are sent out to clients which have subscribed. Signals are only emitted on objects referencing a specific seat ID, not on the `/org/freedesktop/login1/seat/self` or `/org/freedesktop/login1/seat/auto` convenience objects, as they can only be dereferenced relative to a method caller. ## Properties The `Id` property encodes the ID of the seat. `ActiveSession` encodes the currently active session if there is one. It is a structure consisting of the session id and the object path. `CanTTY` encodes whether the session is suitable for text logins, and `CanGraphical` whether it is suitable for graphical sessions. The `Sessions` property is an array of all current sessions of this seat, each encoded in a structure consisting of the ID and the object path. The `IdleHint`, `IdleSinceHint`, and `IdleSinceHintMonotonic` properties encode the idle state, similarly to the ones exposed on the Manager object, but specific for this seat. # User Objects node /org/freedesktop/login1/user/_1000 { interface org.freedesktop.login1.User { methods: Terminate(); Kill(in i signal_number); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u UID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u GID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Name = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t Timestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RuntimePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Service = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Slice = '...'; readonly (so) Display = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s State = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(so) Sessions = [...]; readonly b IdleHint = ...; readonly t IdleSinceHint = ...; readonly t IdleSinceHintMonotonic = ...; readonly b Linger = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `Terminate()` and `Kill()` work similarly to the `TerminateUser()` and `KillUser()` methods on the manager object. ## Signals Whenever `Sessions` or the idle state changes, `PropertyChanged` signals are sent out to clients which have subscribed. Signals are only emitted on objects referencing a specific UID, not on the `/org/freedesktop/login1/user/self` convenience object, as `self` can only be dereferenced relative to a method caller. ## Properties The `UID` and `GID` properties encode the Unix UID and primary GID of the user. The `Name` property encodes the user name. `Timestamp` and `TimestampMonotonic` encode the login time of the user in microseconds since the epoch, in the `CLOCK_REALTIME` and `CLOCK_MONOTONIC` clocks, respectively. `RuntimePath` encodes the runtime path of the user, i.e. `$XDG_RUNTIME_DIR`. For details see the [ XDG Basedir Specification ](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). `Service` contains the unit name of the user systemd service of this user. Each logged in user is assigned a user service that runs a user systemd instance. This is usually an instance of `user@.service`. `Slice` contains the unit name of the user systemd slice of this user. Each logged in user gets a private slice. `Display` encodes which graphical session should be used as the primary UI display for the user. It is a structure encoding the session ID and the object path of the session to use. `State` encodes the user state and is one of `offline`, `lingering`, `online`, `active`, or `closing`. See `sd_uid_get_state(3)` for more information about the states. `Sessions` is an array of structures encoding all current sessions of the user. Each structure consists of the ID and object path. The `IdleHint`, `IdleSinceHint`, and `IdleSinceHintMonotonic` properties encode the idle hint state of the user, similarly to the Manager's properties, but specific for this user. The `Linger` property shows whether lingering is enabled for this user. # Session Objects node /org/freedesktop/login1/session/1 { interface org.freedesktop.login1.Session { methods: Terminate(); Activate(); Lock(); Unlock(); SetIdleHint(in b idle); SetLockedHint(in b locked); Kill(in s whom, in i signal_number); TakeControl(in b force); ReleaseControl(); SetType(in s type); SetClass(in s class); SetDisplay(in s display); SetTTY(in h tty_fd); TakeDevice(in u major, in u minor, out h fd, out b inactive); ReleaseDevice(in u major, in u minor); PauseDeviceComplete(in u major, in u minor); SetBrightness(in s subsystem, in s name, in u brightness); signals: PauseDevice(u major, u minor, s type); ResumeDevice(u major, u minor, h fd); Lock(); Unlock(); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Id = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (uo) User = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Name = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t Timestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u VTNr = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (so) Seat = ...; readonly s TTY = '...'; readonly s Display = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b Remote = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RemoteHost = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RemoteUser = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExtraDeviceAccess = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Service = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Desktop = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Scope = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u Leader = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LeaderPIDFDId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u Audit = ...; readonly s Type = '...'; readonly s Class = '...'; readonly b Active = ...; readonly s State = '...'; readonly b IdleHint = ...; readonly t IdleSinceHint = ...; readonly t IdleSinceHintMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CanIdle = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CanLock = ...; readonly b LockedHint = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `Terminate()`, `Activate()`, `Lock()`, `Unlock()`, and `Kill()` work similarly to the respective calls on the Manager object. `SetIdleHint()` is called by the session object to update the idle state of the session whenever it changes. `TakeControl()` allows a process to take exclusive managed device access-control for that session. Only one D-Bus connection can be a controller for a given session at any time. If the `force` argument is set (root only), an existing controller is kicked out and replaced. Otherwise, this method fails if there is already a controller. Note that this method is limited to D-Bus users with the effective UID set to the user of the session or root. `ReleaseControl()` drops control of a given session. Closing the D-Bus connection implicitly releases control as well. See `TakeControl()` for more information. This method also releases all devices for which the controller requested ownership via `TakeDevice()`. `SetType()` allows the type of the session to be changed dynamically. It can only be called by session's current controller. If `TakeControl()` has not been called, this method will fail. In addition, the session type will be reset to its original value once control is released, either by calling `ReleaseControl()` or closing the D-Bus connection. This should help prevent a session from entering an inconsistent state, for example if the controller crashes. The only argument `type` is the new session type. `SetClass()` allows the caller to change the class of the session dynamically. It may only be called by session's owning user. Currently, this call may be exclusively used to change the class from `user-incomplete` to `user`. The call is synchronous, and will return only once the user's service manager has successfully been started, if necessary. The only argument `type` is the new session type. `SetDisplay()` allows the display name of the graphical session to be changed. This is useful if the display server is started as part of the session. It can only be called by session's current controller. If `TakeControl()` has not been called, this method will fail. The only argument `display` is the new display name. `SetTTY()` allows the device name of the session to be changed. This is useful if the tty device is only known after authentication. It can only be called by session's current controller. If `TakeControl()` has not been called, this method will fail. The only argument `tty_fd` is a file handle to the new tty device. `TakeDevice()` allows a session controller to get a file descriptor for a specific device. Pass in the major and minor numbers of the character device and `systemd-logind` will return a file descriptor for the device. Only a limited set of device-types is currently supported (but may be extended). `systemd-logind` automatically mutes the file descriptor if the session is inactive and resumes it once the session is activated again. This guarantees that a session can only access session devices if the session is active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time. This only works on devices that are attached to the seat of the given session. A process is not required to have direct access to the device node. `systemd-logind` only requires you to be the active session controller (see `TakeControl()`). Also note that any device can only be requested once. As long as you do not release it, further `TakeDevice()` calls will fail. `ReleaseDevice()` releases a device again (see `TakeDevice()`). This is also implicitly done by `ReleaseControl()` or when closing the D-Bus connection. `PauseDeviceComplete()` allows a session controller to synchronously pause a device after receiving a `PauseDevice(pause)` signal. Forced signals (or after an internal timeout) are automatically completed by `systemd-logind` asynchronously. `SetLockedHint()` may be used to set the "locked hint" to `locked`, i.e. information whether the session is locked. This is intended to be used by the desktop environment to tell `systemd-logind` when the session is locked and unlocked. `SetBrightness()` may be used to set the display brightness. This is intended to be used by the desktop environment and allows unprivileged programs to access hardware settings in a controlled way. The `subsystem` parameter specifies a kernel subsystem, either `backlight` or `leds`. The `name` parameter specifies a device name under the specified subsystem. The `brightness` parameter specifies the brightness. The range is defined by individual drivers, see `/sys/class/subsystem/name/max_brightness`. ## Signals The active session controller exclusively gets `PauseDevice()` and `ResumeDevice()` events for any device it requested via `TakeDevice()`. They notify the controller whenever a device is paused or resumed. A device is never resumed if its session is inactive. Also note that `PauseDevice()` signals are sent before the `PropertyChanged` signal for the `Active` state. The inverse is true for `ResumeDevice()`. A device may remain paused for unknown reasons even though the Session is active. A `PauseDevice()` signal carries the major and minor numbers and a string describing the type as arguments. `force` means the device was already paused by `systemd-logind` and the signal is only an asynchronous notification. `pause` means `systemd-logind` grants you a limited amount of time to pause the device. You must respond to this via `PauseDeviceComplete()`. This synchronous pausing mechanism is used for backwards-compatibility to VTs and `systemd-logind` is free to not make use of it. It is also free to send a forced `PauseDevice()` if you do not respond in a timely manner (or for any other reason). `gone` means the device was unplugged from the system and you will no longer get any notifications about it. There is no need to call `ReleaseDevice()`. You may call `TakeDevice()` again if a new device is assigned the major+minor combination. `ResumeDevice()` is sent whenever a session is active and a device is resumed. It carries the major/minor numbers as arguments and provides a new open file descriptor. You should switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying open file descriptor in the kernel (except for a limited set of device types). Whenever `Active` or the idle state changes, `PropertyChanged` signals are sent out to clients which have subscribed. `Lock()`/`Unlock()` is sent when the session is asked to be screen-locked/unlocked. A session manager of the session should listen to this signal and act accordingly. This signal is sent out as a result of the `Lock()` and `Unlock()` methods, respectively. Signals are only emitted on objects referencing a specific session ID, not on the `/org/freedesktop/login1/session/self` or `/org/freedesktop/login1/session/auto` convenience objects, as they can only be dereferenced relative to a method caller. ## Properties `Id` encodes the session ID. `User` encodes the user ID of the user this session belongs to. This is a structure consisting of the Unix UID and the object path. `Name` encodes the user name. `Timestamp` and `TimestampMonotonic` encode the microseconds since the epoch when the session was created, in `CLOCK_REALTIME` or `CLOCK_MONOTONIC`, respectively. `VTNr` encodes the virtual terminal number of the session if there is any, 0 otherwise. `Seat` encodes the seat this session belongs to if there is any. This is a structure consisting of the ID and the seat object path. `TTY` encodes the kernel TTY path of the session if this is a text login. If not this is an empty string. `Display` encodes the X11 display name if this is a graphical login. If not, this is an empty string. `Remote` encodes whether the session is local or remote. `RemoteHost` and `RemoteUser` encode the remote host and user if this is a remote session, or an empty string otherwise. `ExtraDeviceAccess` encodes the set of additional hardware devices that the session is granted access to. For every `ID` in the list, the session is granted access to all devices tagged with `xaccess-ID` in udev. `Service` encodes the PAM service name that registered the session. `Desktop` describes the desktop environment running in the session (if known). `Scope` contains the systemd scope unit name of this session. `Leader` encodes the PID of the process that registered the session. `LeaderPIDFDId` encodes the Linux pidfd inode ID of the process that registered the session. `Audit` encodes the Kernel Audit session ID of the session if auditing is available. `Type` encodes the session type. It's one of `unspecified` (for cron PAM sessions and suchlike), `tty` (for text logins), `web` (for web-based logins), or `x11`/`mir`/`wayland` (for graphical logins). `Class` encodes the session class. It's one of `user` (for normal user sessions), `greeter` (for display manager pseudo-sessions), or `lock-screen` (for display lock screens). `Active` is a boolean that is true if the session is active, i.e. currently in the foreground. This field is semi-redundant due to `State`. `State` encodes the session state and one of `online`, `active`, or `closing`. See `sd_session_get_state(3)` for more information about the states. `IdleHint`, `IdleSinceHint`, and `IdleSinceHintMonotonic` encapsulate the idle hint state of this session, similarly to how the respective properties on the manager object do it for the whole system. `LockedHint` shows the locked hint state of this session, as set by the `SetLockedHint()` method described above. `CanIdle` indicates whether the session supports the idle hint concept. Similarly, `CanLock` indicates whether the session supports the screen lock concept. # Examples
Introspect the logind manager on the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1 or $ busctl introspect org.freedesktop.login1 /org/freedesktop/login1
Introspect the default seat on the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1/seat/seat0 or $ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/seat/seat0 Seat `seat0` is the default seat, so it'll be present unless local configuration is made to reassign all devices to a different seat. The list of seats and users can be acquired with `loginctl list-sessions`.
Introspect a single user on the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1/user/_1000 or $ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/user/_1000
Introspect org.freedesktop.login1.Session on the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1/session/45 or $ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/session/45
# History ## The Manager Object `HandlePowerKeyLongPress`, `HandleRebootKey`, `HandleRebootKeyLongPress`, `HandleSuspendKeyLongPress`, and `HandleHibernateKeyLongPress` were added in version 251. `StopIdleSessionUSec` was added in version 252. `PrepareForShutdownWithMetadata()` and `CreateSessionWithPIDFD()` were added in version 255. `Sleep()`, `CanSleep()`, `SleepOperation`, and `ListSessionsEx()` were added in version 256. `HandleSecureAttentionKey`, `SecureAttentionKey()`, `PreparingForShutdownWithMetadata`, `DesignatedMaintenanceTime`, `CanIdle`, `CanLock`, and `BlockWeakInhibited` were added in version 257. ## Session Objects `SetDisplay()` was added in version 252. `SetTTY()` was added in version 254. `SetClass()` was added in version 256. `LeaderPIDFDId` was added in version 258. `ExtraDeviceAccess` was added in version 260. # See Also `systemd(1)`, `systemd-logind.service(8)`, `loginctl(1)` # org.freedesktop.machine1 systemd org.freedesktop.machine1 5 org.freedesktop.machine1 The D-Bus interface of systemd-machined # Introduction `systemd-machined.service(8)` is a system service that keeps track of locally running virtual machines and containers. This page describes the D-Bus interface. # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/machine1 { interface org.freedesktop.machine1.Manager { methods: GetMachine(in s name, out o machine); GetImage(in s name, out o image); GetMachineByPID(in u pid, out o machine); ListMachines(out a(ssso) machines); ListImages(out a(ssbttto) images); CreateMachine(in s name, in ay id, in s service, in s class, in u leader, in s root_directory, in a(sv) scope_properties, out o path); CreateMachineWithNetwork(in s name, in ay id, in s service, in s class, in u leader, in s root_directory, in ai ifindices, in a(sv) scope_properties, out o path); CreateMachineEx(in s name, in a(sv) properties, in a(sv) scope_properties, out o path); RegisterMachine(in s name, in ay id, in s service, in s class, in u leader, in s root_directory, out o path); RegisterMachineWithNetwork(in s name, in ay id, in s service, in s class, in u leader, in s root_directory, in ai ifindices, out o path); RegisterMachineEx(in s name, in a(sv) properties, out o path); UnregisterMachine(in s name); TerminateMachine(in s id); KillMachine(in s name, in s whom, in i signal); GetMachineAddresses(in s name, out a(iay) addresses); GetMachineSSHInfo(in s name, out s ssh_address, out s ssh_private_key_path); GetMachineOSRelease(in s name, out a{ss} fields); OpenMachinePTY(in s name, out h pty, out s pty_path); OpenMachineLogin(in s name, out h pty, out s pty_path); OpenMachineShell(in s name, in s user, in s path, in as args, in as environment, out h pty, out s pty_path); BindMountMachine(in s name, in s source, in s destination, in b read_only, in b mkdir); CopyFromMachine(in s name, in s source, in s destination); CopyToMachine(in s name, in s source, in s destination); CopyFromMachineWithFlags(in s name, in s source, in s destination, in t flags); CopyToMachineWithFlags(in s name, in s source, in s destination, in t flags); OpenMachineRootDirectory(in s name, out h fd); GetMachineUIDShift(in s name, out u shift); RemoveImage(in s name); RenameImage(in s name, in s new_name); CloneImage(in s name, in s new_name, in b read_only); MarkImageReadOnly(in s name, in b read_only); GetImageHostname(in s name, out s hostname); GetImageMachineID(in s name, out ay id); GetImageMachineInfo(in s name, out a{ss} machine_info); GetImageOSRelease(in s name, out a{ss} os_release); SetPoolLimit(in t size); SetImageLimit(in s name, in t size); CleanPool(in s mode, out a(st) images); MapFromMachineUser(in s name, in u uid_inner, out u uid_outer); MapToMachineUser(in u uid_outer, out s machine_name, out o machine_path, out u uid_inner); MapFromMachineGroup(in s name, in u gid_inner, out u gid_outer); MapToMachineGroup(in u gid_outer, out s machine_name, out o machine_path, out u gid_inner); signals: MachineNew(s machine, o path); MachineRemoved(s machine, o path); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s PoolPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t PoolUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t PoolLimit = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `GetMachine()` may be used to get the machine object path for the machine with the specified name. Similarly, `GetMachineByPID()` gets the machine object the specified PID belongs to if there is any. `GetImage()` may be used to get the image object path of the image with the specified name. `ListMachines()` returns an array of all currently registered machines. The structures in the array consist of the following fields: machine name, machine class, an identifier for the service that registered the machine and the machine object path. `ListImages()` returns an array of all currently known images. The structures in the array consist of the following fields: image name, type, read-only flag, creation time, modification time, current disk space, and image object path. `CreateMachine()` may be used to register a new virtual machine or container with `systemd-machined`, creating a scope unit for it. It accepts the following arguments: a machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the service that registers the machine, a class string, the PID of the leader process of the machine, an optional root directory of the container, and an array of additional properties to use for the scope registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only 7 bit ASCII is permitted, a maximum length of 64 characters is enforced, only characters from the set `a-zA-Z0-9-_.` are allowed, the name may not begin with a dot, and it may not contain two dots immediately following each other. Container and VM managers should ideally use the hostname used internally in the machine for this parameter. This recommendation is made in order to make the machine name naturally resolvable using `nss-mymachines(8)`. If a container manager needs to embed characters outside of the indicated range, escaping is required, possibly using `_` as the escape character. Another (somewhat natural) option would be to utilize Internet IDNA encoding. The UUID is passed as a 32 byte array or, if no suitable UUID is available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify the virtual machine/container uniquely and should ideally be the same UUID that `/etc/machine-id` in the VM/container is initialized from. The service string can be free-form, but it is recommended to pass a short lowercase identifier like `systemd-nspawn`, `libvirt-lxc` or similar. The class string should be either `container` or `vm` indicating whether the machine to register is of the respective class. The leader PID should be the host PID of the init process of the container or the encapsulating process of the VM. If the root directory of the container is known and available in the host's hierarchy, it should be passed (note that this is for informational purposes only, and will not be used otherwise). Otherwise, pass the empty string instead. Finally, the scope properties are passed as array in the same way as to PID1's `StartTransientUnit()` method. Calling this method will internally register a transient scope unit for the calling client (utilizing the passed scope_properties) and move the leader PID into it. The method returns an object path for the registered machine object that implements the org.freedesktop.machine1.Machine interface (see below). Also see the [New Control Group Interfaces](https://systemd.io/CONTROL_GROUP_INTERFACE) for details about scope units and how to alter resource control settings on the created machine at runtime. `RegisterMachine()` is similar to `CreateMachine()`. However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is registered. We recommend to only use this method for container or VM managers that are run multiple times, one instance for each container/VM they manage, and are invoked as system services. `RegisterMachineEx()` and `CreateMachineEx()` are similar to the counterparts, but take a series of key/value pairs instead of a fixed number of parameters, to allow for future extensions, and take a PIDFD instead of a PID for the leader parameter. The currently supported parameters are: - `Id` (`ay`): the machine UUID. - `Service` (`s`): the service string. - `Class` (`s`): the class string. - `LeaderPIDFD` (`h`): A PIDFD for the leader process of the machine. This parameter is optional. If it is specified, it is preferred over the combination of `LeaderPID` and `LeaderPIDFDID`. - `LeaderPID` (`u`): A PID for the leader process of the machine. This parameter is optional. Must be specified together with `LeaderPIDFDID`. - `LeaderPIDFDID` (`t`): A PIDFDID for the leader process of the machine. This parameter is optional. Must be specified together with `LeaderPID`. - `RootDirectory` (`s`): The root directory of the container. This parameter is optional and for informational purposes only. - `NetworkInterfaces` (`ai`): An array of network interface indices, as in `CreateMachineWithNetwork()`. This parameter is optional. `CreateMachineWithNetwork()` and `RegisterMachineWithNetwork()` are similar to `CreateMachine()` and `RegisterMachine()` but take an extra argument: an array of network interface indices that point towards the virtual machine or container. The interface indices should reference one or more network interfaces on the host that can be used to communicate with the guest. Commonly, the passed interface index refers to the host side of a "veth" link (in case of containers), a "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6 communication to the machines since the scope field of sockaddr_in6 can be initialized by the specified ifindex. `nss-mymachines(8)` makes use of this information. `KillMachine()` sends a UNIX signal to the machine's processes. As its arguments, it takes a machine name (as originally passed to `CreateMachine()` or returned by `ListMachines()`), an identifier that specifies what precisely to send the signal to (either `leader` or `all`), and a numeric UNIX signal integer. `TerminateMachine()` terminates a virtual machine, killing its processes. It takes a machine name as its only argument. `GetMachineAddresses()` retrieves the IP addresses of a container. This method returns an array of pairs consisting of an address family specifier (`AF_INET` or `AF_INET6`) and a byte array containing the addresses. This is only supported for containers that make use of network namespacing. `GetMachineSSHInfo()` retrieves the SSH information of a machine. This method returns two strings, the SSH address which can be used to tell SSH where to connect, and the path to the SSH private key required for the connection to succeed. `GetMachineOSRelease()` retrieves the OS release information of a container. This method returns an array of key value pairs read from the `os-release(5)` file in the container and is useful to identify the operating system used in a container. `OpenMachinePTY()` allocates a pseudo TTY in the container and returns a file descriptor and its path. This is equivalent to transitioning into the container and invoking `posix_openpt(3)`. `OpenMachineLogin()` allocates a pseudo TTY in the container and ensures that a getty login prompt of the container is running on the other end. It returns the file descriptor of the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the container. `OpenMachineShell()` allocates a pseudo TTY in the container, as the specified user, and invokes the executable at the specified path with a list of arguments (starting from argv\[0\]) and an environment block. It then returns the file descriptor of the PTY and the PTY path. `BindMountMachine()` bind mounts a file or directory from the host into the container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the container, and two booleans, one indicating whether the bind mount shall be read-only, the other indicating whether the destination mount point shall be created first, if it is missing. `CopyFromMachine()` copies files or directories from a container into the host. It takes a container name, a source directory in the container and a destination directory on the host as arguments. `CopyToMachine()` does the opposite and copies files from a source directory on the host into a destination directory in the container. `CopyFromMachineWithFlags()` and `CopyToMachineWithFlags()` do the same but take an additional flags argument. `RemoveImage()` removes the image with the specified name. `RenameImage()` renames the specified image. `CloneImage()` clones the specified image under a new name. It also takes a boolean argument indicating whether the resulting image shall be read-only or not. `MarkImageReadOnly()` toggles the read-only flag of an image. `SetPoolLimit()` sets an overall quota limit on the pool of images. `SetImageLimit()` sets a per-image quota limit. `MapFromMachineUser()`, `MapToMachineUser()`, `MapFromMachineGroup()`, and `MapToMachineGroup()` may be used to map UIDs/GIDs from the host user namespace to a container user namespace or vice versa. ## Signals `MachineNew()` and `MachineRemoved()` are sent whenever a new machine is registered or removed. These signals carry the machine name and the object path to the corresponding org.freedesktop.machine1.Machine interface (see below). ## Properties `PoolPath` specifies the file system path where images are written to. `PoolUsage` specifies the current usage size of the image pool in bytes. `PoolLimit` specifies the size limit of the image pool in bytes. # Machine Objects node /org/freedesktop/machine1/machine/rawhide { interface org.freedesktop.machine1.Machine { methods: Terminate(); Kill(in s whom, in i signal); GetAddresses(out a(iay) addresses); GetSSHInfo(out s ssh_address, out s ssh_private_key_path); GetOSRelease(out a{ss} fields); GetUIDShift(out u shift); OpenPTY(out h pty, out s pty_path); OpenLogin(out h pty, out s pty_path); OpenShell(in s user, in s path, in as args, in as environment, out h pty, out s pty_path); BindMount(in s source, in s destination, in b read_only, in b mkdir); CopyFrom(in s source, in s destination); CopyTo(in s source, in s destination); CopyFromWithFlags(in s source, in s destination, in t flags); CopyToWithFlags(in s source, in s destination, in t flags); OpenRootDirectory(out h fd); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Name = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay Id = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t Timestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Service = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Unit = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Subgroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u Leader = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LeaderPIDFDId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u Supervisor = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t SupervisorPIDFDId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Class = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootDirectory = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ai NetworkInterfaces = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u VSockCID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SSHAddress = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SSHPrivateKeyPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s State = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u UID = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `Terminate()` and `Kill()` terminate/kill the machine. These methods take the same arguments as `TerminateMachine()` and `KillMachine()` on the Manager interface, respectively. `GetAddresses()`, `GetSSHInfo()` and `GetOSRelease()` get the IP address, SSH connection and OS release information from the machine. These methods take the same arguments as `GetMachineAddresses()`, `GetMachineSSHInfo()` and `GetMachineOSRelease()` of the Manager interface, respectively. ## Properties `Name` is the machine name as it was passed in during registration with `CreateMachine()` on the manager object. `Id` is the machine UUID. `Timestamp` and `TimestampMonotonic` are the realtime and monotonic timestamps when the virtual machines where created in microseconds since the epoch. `Service` contains a short string identifying the registering service as passed in during registration of the machine. `Unit` is the systemd scope or service unit name for the machine. `Leader` is the PID of the leader process of the machine. (The leader process is the top-level process of the payload of the machine, i.e. for containers PID 1 inside the container, and for VMs the process encapsulating the VM. Its lifetime defines the lifetime of the machine.) `LeaderPIDFDId` encodes the Linux pidfd inode ID of the leader process of the machine. `Supervisor` is the PID of the supervisor process of the machine. (The supervisor process is the process that manages the machine, if there's a separate one for it. A supervisor process is not always defined, and does not define the machine's lifetime.) `SupervisorPIDFDId` encodes the Linux pidfd inode ID of the supervisor process of the machine. `Class` is the class of the machine and is either the string "vm" (for real VMs based on virtualized hardware) or "container" (for lightweight userspace virtualization sharing the same kernel as the host). `RootDirectory` is the root directory of the container if it is known and applicable or the empty string. `NetworkInterfaces` contains an array of network interface indices that point towards the container, the VM or the host. For details about this information see the description of `CreateMachineWithNetwork()` above. `VSockCID` is the VSOCK CID of the VM if it is known, or `VMADDR_CID_ANY` otherwise. `SSHAddress` is the address of the VM in a format `ssh` can understand if it is known or the empty string. `SSHPrivateKeyPath` is the path to the SSH private key of the VM if it is known or the empty string. `State` is the state of the machine and is one of `opening`, `running`, or `closing`. Note that the state machine is not considered part of the API and states might be removed or added without this being considered API breakage. `Subgroup` contains the sub-control-group path this machine's processes reside in, relative to the specified unit's control group. `UID` contains the numeric UNIX UID of the user who registered the machine. # Examples
Introspect org.freedesktop.machine1.Manager on the bus
$ gdbus introspect --system \ --dest org.freedesktop.machine1 \ --object-path /org/freedesktop/machine1
Introspect org.freedesktop.machine1.Machine on the bus
$ gdbus introspect --system \ --dest org.freedesktop.machine1 \ --object-path /org/freedesktop/machine1/machine/rawhide
# History ## The Manager Object `CopyFromMachineWithFlags()` and `CopyToMachineWithFlags()` were added in version 252. `GetMachineSSHInfo()` was added in version 256. ## Machine Objects `CopyFromWithFlags()` and `CopyToWithFlags()` were added in version 252. `GetSSHInfo()`, `VSockCID`, `SSHAddress`, and `SSHPrivateKeyPath` were added in version 256. `LeaderPIDFDId`, `Supervisor`, `SupervisorPIDFDId`, `Subgroup`, and `UID` were added in version 258. `CreateMachineEx()`, and `RegisterMachineEx()` were added in version 259. # See Also `systemd(1)`, `systemd-machined.service(8)`, `machinectl(1)` # org.freedesktop.network1 systemd org.freedesktop.network1 5 org.freedesktop.network1 The D-Bus interface of systemd-networkd # Introduction `systemd-networkd.service(8)` is a system service that manages and configures network interfaces. This page describes the D-Bus interface. # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/network1 { interface org.freedesktop.network1.Manager { methods: ListLinks(out a(iso) links); GetLinkByName(in s name, out i ifindex, out o path); GetLinkByIndex(in i ifindex, out s name, out o path); SetLinkNTP(in i ifindex, in as servers); SetLinkDNS(in i ifindex, in a(iay) addresses); SetLinkDNSEx(in i ifindex, in a(iayqs) addresses); SetLinkDomains(in i ifindex, in a(sb) domains); SetLinkDefaultRoute(in i ifindex, in b enable); SetLinkLLMNR(in i ifindex, in s mode); SetLinkMulticastDNS(in i ifindex, in s mode); SetLinkDNSOverTLS(in i ifindex, in s mode); SetLinkDNSSEC(in i ifindex, in s mode); SetLinkDNSSECNegativeTrustAnchors(in i ifindex, in as names); RevertLinkNTP(in i ifindex); RevertLinkDNS(in i ifindex); RenewLink(in i ifindex); ForceRenewLink(in i ifindex); ReconfigureLink(in i ifindex); Reload(); DescribeLink(in i ifindex, out s json); Describe(out s json); properties: readonly s OperationalState = '...'; readonly s CarrierState = '...'; readonly s AddressState = '...'; readonly s IPv4AddressState = '...'; readonly s IPv6AddressState = '...'; readonly s OnlineState = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t NamespaceId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NamespaceNSID = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; Provides information about the manager. ## Properties `NamespaceId` contains the inode number of the network namespace that the network service runs in. A client may compare this with the inode number of its own network namespace to verify whether the service manages the same network namespace. `NamespaceNSID` contains the "nsid" identifier the kernel maintains for the network namespace, if there's one assigned. # Link Object node /org/freedesktop/network1/link/_1 { interface org.freedesktop.network1.Link { methods: SetNTP(in as servers); SetDNS(in a(iay) addresses); SetDNSEx(in a(iayqs) addresses); SetDomains(in a(sb) domains); SetDefaultRoute(in b enable); SetLLMNR(in s mode); SetMulticastDNS(in s mode); SetDNSOverTLS(in s mode); SetDNSSEC(in s mode); SetDNSSECNegativeTrustAnchors(in as names); RevertNTP(); RevertDNS(); Renew(); ForceRenew(); Reconfigure(); Describe(out s json); properties: readonly s OperationalState = '...'; readonly s CarrierState = '...'; readonly s AddressState = '...'; readonly s IPv4AddressState = '...'; readonly s IPv6AddressState = '...'; readonly s OnlineState = '...'; readonly s AdministrativeState = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) BitRates = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; Provides information about interfaces. # Network Object node /org/freedesktop/network1/network/_1 { interface org.freedesktop.network1.Network { properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Description = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SourcePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as MatchMAC = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as MatchPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as MatchDriver = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as MatchType = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as MatchName = ['...', ...]; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; Provides information about .network files. # DHCP Server Object node /org/freedesktop/network1/link/_1 { interface org.freedesktop.network1.DHCPServer { properties: readonly a(uayayayayt) Leases = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u PoolSize = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u PoolOffset = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.network1.Link { ... }; }; Provides information about the DHCP server. The `Leases` property contains the currently active leases. The `PoolSize` property contains the total number of addresses in the dynamic address pool. The `PoolOffset` property contains the offset from the subnet base address where the pool starts. These correspond to the `PoolSize=` and `PoolOffset=` settings in `systemd.network(5)`. `UINT32_MAX` is used as a sentinel value for `PoolSize` and `PoolOffset` to indicate that the information is unavailable (i.e. no DHCP server is configured or the link is in relay mode), rather than a valid pool size or offset. # DHCPv4 Client Object node /org/freedesktop/network1/link/_1 { interface org.freedesktop.network1.DHCPv4Client { properties: readonly s State = '...'; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.network1.Link { ... }; }; Provides information about DHCPv4 client status. # DHCPv6 Client Object node /org/freedesktop/network1/link/_1 { interface org.freedesktop.network1.DHCPv6Client { properties: readonly s State = '...'; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.network1.Link { ... }; }; Provides information about DHCPv6 client status. # Examples
Introspect org.freedesktop.network1.Manager on the bus
$ gdbus introspect --system \ --dest org.freedesktop.network1 \ --object-path /org/freedesktop/network1
Introspect org.freedesktop.network1.Link on the bus
$ gdbus introspect --system \ --dest org.freedesktop.network1 \ --object-path /org/freedesktop/network1/link/_11
# History ## DHCP Server Object `PoolSize` and `PoolOffset` were added in version 261. ## DHCPv4 Client Object `State` was added in version 255. ## DHCPv6 Client Object `State` was added in version 255. ## Manager Object `NamespaceNSID` was added in version 256. # See Also `systemd(1)`, `systemd-networkd.service(8)`, `networkctl(1)` # org.freedesktop.oom1 systemd org.freedesktop.oom1 5 org.freedesktop.oom1 The D-Bus interface of systemd-oomd # Introduction `systemd-oomd.service(8)` is a system service which implements a userspace out-of-memory (OOM) killer. This page describes the D-Bus interface. # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/oom1 { interface org.freedesktop.oom1.Manager { methods: DumpByFileDescriptor(out h fd); signals: Killed(s cgroup, s reason); }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `Killed()` signal is sent when any cgroup is killed by oomd. Note that more reasons will be added in the future, and the table below will be expanded accordingly. | Reason | Description | |----|----| | memory-used | Application took too much memory and swap. | | memory-pressure | Application took enough memory and swap to cause sufficient slowdown of other applications. | Killing reasons # History ## The Manager Object `Killed()` was added in version 252. # See Also `systemd(1)`, `systemd-oomd.service(8)`, `oomctl(1)` # org.freedesktop.portable1 systemd org.freedesktop.portable1 5 org.freedesktop.portable1 The D-Bus interface of systemd-portabled # Introduction `systemd-portabled.service(8)` is a system service that may be used to attach, detach and inspect portable services. This page describes the D-Bus interface. # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/portable1 { interface org.freedesktop.portable1.Manager { methods: GetImage(in s image, out o object); ListImages(out a(ssbtttso) images); GetImageOSRelease(in s image, out a{ss} os_release); GetImageMetadata(in s image, in as matches, out s image, out ay os_release, out a{say} units); GetImageMetadataWithExtensions(in s image, in as extensions, in as matches, in t flags, out s image, out ay os_release, out a{say} extensions, out a{say} units); GetImageState(in s image, out s state); GetImageStateWithExtensions(in s image, in as extensions, in t flags, out s state); AttachImage(in s image, in as matches, in s profile, in b runtime, in s copy_mode, out a(sss) changes); AttachImageWithExtensions(in s image, in as extensions, in as matches, in s profile, in s copy_mode, in t flags, out a(sss) changes); DetachImage(in s image, in b runtime, out a(sss) changes); DetachImageWithExtensions(in s image, in as extensions, in t flags, out a(sss) changes); ReattachImage(in s image, in as matches, in s profile, in b runtime, in s copy_mode, out a(sss) changes_removed, out a(sss) changes_updated); ReattachImageWithExtensions(in s image, in as extensions, in as matches, in s profile, in s copy_mode, in t flags, out a(sss) changes_removed, out a(sss) changes_updated); RemoveImage(in s image); MarkImageReadOnly(in s image, in b read_only); SetImageLimit(in s image, in t limit); SetPoolLimit(in t limit); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s PoolPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t PoolUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t PoolLimit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as Profiles = ['...', ...]; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `GetImage()` may be used to get the image object path of the image with the specified name. `ListImages()` returns an array of all currently known images. The structures in the array consist of the following fields: image name, type, read-only flag, creation time, modification time, current disk space, usage and image object path. `GetImageOSRelease()` retrieves the OS release information of an image. This method returns an array of key value pairs read from the `os-release(5)` file in the image and is useful to identify the operating system used in a portable service. `GetImageMetadata()` retrieves metadata associated with an image. This method returns the image name, the image's `os-release(5)` content in the form of a (streamable) array of bytes, and a list of portable units contained in the image, in the form of a string (unit name) and an array of bytes with the content. `GetImageMetadataWithExtensions()` retrieves metadata associated with an image. This method is a superset of `GetImageMetadata()` with the addition of a list of extensions as input parameter, which were overlaid on top of the main image via `AttachImageWithExtensions()`. The path of each extension and an array of bytes with the content of the respective extension-release file are returned, one such structure for each extension named in the input arguments. `GetImageState()` retrieves the image state as one of the following strings: - detached - attached - attached-runtime - enabled - enabled-runtime - running - running-runtime `GetImageStateWithExtensions()` is a superset of `GetImageState()`, with additional support for a list of extensions as input parameters, which is necessary to query the state in case the image was attached in that particular way. The `flag` parameter is currently unused and reserved for future purposes. `AttachImage()` attaches a portable image to the system. This method takes an image path or name, a list of strings that will be used to search for unit files inside the image (partial or complete matches), a string indicating which portable profile to use for the image (see `Profiles` property for a list of available profiles), a boolean indicating whether to attach the image only for the current boot session, and a string representing the preferred copy mode (whether to copy the image or to just symlink it) with the following possible values: - (empty) - copy - symlink - mixed If an empty string is passed the security profile drop-ins and images will be symlinked while unit files will be copied, `copy` will copy, `symlink` will prefer linking if possible (e.g.: a unit has to be copied out of an image), and `mixed` will prefer linking the resources owned by the OS (e.g.: the portable profile located within the host's /usr/ tree) but will copy the resources owned by the portable image (e.g.: the unit files and the images). This method returns the list of changes applied to the system (for example, which unit was added and is now available as a system service). Each change is represented as a triplet of strings: the type of change applied, the path on which it was applied, and the source (if any). The type of change applied will be one of the following possible values: - copy - symlink - write - mkdir Note that an image cannot be attached if a unit that it contains is already present on the system. Note that this method returns only after all the listed operations are completed, and due to the I/O involved it might take some time. `AttachImageWithExtensions()` attaches a portable image to the system. This method is a superset of `AttachImage()` with the addition of a list of extensions as input parameter, which will be overlaid on top of the main image. When this method is used, detaching must be done by passing the same arguments via the `DetachImageWithExtensions()` method. For more details on this functionality, see the `MountImages=` entry on `systemd.exec(5)` and `systemd-sysext(8)`. `DetachImage()` detaches a portable image from the system. This method takes an image path or name, and a boolean indicating whether the image to detach was attached only for the current boot session or persistently. This method returns the list of changes applied to the system (for example, which unit was removed and is no longer available as a system service). Each change is represented as a triplet of strings: the type of change applied, the path on which it was applied, and the source (if any). The type of change applied will be one of the following possible values: - unlink Note that an image cannot be detached if a unit that it contains is running. Note that this method returns only after all the listed operations are completed, and due to the I/O involved it might take some time. `DetachImageWithExtensions()` detaches a portable image from the system. This method is a superset of `DetachImage()` with the addition of a list of extensions as input parameter, which were overlaid on top of the main image via `AttachImageWithExtensions()`. `ReattachImage()` combines the effects of the `AttachImage()` method and the `DetachImage()` method. The difference is that it is allowed to reattach an image while one or more of its units are running. The reattach operation will fail if no matching image is attached. The input parameters match the `AttachImage()` method, and the return parameters are the combination of the return parameters of the `DetachImage()` method (first array, units that were removed) and the `AttachImage()` method (second array, units that were updated or added). `ReattachImageWithExtensions()` reattaches a portable image to the system. This method is a superset of `ReattachImage()` with the addition of a list of extensions as input parameter, which will be overlaid on top of the main image. For more details on this functionality, see the `MountImages=` entry on `systemd.exec(5)` and `systemd-sysext(8)`. `RemoveImage()` removes the image with the specified name. `MarkImageReadOnly()` toggles the read-only flag of an image. `SetPoolLimit()` sets an overall quota limit on the pool of images. `SetImageLimit()` sets a per-image quota limit. The `AttachImageWithExtensions()`, `DetachImageWithExtensions()` and `ReattachImageWithExtensions()` methods take in options as flags instead of booleans to allow for extendability. `SD_SYSTEMD_PORTABLE_FORCE_ATTACH` will bypass the safety checks that ensure the units are not running while the image is attached or detached. `SD_SYSTEMD_PORTABLE_FORCE_EXTENSION` will bypass the check that ensures the `extension-release.NAME` file in the extension image matches the image name. They are defined as follows: #define SD_SYSTEMD_PORTABLE_RUNTIME (UINT64_C(1) << 0) #define SD_SYSTEMD_PORTABLE_FORCE_ATTACH (UINT64_C(1) << 1) #define SD_SYSTEMD_PORTABLE_FORCE_EXTENSION (UINT64_C(1) << 2) ## Properties `PoolPath` specifies the file system path where images are written to. `PoolUsage` specifies the current usage size of the image pool in bytes. `PoolLimit` specifies the size limit of the image pool in bytes. `Profiles` specifies the available runtime profiles for portable services. # The Image Object The service exposes the following interfaces on the Image object on the bus: node /org/freedesktop/portable1 { interface org.freedesktop.portable1.Image { methods: GetOSRelease(out a{ss} os_release); GetMetadata(in as matches, out s image, out ay os_release, out a{say} units); GetMetadataWithExtensions(in as extensions, in as matches, in t flags, out s image, out ay os_release, out a{say} extensions, out a{say} units); GetState(out s state); GetStateWithExtensions(in as extensions, in t flags, out s state); Attach(in as matches, in s profile, in b runtime, in s copy_mode, out a(sss) changes); AttachWithExtensions(in as extensions, in as matches, in s profile, in s copy_mode, in t flags, out a(sss) changes); Detach(in b runtime, out a(sss) changes); DetachWithExtensions(in as extensions, in t flags, out a(sss) changes); Reattach(in as matches, in s profile, in b runtime, in s copy_mode, out a(sss) changes_removed, out a(sss) changes_updated); ReattachWithExtensions(in as extensions, in as matches, in s profile, in s copy_mode, in t flags, out a(sss) changes_removed, out a(sss) changes_updated); Remove(); MarkReadOnly(in b read_only); SetLimit(in t limit); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Name = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Path = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Type = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b ReadOnly = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CreationTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ModificationTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t Usage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t Limit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t UsageExclusive = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t LimitExclusive = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods The following methods implement the same operation as the respective methods on the Manager object (see above). However, these methods operate on the image object and hence does not take an image name parameter. Invoking the methods directly on the Manager object has the advantage of not requiring a `GetImage()` call to get the image object for a specific image name. Calling the methods on the Manager object is hence a round trip optimization. List of methods: - GetOSRelease() - GetMetadata() - GetMetadataWithExtensions() - GetState() - Attach() - AttachWithExtensions() - Detach() - DetachWithExtensions() - Reattach() - ReattachWithExtensions() - Remove() - MarkReadOnly() - SetLimit() ## Properties `Name` specifies the image name. `Path` specifies the file system path where image is stored. `Type` specifies the image type. `ReadOnly` specifies whether the image is read-only. `CreationTimestamp` specifies the image creation timestamp. `ModificationTimestamp` specifies the image modification timestamp. `Usage` specifies the image disk usage. `Limit` specifies the image disk usage limit. `UsageExclusive` specifies the image disk usage (exclusive). `LimitExclusive` specifies the image disk usage limit (exclusive). # History ## The Manager Object `GetImageStateWithExtensions()` was added in version 251. ## The Image Object `GetStateWithExtensions()` was added in version 251. `ReattachWithExtensions()` was added in version 254. # See Also `systemd(1)`, `systemd-portabled.service(8)`, `portablectl(1)` # org.freedesktop.resolve1 systemd org.freedesktop.resolve1 5 org.freedesktop.resolve1 The D-Bus interface of systemd-resolved # Introduction `systemd-resolved.service(8)` is a system service that provides hostname resolution and caching using DNS, LLMNR, and mDNS. It also does DNSSEC validation. This page describes the resolve semantics and the D-Bus interface. This page contains an API reference only. If you are looking for a longer explanation how to use this API, please consult [ Writing Network Configuration Managers](https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers) and [Writing Resolver Clients](https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients). # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/resolve1 { interface org.freedesktop.resolve1.Manager { methods: ResolveHostname(in i ifindex, in s name, in i family, in t flags, out a(iiay) addresses, out s canonical, out t flags); ResolveAddress(in i ifindex, in i family, in ay address, in t flags, out a(is) names, out t flags); ResolveRecord(in i ifindex, in s name, in q class, in q type, in t flags, out a(iqqay) records, out t flags); ResolveService(in i ifindex, in s name, in s type, in s domain, in i family, in t flags, out a(qqqsa(iiay)s) srv_data, out aay txt_data, out s canonical_name, out s canonical_type, out s canonical_domain, out t flags); GetLink(in i ifindex, out o path); SetLinkDNS(in i ifindex, in a(iay) addresses); SetLinkDNSEx(in i ifindex, in a(iayqs) addresses); SetLinkDomains(in i ifindex, in a(sb) domains); SetLinkDefaultRoute(in i ifindex, in b enable); SetLinkLLMNR(in i ifindex, in s mode); SetLinkMulticastDNS(in i ifindex, in s mode); SetLinkDNSOverTLS(in i ifindex, in s mode); SetLinkDNSSEC(in i ifindex, in s mode); SetLinkDNSSECNegativeTrustAnchors(in i ifindex, in as names); RevertLink(in i ifindex); RegisterService(in s id, in s name_template, in s type, in q service_port, in q service_priority, in q service_weight, in aa{say} txt_datas, out o service_path); UnregisterService(in o service_path); ResetStatistics(); FlushCaches(); ResetServerFeatures(); GetDelegate(in s id, out o path); ListDelegates(out a(so) delegates); properties: readonly s LLMNRHostname = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s LLMNR = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s MulticastDNS = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DNSOverTLS = '...'; readonly a(iiay) DNS = [...]; readonly a(iiayqs) DNSEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(iiay) FallbackDNS = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(iiayqs) FallbackDNSEx = [...]; readonly (iiay) CurrentDNSServer = ...; readonly (iiayqs) CurrentDNSServerEx = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(isb) Domains = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) TransactionStatistics = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (ttt) CacheStatistics = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DNSSEC = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tttt) DNSSECStatistics = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b DNSSECSupported = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DNSSECNegativeTrustAnchors = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DNSStubListener = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ResolvConfMode = '...'; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `ResolveHostname()` takes a hostname and resolves it to one or more IP addresses. As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be done on any suitable interface. The `name` parameter specifies the hostname to resolve. Note that if required, IDNA conversion is applied to this name unless it is resolved via LLMNR or MulticastDNS. The `family` parameter limits the results to a specific address family. It may be `AF_INET`, `AF_INET6` or `AF_UNSPEC`. If `AF_UNSPEC` is specified (recommended), both kinds are retrieved, subject to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is retrieved; and similarly for IPv4). A 64-bit `flags` field may be used to alter the behaviour of the resolver operation (see below). The method returns an array of address records. Each address record consists of the interface index the address belongs to, an address family as well as a byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address family). The returned address family will be one of `AF_INET` or `AF_INET6`. For IPv6, the returned address interface index should be used to initialize the .sin6_scope_id field of a struct sockaddr_in6 instance to permit support for resolution to link-local IP addresses. The address array is followed by the canonical name of the host, which may or may not be identical to the resolved hostname. Finally, a 64-bit `flags` field is returned that is defined similarly to the `flags` field that was passed in, but contains information about the resolved data (see below). If the hostname passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned. In this case, no network communication is done. `ResolveAddress()` executes the reverse operation: it takes an IP address and acquires one or more hostnames for it. As parameters it takes the interface index to execute the query on, or `0` if all suitable interfaces are OK. The `family` parameter indicates the address family of the IP address to resolve. It may be either `AF_INET` or `AF_INET6`. The `address` parameter takes the raw IP address data (as either a 4 or 16 byte array). The `flags` input parameter may be used to alter the resolver operation (see below). The method returns an array of name records, each consisting of an interface index and a hostname. The `flags` output field contains additional information about the resolver operation (see below). `ResolveRecord()` takes a DNS resource record (RR) type, class and name, and retrieves the full resource record set (RRset), including the RDATA, for it. As parameter it takes the Linux network interface index to execute the query on, or `0` if it may be done on any suitable interface. The `name` parameter specifies the RR domain name to look up (no IDNA conversion is applied), followed by the 16-bit class and type fields (which may be ANY). Finally, a `flags` field may be passed in to alter behaviour of the look-up (see below). On completion, an array of RR items is returned. Each array entry consists of the network interface index the RR was discovered on, the class and type field of the RR found, and a byte array of the raw RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed by the RR type, class, TTL and RDATA, in the binary format documented in [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt). For RRs that support name compression in the payload (such as MX or PTR), the compression is expanded in the returned data. Note that currently, the class field has to be specified as IN or ANY. Specifying a different class will return an error indicating that look-ups of this kind are unsupported. Similarly, some special types are not supported either (AXFR, OPT, …). While `systemd-resolved` parses and validates resource records of many types, it is crucial that clients using this API understand that the RR data originates from the network and should be thoroughly validated before use. `ResolveService()` may be used to resolve a DNS `SRV` service record, as well as the hostnames referenced in it, and possibly an accompanying DNS-SD `TXT` record containing additional service metadata. The primary benefit of using this method over `ResolveRecord()` specifying the `SRV` type is that it will resolve the `SRV` and `TXT` RRs as well as the hostnames referenced in the SRV in a single operation. As parameters it takes a Linux network interface index, a service name, a service type and a service domain. This method may be invoked in three different modes: 1. To resolve a DNS-SD service, specify the service name (e.g. `Lennart's Files`), the service type (e.g. `_webdav._tcp`) and the domain to search in (e.g. `local`) as the three service parameters. The service name must be in UTF-8 format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD specifications). However, if necessary, IDNA conversion is applied to the domain parameter. 2. To resolve a plain `SRV` record, set the service name parameter to the empty string and set the service type and domain properly. (IDNA conversion is applied to the domain, if necessary.) 3. Alternatively, leave both the service name and type empty and specify the full domain name of the `SRV` record (i.e. prefixed with the service type) in the domain parameter. (No IDNA conversion is applied in this mode.) The `family` parameter of the `ResolveService()` method encodes the desired family of the addresses to resolve (use `AF_INET`, `AF_INET6`, or `AF_UNSPEC`). If this is enabled (Use the `NO_ADDRESS` flag to turn address resolution off, see below). The `flags` parameter takes a couple of flags that may be used to alter the resolver operation. On completion, `ResolveService()` returns an array of `SRV` record structures. Each items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the `SRV` record. Immediately following is an array of the addresses of this hostname, with each item consisting of the interface index, the address family and the address data in a byte array. This address array is followed by the canonicalized hostname. After this array of `SRV` record structures an array of byte arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters are the canonical service name, type and domain. This may or may not be identical to the parameters passed in. Finally, a `flags` field is returned that contains information about the resolver operation performed. The `ResetStatistics()` method resets the various statistics counters that `systemd-resolved` maintains to zero. (For details, see the statistics properties below.) The `GetLink()` method takes a network interface index and returns the object path to the org.freedesktop.resolve1.Link object corresponding to it. The `SetLinkDNS()` method sets the DNS servers to use on a specific interface. This method (and the following ones) may be used by network management software to configure per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP address records. Each array item consists of an address family (either `AF_INET` or `AF_INET6`), followed by a 4-byte or 16-byte array with the raw address data. This method is a one-step shortcut for retrieving the Link object for a network interface using `GetLink()` (see above) and then invoking the `SetDNS()` method (see below) on it. `SetLinkDNSEx()` is similar to `SetLinkDNS()`, but allows an IP port (instead of the default 53) and DNS name to be specified for each DNS server. The server name is used for Server Name Indication (SNI), which is useful when DNS-over-TLS is used. C.f. `DNS=` in `resolved.conf(5)`. `SetLinkDefaultRoute()` specifies whether the link shall be used as the default route for name queries. See the description of name routing in `systemd-resolved.service(8)` for details. The `SetLinkDomains()` method sets the search and routing domains to use on a specific network interface for DNS look-ups. It takes a network interface index and an array of domains, each with a boolean parameter indicating whether the specified domain shall be used as a search domain (false), or just as a routing domain (true). Search domains are used for qualifying single-label names into FQDN when looking up hostnames, as well as for making routing decisions on which interface to send queries ending in the domain to. Routing domains are only used for routing decisions and not used for single-label name qualification. Pass the search domains in the order they should be used. The `SetLinkLLMNR()` method enables or disables LLMNR support on a specific network interface. It takes a network interface index as well as a string that may either be empty or one of `yes`, `no` or `resolve`. If empty, the systemd-wide default LLMNR setting is used. If `yes`, LLMNR is used for resolution of single-label names and the local hostname is registered on all local LANs for LLMNR resolution by peers. If `no`, LLMNR is turned off fully on this interface. If `resolve`, LLMNR is only enabled for resolving names, but the local hostname is not registered for other peers to use. Similarly, the `SetLinkMulticastDNS()` method enables or disables MulticastDNS support on a specific interface. It takes the same parameters as `SetLinkLLMNR()` described above. The `SetLinkDNSSEC()` method enables or disables DNSSEC validation on a specific network interface. It takes a network interface index as well as a string that may either be empty or one of `yes`, `no`, or `allow-downgrade`. When empty, the system-wide default DNSSEC setting is used. If `yes`, full DNSSEC validation is done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this mode is used. If `no`, DNSSEC validation is fully disabled. If `allow-downgrade`, DNSSEC validation is enabled, but is turned off automatically if the selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC only applies to traditional DNS, not to LLMNR or MulticastDNS. The `SetLinkDNSSECNegativeTrustAnchors()` method may be used to configure DNSSEC Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a list of domains as arguments. The `SetLinkDNSOverTLS()` method enables or disables DNS-over-TLS. C.f. `DNSOverTLS=` in `systemd-resolved.service(8)` for details. Network management software integrating with `systemd-resolved` should call `SetLinkDNS()` or `SetLinkDNSEx()`, `SetLinkDefaultRoute()`, `SetLinkDomains()` and others after the interface appeared in the kernel (and thus after a network interface index has been assigned), but before the network interfaces is activated (`IFF_UP` set) so that all settings take effect during the full time the network interface is up. It is safe to alter settings while the interface is up, however. Use `RevertLink()` (described below) to reset all per-interface settings. The `RevertLink()` method may be used to revert all per-link settings described above to the defaults. The `FlushCaches()` method flushes all resource record caches maintained by the resolver, and ensures that any subsequent lookups re-request their responses from their sources. The `ResetServerFeatures()` method flushes any feature information learned about remote DNS servers. This ensures that subsequent lookups will be initially attempted at the highest DNS protocol feature level again, possibly requiring a (potentially slow) downgrade cycle to recognize the supported feature level again. The `RegisterService()` method may be used to register a DNS-SD service on the host. This functionality is closely related to the functionality provided by `systemd.dnssd(5)` files. It takes a server identifier string as first parameter (this is just a local identifier, and should be chosen so that it neither collides with the basename of `*.dnssd` files nor with names chosen by other IPC clients). It also takes a name template string for the DNS-SD service name visible on the network. This string is subject to specifier expansation, as documented for the `Name=` setting in `*.dnssd` files. It also takes a service type string containing the DNS-SD service type, as well as an IP port, a priority/weight pair for the DNS-SD SRV record. Finally, it takes an array of TXT record data. It returns an object path which may be used as handle to the registered service. The lifetime of a service registered via this method is bound to the D-Bus connection of the client that registered it: when the client disconnects from the bus the service is automatically unregistered and goodbye packets are sent out, as if `UnregisterService()` had been called. Clients hence must keep their bus connection open for as long as the service shall remain registered. The registration also does not survive `systemd-resolved` losing its own bus connection, in which case tracking clients is not possible anymore and all services registered via this method are unregistered. To register a DNS-SD service independently of a client's lifetime, use `*.dnssd` files, see `systemd.dnssd(5)`. Note that prior to version 262, due to a bug, the client's connection was not tracked and services registered via this method stayed registered until the daemon exited. The `UnregisterService()` method undoes the effect of `RegisterService()` and deletes a DNS-SD service previously created via IPC again. The `GetDelegate()` method returns the D-Bus object path for the specified DNS delegate ID. The `ListDelegates()` method returns a list of the IDs and D-Bus object paths of the currently configured DNS delegates. ### The Flags Parameter The four methods above accept and return a 64-bit flags value. In most cases passing 0 is sufficient and recommended. However, the following flags are defined to alter the look-up: /* Input+Output: Protocol/scope */ #define SD_RESOLVED_DNS (UINT64_C(1) << 0) #define SD_RESOLVED_LLMNR_IPV4 (UINT64_C(1) << 1) #define SD_RESOLVED_LLMNR_IPV6 (UINT64_C(1) << 2) #define SD_RESOLVED_MDNS_IPV4 (UINT64_C(1) << 3) #define SD_RESOLVED_MDNS_IPV6 (UINT64_C(1) << 4) /* Input: Restrictions */ #define SD_RESOLVED_NO_CNAME (UINT64_C(1) << 5) #define SD_RESOLVED_NO_TXT (UINT64_C(1) << 6) #define SD_RESOLVED_NO_ADDRESS (UINT64_C(1) << 7) #define SD_RESOLVED_NO_SEARCH (UINT64_C(1) << 8) #define SD_RESOLVED_NO_VALIDATE (UINT64_C(1) << 10) #define SD_RESOLVED_NO_SYNTHESIZE (UINT64_C(1) << 11) #define SD_RESOLVED_NO_CACHE (UINT64_C(1) << 12) #define SD_RESOLVED_NO_ZONE (UINT64_C(1) << 13) #define SD_RESOLVED_NO_TRUST_ANCHOR (UINT64_C(1) << 14) #define SD_RESOLVED_NO_NETWORK (UINT64_C(1) << 15) #define SD_RESOLVED_NO_STALE (UINT64_C(1) << 24) #define SD_RESOLVED_RELAX_SINGLE_LABEL (UINT64_C(1) << 25) /* Output: Security */ #define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) << 9) #define SD_RESOLVED_CONFIDENTIAL (UINT64_C(1) << 18) /* Output: Origin */ #define SD_RESOLVED_SYNTHETIC (UINT64_C(1) << 19) #define SD_RESOLVED_FROM_CACHE (UINT64_C(1) << 20) #define SD_RESOLVED_FROM_ZONE (UINT64_C(1) << 21) #define SD_RESOLVED_FROM_TRUST_ANCHOR (UINT64_C(1) << 22) #define SD_RESOLVED_FROM_NETWORK (UINT64_C(1) << 23) #define SD_RESOLVED_FROM_HOOK (UINT64_C(1) << 27) On input, the first five flags control the protocols to use for the look-up. They refer to classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the look-up will be done via all suitable protocols for the specific look-up. Note that these flags operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, `systemd-resolved` will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address domains), and single-label names to LLMNR (plus some reverse address lookup domains). It will route neither of these to Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only on interfaces suitable for multicast. On output, these five flags indicate which protocol was used to execute the operation, and hence where the data was found. The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved earlier. In this case, it is often a good idea to limit the follow-up look-up to the protocol that was used to discover the first DNS result. The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the look-up. This flag is only available at input, none of the functions will return it on output. If a CNAME/DNAME RR is discovered while resolving a hostname, an error is returned instead. By default, when the flag is off, CNAME/DNAME RRs are followed. The NO_TXT and NO_ADDRESS flags only influence operation of the `ResolveService()` method. They are only defined for input, not output. If NO_TXT is set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is set, the discovered hostnames are not implicitly translated to their addresses. The NO_SEARCH flag turns off the search domain logic. It is only defined for input in `ResolveHostname()`. When specified, single-label hostnames are not qualified using defined search domains, if any are configured. Note that `ResolveRecord()` will never qualify single-label domain names using search domains. Also note that multi-label hostnames are never subject to search list expansion. NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be used. The next six flags allow disabling certain sources during resolution. NO_SYNTHESIZE disables synthetic records, e.g. the local host name, see section SYNTHETIC RECORDS in `systemd-resolved.service(8)` for more information. NO_CACHE disables the use of the cache of previously resolved records. NO_ZONE disables answers using locally registered public LLMNR/mDNS resource records. NO_TRUST_ANCHOR disables answers using locally configured trust anchors. NO_NETWORK requires all answers to be provided without using the network, i.e. either from local sources or the cache. NO_STALE flag can be set to disable answering request with stale records. The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected data for which a full trust chain may be established to a trusted domain anchor. It is also set for locally synthesized data, such as `localhost` or data from `/etc/hosts`. Moreover, it is set for all LLMNR or mDNS RRs which originate from the local host. Applications that require authenticated RR data for operation should check this flag before trusting the data. Note that `systemd-resolved` will never return invalidated data, hence this flag simply allows one to discern the cases where data is known to be trusted, or where there is proof that the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server does not support authenticating data). CONFIDENTIAL means the query was resolved via encrypted channels or never left this system. The next five bits flags are used in output and provide information about the origin of the answer. FROM_SYNTHETIC means the query was (at least partially) synthesized locally. FROM_CACHE means the query was answered (at least partially) using the cache. FROM_ZONE means the query was answered (at least partially) based on public, locally registered records. FROM_TRUST_ANCHOR means the query was answered (at least partially) using local trust anchors. FROM_NETWORK means the query was answered (at least partially) using the network. ## Properties The `LLMNR` and `MulticastDNS` properties report whether LLMNR and MulticastDNS are (globally) enabled. Each may be one of `yes`, `no`, and `resolve`. See `SetLinkLLMNR()` and `SetLinkMulticastDNS()` above. `LLMNRHostname` contains the hostname currently exposed on the network via LLMNR. It usually follows the system hostname as may be queried via `gethostname(3)`, but may differ if a conflict is detected on the network. `DNS` and `DNSEx` contain arrays of all DNS servers currently used by `systemd-resolved`. `DNS` contains information similar to the DNS server data in `/run/systemd/resolve/resolv.conf`. Each structure in the array consists of a numeric network interface index, an address family, and a byte array containing the DNS server address (either 4 bytes in length for IPv4 or 16 bytes in lengths for IPv6). `DNSEx` is similar, but additionally contains the IP port and server name (used for Server Name Indication, SNI). Both arrays contain DNS servers configured system-wide, including those possibly read from a foreign `/etc/resolv.conf` or the `DNS=` setting in `/etc/systemd/resolved.conf`, as well as per-interface DNS server information either retrieved from `systemd-networkd(8)`, or configured by external software via `SetLinkDNS()` or `SetLinkDNSEx()` (see above). The network interface index will be 0 for the system-wide configured services and non-zero for the per-link servers. `FallbackDNS` and `FallbackDNSEx` contain arrays of all DNS servers configured as fallback servers, if any, using the same format as `DNS` and `DNSEx` described above. See the description of `FallbackDNS=` in `resolved.conf(5)` for the description of when those servers are used. `CurrentDNSServer` and `CurrentDNSServerEx` specify the server that is currently used for query resolution, in the same format as a single entry in the `DNS` and `DNSEx` arrays described above. Similarly, the `Domains` property contains an array of all search and routing domains currently used by `systemd-resolved`. Each entry consists of a network interface index (again, 0 encodes system-wide entries), the actual domain name, and whether the entry is used only for routing (true) or for both routing and searching (false). The `TransactionStatistics` property contains information about the number of transactions `systemd-resolved` has processed. It contains a pair of unsigned 64-bit counters, the first containing the number of currently ongoing transactions, the second the number of total transactions `systemd-resolved` is processing or has processed. The latter value may be reset using the `ResetStatistics()` method described above. Note that the number of transactions does not directly map to the number of issued resolver bus method calls. While simple look-ups usually require a single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC are in use. The `CacheStatistics` property contains information about the executed cache operations so far. It exposes three 64-bit counters: the first being the total number of current cache entries (both positive and negative), the second the number of cache hits, and the third the number of cache misses. The latter counters may be reset using `ResetStatistics()` (see above). The `DNSSEC` property specifies current status of DNSSEC validation. It is one of `yes` (validation is enforced), `no` (no validation is done), `allow-downgrade` (validation is done if the current DNS server supports it). See the description of `DNSSEC=` in `resolved.conf(5)`. The `DNSSECStatistics` property contains information about the DNSSEC validations executed so far. It contains four 64-bit counters: the number of secure, insecure, bogus, and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and each non-existence proof. The secure counter is increased for each operation that successfully verified a signed reply, the insecure counter is increased for each operation that successfully verified that an unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the validation did not check out and the data is likely to have been tampered with. Finally, the indeterminate counter is increased for each operation which did not complete because the necessary keys could not be acquired or the cryptographic algorithms were unknown. The `DNSSECSupported` boolean property reports whether DNSSEC is enabled and the selected DNS servers support it. It combines information about system-wide and per-link DNS settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for which DNS is configured and for the system-wide settings if there are any. Note that `systemd-resolved` assumes DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported value may initially be true, until the first transactions are executed. The `DNSOverTLS` boolean property reports whether DNS-over-TLS is enabled. The `ResolvConfMode` property exposes how `/etc/resolv.conf` is managed on the host. Currently, the values `uplink`, `stub`, `static` (these three correspond to the three different files `systemd-resolved.service` provides), `foreign` (the file is managed by admin or another service, `systemd-resolved.service` just consumes it), `missing` (`/etc/resolv.conf` is missing). The `DNSStubListener` property reports whether the stub listener on port 53 is enabled. Possible values are `yes` (enabled), `no` (disabled), `udp` (only the UDP listener is enabled), and `tcp` (only the TCP listener is enabled). The `DNSSECNegativeTrustAnchors` property contains a list of recognized DNSSEC negative trust anchors and contains a list of domains. # Link Object node /org/freedesktop/resolve1/link/_1 { interface org.freedesktop.resolve1.Link { methods: SetDNS(in a(iay) addresses); SetDNSEx(in a(iayqs) addresses); SetDomains(in a(sb) domains); SetDefaultRoute(in b enable); SetLLMNR(in s mode); SetMulticastDNS(in s mode); SetDNSOverTLS(in s mode); SetDNSSEC(in s mode); SetDNSSECNegativeTrustAnchors(in as names); Revert(); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ScopesMask = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iay) DNS = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayqs) DNSEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (iay) CurrentDNSServer = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (iayqs) CurrentDNSServerEx = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(sb) Domains = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b DefaultRoute = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s LLMNR = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s MulticastDNS = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DNSOverTLS = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DNSSEC = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DNSSECNegativeTrustAnchors = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b DNSSECSupported = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; For each Linux network interface a "Link" object is created which exposes per-link DNS configuration and state. Use `GetLink()` on the Manager interface to retrieve the object path for a link object given the network interface index (see above). ## Methods The various methods exposed by the Link interface are equivalent to their similarly named counterparts on the Manager interface. e.g. `SetDNS()` on the Link object maps to `SetLinkDNS()` on the Manager object, the main difference being that the later expects an interface index to be specified. Invoking the methods on the Manager interface has the benefit of reducing roundtrips, as it is not necessary to first request the Link object path via `GetLink()` before invoking the methods. The same relationship holds for `SetDNSEx()`, `SetDomains()`, `SetDefaultRoute()`, `SetLLMNR()`, `SetMulticastDNS()`, `SetDNSOverTLS()`, `SetDNSSEC()`, `SetDNSSECNegativeTrustAnchors()`, and `Revert()`. For further details on these methods see the Manager documentation above. ## Properties `ScopesMask` defines which resolver scopes are currently active on this interface. This 64-bit unsigned integer field is a bit mask consisting of a subset of the bits of the flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in the "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR and MulticastDNS properties also exposed on the Link interface. The latter expose what is \*configured\* to be used on the interface, the former expose what is actually used on the interface, taking into account the abilities of the interface. `DNSSECSupported` exposes a boolean field that indicates whether DNSSEC is currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface, it is assumed available until it is detected that the configured server does not actually support it. Thus, this property may initially report that DNSSEC is supported on an interface. `DefaultRoute` exposes a boolean field that indicates whether the interface will be used as default route for name queries. See `SetLinkDefaultRoute()` above. The other properties reflect the state of the various configuration settings for the link which may be set with the various methods calls such as `SetDNS()` or `SetLLMNR()`. # Common Errors Many bus methods `systemd-resolved` exposes (in particular the resolver methods such as `ResolveHostname()` on the Manager interface) may return some of the following errors: `org.freedesktop.resolve1.NoNameServers` No suitable DNS servers were found to resolve a request. `org.freedesktop.resolve1.InvalidReply` A response from the selected DNS server was not understood. `org.freedesktop.resolve1.NoSuchRR` The requested name exists, but there is no resource record of the requested type for it. (This is the DNS NODATA case). `org.freedesktop.resolve1.CNameLoop` The look-up failed because a CNAME or DNAME loop was detected. `org.freedesktop.resolve1.Aborted` The look-up was aborted because the selected protocol became unavailable while the operation was ongoing. `org.freedesktop.resolve1.NoSuchService` A service look-up was successful, but the `SRV` record reported that the service is not available. `org.freedesktop.resolve1.DnssecFailed` The acquired response did not pass DNSSEC validation. `org.freedesktop.resolve1.NoTrustAnchor` No chain of trust could be established for the response to a configured DNSSEC trust anchor. `org.freedesktop.resolve1.ResourceRecordTypeUnsupported` The requested resource record type is not supported on the selected DNS servers. This error is generated for example when an RRSIG record is requested from a DNS server that does not support DNSSEC. `org.freedesktop.resolve1.NoSuchLink` No network interface with the specified network interface index exists. `org.freedesktop.resolve1.LinkBusy` The requested configuration change could not be made because `systemd-networkd(8)`, already took possession of the interface and supplied configuration data for it. `org.freedesktop.resolve1.NetworkDown` The requested look-up failed because the system is currently not connected to any suitable network. `org.freedesktop.resolve1.DnsError.NXDOMAIN`; `org.freedesktop.resolve1.DnsError.REFUSED`; ... The look-up failed with a DNS return code reporting a failure. The error names used as suffixes here are defined in by IANA in [DNS RCODEs](https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6). # Examples
Introspect org.freedesktop.resolve1.Manager on the bus
$ gdbus introspect --system \ --dest org.freedesktop.resolve1 \ --object-path /org/freedesktop/resolve1
Introspect org.freedesktop.resolve1.Link on the bus
$ gdbus introspect --system \ --dest org.freedesktop.resolve1 \ --object-path /org/freedesktop/resolve1/link/_11
# History ## The Manager Object `GetDelegate()` and `ListDelegates()` were added in version 258. # See Also `systemd(1)`, `systemd-resolved.service(8)`, `resolvectl(1)` # org.freedesktop.systemd1 systemd org.freedesktop.systemd1 5 org.freedesktop.systemd1 The D-Bus interface of systemd # Introduction `systemd(1)` and its auxiliary daemons expose a number of APIs over D-Bus. This page only describes the various APIs exposed by the system and service manager itself. It does not cover the auxiliary daemons. The service manager exposes a number of objects on the bus: one Manager object as a central entry point for clients along with individual objects for each unit and for each queued job. The unit objects implement a generic Unit interface as well as a type-specific interface. For example, service units implement both org.freedesktop.systemd1.Unit and org.freedesktop.systemd1.Service. The manager object can list unit and job objects or directly convert a unit name or job identifier to a bus path of the corresponding D-Bus object. Properties exposing time values are usually encoded in microseconds (μs) on the bus, even if their corresponding settings in the unit files are in seconds. PID 1 uses [polkit](https://www.freedesktop.org/software/polkit/docs/latest/) to allow access to privileged operations for unprivileged processes. Some operations (such as shutdown/reboot/suspend) are also available through the D-Bus API of logind, see `org.freedesktop.login1(5)`. # The Manager Object The main entry point object is available on the fixed `/org/freedesktop/systemd1` object path: node /org/freedesktop/systemd1 { interface org.freedesktop.systemd1.Manager { methods: GetUnit(in s name, out o unit); GetUnitByPID(in u pid, out o unit); GetUnitByInvocationID(in ay invocation_id, out o unit); GetUnitByControlGroup(in s cgroup, out o unit); GetUnitByPIDFD(in h pidfd, out o unit, out s unit_id, out ay invocation_id); LoadUnit(in s name, out o unit); StartUnit(in s name, in s mode, out o job); StartUnitWithFlags(in s name, in s mode, in t flags, out o job); StartUnitReplace(in s old_unit, in s new_unit, in s mode, out o job); StopUnit(in s name, in s mode, out o job); ReloadUnit(in s name, in s mode, out o job); RestartUnit(in s name, in s mode, out o job); TryRestartUnit(in s name, in s mode, out o job); ReloadOrRestartUnit(in s name, in s mode, out o job); ReloadOrTryRestartUnit(in s name, in s mode, out o job); EnqueueUnitJob(in s name, in s job_type, in s job_mode, out u job_id, out o job_path, out s unit_id, out o unit_path, out s job_type, out a(uosos) affected_jobs); EnqueueUnitJobMany(in as units, in s job_type, in s job_mode, in t flags, out a(uosos) jobs); KillUnit(in s name, in s whom, in i signal); KillUnitSubgroup(in s name, in s whom, in s subgroup, in i signal); QueueSignalUnit(in s name, in s whom, in i signal, in i value); CleanUnit(in s name, in as mask); FreezeUnit(in s name); ThawUnit(in s name); ResetFailedUnit(in s name); SetUnitProperties(in s name, in b runtime, in a(sv) properties); BindMountUnit(in s name, in s source, in s destination, in b read_only, in b mkdir); MountImageUnit(in s name, in s source, in s destination, in b read_only, in b mkdir, in a(ss) options); RefUnit(in s name); UnrefUnit(in s name); StartTransientUnit(in s name, in s mode, in a(sv) properties, in a(sa(sv)) aux, out o job); GetUnitProcesses(in s name, out a(sus) processes); AttachProcessesToUnit(in s unit_name, in s subcgroup, in au pids); RemoveSubgroupFromUnit(in s unit_name, in s subcgroup, in t flags); AbandonScope(in s name); GetJob(in u id, out o job); GetJobAfter(in u id, out a(usssoo) jobs); GetJobBefore(in u id, out a(usssoo) jobs); CancelJob(in u id); ClearJobs(); ResetFailed(); SetShowStatus(in s mode); ListUnits(out a(ssssssouso) units); ListUnitsFiltered(in as states, out a(ssssssouso) units); ListUnitsByPatterns(in as states, in as patterns, out a(ssssssouso) units); ListUnitsByNames(in as names, out a(ssssssouso) units); ListJobs(out a(usssoo) jobs); Subscribe(); Unsubscribe(); Dump(out s output); DumpUnitsMatchingPatterns(in as patterns, out s output); DumpByFileDescriptor(out h fd); DumpUnitsMatchingPatternsByFileDescriptor(in as patterns, out h fd); Reload(); @org.freedesktop.DBus.Method.NoReply("true") Reexecute(); @org.freedesktop.systemd1.Privileged("true") Exit(); @org.freedesktop.systemd1.Privileged("true") Reboot(); @org.freedesktop.systemd1.Privileged("true") SoftReboot(in s new_root); @org.freedesktop.systemd1.Privileged("true") PowerOff(); @org.freedesktop.systemd1.Privileged("true") Halt(); @org.freedesktop.systemd1.Privileged("true") KExec(); @org.freedesktop.systemd1.Privileged("true") SwitchRoot(in s new_root, in s init); SetEnvironment(in as assignments); UnsetEnvironment(in as names); UnsetAndSetEnvironment(in as names, in as assignments); EnqueueMarkedJobs(out ao jobs); ListUnitFiles(out a(ss) unit_files); ListUnitFilesByPatterns(in as states, in as patterns, out a(ss) unit_files); GetUnitFileState(in s file, out s state); EnableUnitFiles(in as files, in b runtime, in b force, out b carries_install_info, out a(sss) changes); DisableUnitFiles(in as files, in b runtime, out a(sss) changes); EnableUnitFilesWithFlags(in as files, in t flags, out b carries_install_info, out a(sss) changes); DisableUnitFilesWithFlags(in as files, in t flags, out a(sss) changes); DisableUnitFilesWithFlagsAndInstallInfo(in as files, in t flags, out b carries_install_info, out a(sss) changes); ReenableUnitFiles(in as files, in b runtime, in b force, out b carries_install_info, out a(sss) changes); LinkUnitFiles(in as files, in b runtime, in b force, out a(sss) changes); PresetUnitFiles(in as files, in b runtime, in b force, out b carries_install_info, out a(sss) changes); PresetUnitFilesWithMode(in as files, in s mode, in b runtime, in b force, out b carries_install_info, out a(sss) changes); MaskUnitFiles(in as files, in b runtime, in b force, out a(sss) changes); UnmaskUnitFiles(in as files, in b runtime, out a(sss) changes); RevertUnitFiles(in as files, out a(sss) changes); SetDefaultTarget(in s name, in b force, out a(sss) changes); GetDefaultTarget(out s name); PresetAllUnitFiles(in s mode, in b runtime, in b force, out a(sss) changes); AddDependencyUnitFiles(in as files, in s target, in s type, in b runtime, in b force, out a(sss) changes); GetUnitFileLinks(in s name, in b runtime, out as links); SetExitCode(in y number); LookupDynamicUserByName(in s name, out u uid); LookupDynamicUserByUID(in u uid, out s name); GetDynamicUsers(out a(us) users); DumpUnitFileDescriptorStore(in s name, out a(suuutuusu) entries); signals: UnitNew(s id, o unit); UnitRemoved(s id, o unit); JobNew(u id, o job, s unit); JobRemoved(u id, o job, s unit, s result); StartupFinished(t firmware, t loader, t kernel, t initrd, t userspace, t total); UnitFilesChanged(); Reloading(b active); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Version = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Features = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Virtualization = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ConfidentialVirtualization = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Architecture = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Tainted = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t FirmwareTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t FirmwareTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LoaderTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LoaderTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t KernelTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t KernelTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UserspaceTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UserspaceTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t FinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t FinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t ShutdownStartTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t ShutdownStartTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t ShutdownFinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t ShutdownFinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PreviousShutdownStartTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PreviousShutdownStartTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PreviousShutdownFinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PreviousShutdownFinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PreviousShutdownLateStartTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PreviousShutdownLateStartTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PreviousShutdownLateFinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PreviousShutdownLateFinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t SecurityStartTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t SecurityStartTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t SecurityFinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t SecurityFinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t GeneratorsStartTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t GeneratorsStartTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t GeneratorsFinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t GeneratorsFinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UnitsLoadStartTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UnitsLoadStartTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UnitsLoadFinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UnitsLoadFinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UnitsLoadTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t UnitsLoadTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDSecurityStartTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDSecurityStartTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDSecurityFinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDSecurityFinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDGeneratorsStartTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDGeneratorsStartTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDGeneratorsFinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDGeneratorsFinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDUnitsLoadStartTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDUnitsLoadStartTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDUnitsLoadFinishTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t InitRDUnitsLoadFinishTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite s LogLevel = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite s LogTarget = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NNames = ...; readonly u NFailedUnits = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NJobs = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NInstalledJobs = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NFailedJobs = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly at TransactionsWithOrderingCycle = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly d Progress = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as Environment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ConfirmSpawn = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b ShowStatus = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as UnitPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s DefaultStandardOutput = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s DefaultStandardError = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s WatchdogDevice = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t WatchdogLastPingTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t WatchdogLastPingTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite t RuntimeWatchdogUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite t RuntimeWatchdogPreUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite s RuntimeWatchdogPreGovernor = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite t RebootWatchdogUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite t KExecWatchdogUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @org.freedesktop.systemd1.Privileged("true") readwrite b ServiceWatchdogs = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ControlGroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s SystemState = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly y ExitCode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultTimerAccuracyUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultTimeoutStartUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultTimeoutStopUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t DefaultTimeoutAbortUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultDeviceTimeoutUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultRestartUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultStartLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u DefaultStartLimitBurst = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t EventLoopRateLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u EventLoopRateLimitBurst = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DefaultIOAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DefaultIPAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DefaultMemoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DefaultTasksAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitCPU = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitCPUSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitFSIZE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitFSIZESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitDATA = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitDATASoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitSTACK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitSTACKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitCORE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitCORESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitRSS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitRSSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitNOFILE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitNOFILESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitAS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitASSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitNPROC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitNPROCSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitMEMLOCK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitMEMLOCKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitLOCKS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitLOCKSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitSIGPENDING = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitSIGPENDINGSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitMSGQUEUE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitMSGQUEUESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitNICE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitNICESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitRTPRIO = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitRTPRIOSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitRTTIME = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DefaultLimitRTTIMESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t DefaultTasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t DefaultMemoryPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DefaultMemoryPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t DefaultCPUPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DefaultCPUPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t DefaultIOPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DefaultIOPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimerSlackNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s DefaultOOMPolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i DefaultOOMScoreAdjust = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DefaultRestrictSUIDSGID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s CtrlAltDelBurstAction = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u SoftRebootsCount = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u KExecCount = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ReloadCount = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DefaultMemoryZSwapWriteback = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods Note that many of the methods exist twice: once on the Manager object and once on the respective unit objects. This is to optimize access times so that methods that belong to unit objects do not have to be called with a resolved unit path, but can be called with only the unit id, too. `GetUnit()` may be used to get the unit object path for a unit name. It takes the unit name and returns the object path. If a unit has not been loaded yet by this name this method will fail. `GetUnitByPID()` may be used to get the unit object path of the unit a process ID belongs to. It takes a UNIX PID and returns the object path. The PID must refer to an existing system process. `GetUnitByPIDFD()` may be used to query with a Linux PIDFD (see: `pidfd_open(2)`) instead of a PID, which is safer as UNIX PIDs can be recycled. The latter method returns the unit id and the invocation id together with the unit object path. `LoadUnit()` is similar to `GetUnit()` but will load the unit from disk if possible. `StartUnit()` enqueues a start job and possibly depending jobs. It takes the unit to activate and a mode string as arguments. The mode needs to be one of `replace`, `fail`, `isolate`, `ignore-dependencies`, or `ignore-requirements`. If `replace`, the method will start the unit and its dependencies, possibly replacing already queued jobs that conflict with it. If `fail`, the method will start the unit and its dependencies, but will fail if this would change an already queued job. If `isolate`, the method will start the unit in question and terminate all units that are not dependencies of it. If `ignore-dependencies`, it will start a unit but ignore all its dependencies. If `ignore-requirements`, it will start a unit but only ignore the requirement dependencies. It is not recommended to make use of the latter two options. On reply, if successful, this method returns the newly created job object which has been enqueued for asynchronous activation. Callers that want to track the outcome of the actual start operation need to monitor the result of this job. This can be achieved in a race-free manner by first subscribing to the `JobRemoved()` signal, then calling `StartUnit()` and using the returned job object to filter out unrelated `JobRemoved()` signals, until the desired one is received, which will then carry the result of the start operation. `StartUnitReplace()` is similar to `StartUnit()` but replaces a job that is queued for one unit by a job for another unit. `StartUnitWithFlags()` is similar to `StartUnit()` but allows the caller to pass an extra `flags` parameter, which does not support any flags for now, and is reserved for future extensions. `StopUnit()` is similar to `StartUnit()` but stops the specified unit rather than starting it. Note that the `isolate` mode is invalid for this method. `ReloadUnit()`, `RestartUnit()`, `TryRestartUnit()`, `ReloadOrRestartUnit()`, or `ReloadOrTryRestartUnit()` may be used to restart and/or reload a unit. These methods take similar arguments as `StartUnit()`. Reloading is done only if the unit is already running and fails otherwise. If a service is restarted that is not running, it will be started unless the "Try" flavor is used in which case a service that is not running is not affected by the restart. The "ReloadOrRestart" flavors attempt a reload if the unit supports it and use a restart otherwise. `EnqueueUnitJob()` is similar to the various `StartUnit()`/`StopUnit()`/`RestartUnit()` methods above, but provides a unified interface that operates on a single unit. The `job_type` argument selects the job type and is one of `start`, `stop`, `reload`, `restart`, `try-restart`, `reload-or-restart` or `reload-or-try-restart`. The `job_mode` argument matches the `mode` argument of `StartUnit()`. On reply the method returns the enqueued anchor job's numeric id and object path, the affected unit's id and object path, the job type actually queued (after type collapsing, e.g. `reload-or-restart` turns into `restart` or `reload`), and an array of additional jobs that were enqueued as part of the same transaction in order to satisfy dependencies. `EnqueueUnitJobMany()` is similar to `EnqueueUnitJob()`, but operates on multiple units at once. All requested units are enqueued in a single transaction, which is necessary in order to properly honour `After=`/`Before=` ordering between units passed in the same call regardless of their order in the array. The `job_type` argument is applied to each of the listed units, including the magic values `reload-or-restart` and `reload-or-try-restart` which are resolved per unit (units that support reloading get a reload job, others get a restart). The `flags` argument does not support any flags for now and must be passed as `0`; it is reserved for future extensions. On reply the method returns an array of tuples describing the anchor job that was enqueued for each requested unit: the numeric job id, the job object path, the unit id, the unit object path, and the job type that was actually queued. Note that the order of tuples in the reply is unspecified and may not correspond to the order of the input array. `EnqueueMarkedJobs()` creates reload/restart jobs for units which have been appropriately marked, see `Markers` property above. This is equivalent to calling `TryRestartUnit()` or `ReloadOrTryRestartUnit()` for the marked units. `BindMountUnit()` can be used to bind mount new files or directories into a running service mount namespace. If supported by the kernel, any prior mount on the selected target will be replaced by the new mount. If not supported, any prior mount will be over-mounted, but remain pinned and inaccessible. `MountImageUnit()` can be used to mount new images into a running service mount namespace. If supported by the kernel, any prior mount on the selected target will be replaced by the new mount. If not supported, any prior mount will be over-mounted, but remain pinned and inaccessible. `KillUnit()` may be used to kill (i.e. send a signal to) all processes of a unit. It takes the unit `name`, an enum `who` and a UNIX `signal` number to send. The `who` enum is one of `main`, `control`, `cgroup` or `all`. If `main`, only the main process of the unit is killed. If `control`, only the control process of the unit is killed. If `cgroup` is specified only the processes in the control group of the unit are killed, which might or might not include the main and control processes too. If `all`, all processes are killed, i.e. the main process, the control process and those in the control group. A `control` process is for example a process that is configured via `ExecStop=` and is spawned in parallel to the main daemon process in order to shut it down. The value may be suffixed by `-fail` in which case the operation will fail of no matching process was found (otherwise it will return successfully, executing no operation). `KillUnitSubgroup()` is just like `KillUnit()` but takes an additional path argument that selects a sub-control group of the unit's control group. Only processes in that subgroup are killed. The path my be specified with our without leading `/`, in both cases it is taken relatively to the unit's control group. If the subgroup path is specified as an empty string or as `/` it has the same effect as `KillUnit()`. If it is specified as anything else the `whom` parameter must be set to either `cgroup` or `cgroup-fail`. `QueueSignalUnit()` is similar to `KillUnit()` but may be used to enqueue a POSIX Realtime Signal (i.e. `SIGRTMIN+…` and `SIGRTMAX-…`) to the selected process(es). Takes the same parameters as `KillUnit()` with one additional argument: an integer that is passed in the `sival_int` value accompanying the queued signal. See `sigqueue(3)` for details. `GetJob()` returns the job object path for a specific job, identified by its id. `CancelJob()` cancels a specific job identified by its numeric ID. This operation is also available in the `Cancel()` method of Job objects (see below) and exists primarily to reduce the necessary round trips to execute this operation. Note that this will not have any effect on jobs whose execution has already begun. `ClearJobs()` flushes the job queue, removing all jobs that are still queued. Note that this does not have any effect on jobs whose execution has already begun. It only flushes jobs that are queued and have not yet begun execution. `ResetFailedUnit()` resets the "failed" state of a specific unit. `SetShowStatus()` configures the display of status messages during bootup and shutdown. The `mode` parameter can be set to any value that's valid for the `systemd.show_status` kernel parameter. For more information about `systemd.show_status`, see `systemd(1)`. The `mode` parameter can also be set to an empty string. When `mode` is set to an empty string, `SetShowStatus()` will reset `ShowStatus` back to its original value. You can use `SetShowStatus()` create a service that does something like this: 1. Send a D-Bus message that will turn off status messages. 2. Block until a reply to that message is received. 3. Print multiple lines without being interrupted by status messages. 4. Send a D-Bus message that will reset `ShowStatus` back to its original value. `ResetFailed()` resets the "failed" state of all units. `ListUnits()` returns an array of all currently loaded units. Note that units may be known by multiple names at the same time, and hence there might be more unit names loaded than actual units behind them. The array consists of structures with the following elements: - The primary unit name as string - The human-readable description string - The load state (i.e. whether the unit file has been loaded successfully) - The active state (i.e. whether the unit is currently started or not) - The sub state (a more fine-grained version of the active state that is specific to the unit type, which the active state is not) - A unit that is being followed in its state by this unit, if there is any, otherwise the empty string. - The unit object path - If there is a job queued for the job unit, the numeric job id, 0 otherwise - The job type as string - The job object path `ListJobs()` returns an array with all currently queued jobs. Returns an array consisting of structures with the following elements: - The numeric job id - The primary unit name for this job - The job type as string - The job state as string - The job object path - The unit object path `Subscribe()` enables most bus signals to be sent out. Clients which are interested in signals need to call this method. Signals are only sent out if at least one client invoked this method. Note that this behavior is applied to all the signals that the object in `/org/freedesktop/systemd1` may emit, including the D-Bus standard `org.freedesktop.DBus.Properties.PropertiesChanged` signal and others that do not belong to the `org.freedesktop.systemd1` interface. `Unsubscribe()` reverts the signal subscription that `Subscribe()` implements. It is not necessary to invoke `Unsubscribe()` as clients are tracked. Signals are no longer sent out as soon as all clients which previously asked for `Subscribe()` either closed their connection to the bus or invoked `Unsubscribe()`. `Dump()` returns a text dump of the internal service manager state. This is a privileged, low-level debugging interface only. The returned string is supposed to be readable exclusively by developers, and not programmatically. There's no interface stability on the returned string guaranteed, and new fields may be added any time, and old fields removed. The general structure may be rearranged drastically between releases. This is exposed by `systemd-analyze(1)`'s `dump` command. Similarly, `DumpUnitsMatchingPatterns()` returns the internal state of units whose names match the glob expressions specified in the `patterns` argument. The `DumpByFileDescriptor()`/`DumpUnitsMatchingPatternsByFileDescriptor()` methods are identical to `Dump()`/`DumpUnitsMatchingPatterns()`, but return data serialized into a file descriptor (the client should read the text data from it until hitting EOF). Given the size limits on D-Bus messages and the possibly large size of the returned strings, `DumpByFileDescriptor()`/`DumpUnitsMatchingPatternsByFileDescriptor()` are usually the preferred interface, since it ensures the data can be passed reliably from the service manager to the client. Note though that they cannot work when communicating with the service manager remotely, as file descriptors are strictly local to a system. All the `Dump*()` methods are rate limited for unprivileged users. `Reload()` may be invoked to reload all unit files. `Reexecute()` may be invoked to reexecute the main manager process. It will serialize its state, reexecute, and deserizalize the state again. This is useful for upgrades and is a more comprehensive version of `Reload()`. `Exit()` may be invoked to ask the manager to exit. This is not available for the system manager and is useful only for user session managers. `Reboot()`, `PowerOff()`, `Halt()`, `KExec()` and `SoftReboot()` may be used to ask for immediate reboot, powering down, halt, kexec based reboot, or soft reboot of the system. Note that this does not shut down any services and immediately transitions into the later shutdown operation. These functions are normally only called as the last step of shutdown and should not be called directly. To shut down the machine, it is generally a better idea to invoke `Reboot()`, `RebootWithFlags()` or `PowerOff()` on the `systemd-logind` manager object; see `org.freedesktop.login1(5)` for more information. `SoftReboot()` accepts an argument indicating the path for the root file system to activate for the next boot cycle. If an empty string is specified the `/run/nextroot/` path is used if it exists. `SwitchRoot()` may be used to transition to a new root directory. This is intended to be used in the initrd, and also to transition from the host system into a shutdown initrd. The method takes two arguments: the new root directory (which needs to be specified) and an init binary path (which may be left empty, in which case it is automatically searched for). The state of the system manager will be serialized before the transition. After the transition, the manager binary on the main system is invoked and replaces the old PID 1. All state will then be deserialized. `SetEnvironment()` may be used to alter the environment block that is passed to all spawned processes. It takes a string array of environment variable assignments. Any previously set environment variables will be overridden. `UnsetEnvironment()` may be used to unset environment variables. It takes a string array of environment variable names. All variables specified will be unset (if they have been set previously) and no longer be passed to all spawned processes. This method has no effect for variables that were previously not set, but will not fail in that case. `UnsetAndSetEnvironment()` is a combination of `UnsetEnvironment()` and `SetEnvironment()`. It takes two lists. The first list contains variables to unset, the second one contains assignments to set. If a variable is listed in both, the variable is set after this method returns, i.e. the set list overrides the unset list. `ListUnitFiles()` returns an array of unit names and their enablement status. Note that `ListUnit()` returns a list of units currently loaded into memory, while `ListUnitFiles()` returns a list of unit *files* that were found on disk. Note that while most units are read directly from a unit file with the same name, some units are not backed by files and some files (templates) cannot directly be loaded as units but need to be instantiated instead. `GetUnitFileState()` returns the current enablement status of a specific unit file. `EnableUnitFiles()` may be used to enable one or more units in the system (by creating symlinks to them in `/etc/` or `/run/`). It takes a list of unit files to enable (either just file names or full absolute paths if the unit files are residing outside the usual unit search paths) and two booleans: the first controls whether the unit shall be enabled for runtime only (true, `/run/`), or persistently (false, `/etc/`). The second one controls whether symlinks pointing to other units shall be replaced if necessary. This method returns one boolean and an array of the changes made. The boolean signals whether the unit files contained any enablement information (i.e. an \[Install\] section). The changes array consists of structures with three strings: the type of the change (one of `symlink` or `unlink`), the file name of the symlink and the destination of the symlink. Note that most of the following calls return a changes list in the same format. Similarly, `DisableUnitFiles()` disables one or more units in the system, i.e. removes all symlinks to them in `/etc/` and `/run/`. The `EnableUnitFilesWithFlags()` and `DisableUnitFilesWithFlags()` take in options as flags instead of booleans to allow for extendability, defined as follows: #define SD_SYSTEMD_UNIT_RUNTIME (UINT64_C(1) << 0) #define SD_SYSTEMD_UNIT_FORCE (UINT64_C(1) << 1) #define SD_SYSTEMD_UNIT_PORTABLE (UINT64_C(1) << 2) `SD_SYSTEMD_UNIT_RUNTIME` will enable or disable the unit for runtime only, `SD_SYSTEMD_UNIT_FORCE` controls whether symlinks pointing to other units shall be replaced if necessary. `SD_SYSTEMD_UNIT_PORTABLE` will add or remove the symlinks in `/etc/systemd/system.attached` and `/run/systemd/system.attached`. `DisableUnitFilesWithFlagsAndInstallInfo()` is similar to `DisableUnitFilesWithFlags()` and takes the same arguments, but returns a boolean to indicate whether the unit files contain any enablement information, like `EnableUnitFiles()`. The changes made are still returned in an array. Similarly, `ReenableUnitFiles()` applies the changes to one or more units that would result from disabling and enabling the unit quickly one after the other in an atomic fashion. This is useful to apply updated \[Install\] information contained in unit files. Similarly, `LinkUnitFiles()` links unit files (that are located outside of the usual unit search paths) into the unit search path. Similarly, `PresetUnitFiles()` enables/disables one or more unit files according to the preset policy. See `systemd.preset(5)` for more information. Similarly, `MaskUnitFiles()` masks unit files and `UnmaskUnitFiles()` unmasks them again. `SetDefaultTarget()` changes the `default.target` link. See `bootup(7)` for more information. `GetDefaultTarget()` retrieves the name of the unit to which `default.target` is aliased. `SetUnitProperties()` may be used to modify certain unit properties at runtime. Not all properties may be changed at runtime, but many resource management settings (primarily those listed in `systemd.resource-control(5)`) may. The changes are applied instantly and stored on disk for future boots, unless `runtime` is true, in which case the settings only apply until the next reboot. `name` is the name of the unit to modify. `properties` are the settings to set, encoded as an array of property name and value pairs. Note that this is not a dictionary! Also note that when setting array properties with this method usually results in appending to the pre-configured array. To reset the configured arrays, set the property to an empty array first and then append to it. `StartTransientUnit()` may be used to create and start a transient unit which will be released as soon as it is not running or referenced anymore or the system is rebooted. `name` is the unit name including its suffix and must be unique. `mode` is the same as in `StartUnit()`, `properties` contains properties of the unit, specified like in `SetUnitProperties()`. `aux` is currently unused and should be passed as an empty array. See the [New Control Group Interface](https://systemd.io/CONTROL_GROUP_INTERFACE) for more information how to make use of this functionality for resource control purposes. `DumpUnitFileDescriptorStore()` returns an array with information about the file descriptors currently in the file descriptor store of the specified unit. This call is equivalent to `DumpFileDescriptorStore()` on the org.freedesktop.systemd1.Service. For further details, see below. `CleanUnit()` deletes the configuration, state, logs, cache and runtime data directories and clear out the file descriptors store for the unit, as specified in the mask parameters. The possible values are `configuration`, `state`, `logs`, `cache`, `runtime`, `fdstore`, and `all`. `RemoveSubgroupFromUnit()` removes a subcgroup belonging to a unit's cgroup. Takes three arguments: the unit name (if empty defaults to the caller's unit), a cgroup path (which must start start with a slash `/`), which is taken relative to the unit's cgroup, and a flags argument (which must be zero for now). This is primarily useful for unprivileged service managers to ask the system service manager for removal of subcgroups it manages, in case one was delegated to other UIDs. ## Signals Note that most signals are sent out only after `Subscribe()` has been invoked by at least one client. Make sure to invoke this method when subscribing to these signals! `UnitNew()` and `UnitRemoved()` are sent out each time a new unit is loaded or unloaded. Note that this has little to do with whether a unit is available on disk or not, and simply reflects the units that are currently loaded into memory. The signals take two parameters: the primary unit name and the object path. `JobNew()` and `JobRemoved()` are sent out each time a new job is queued or dequeued. Both signals take the numeric job ID, the bus path and the primary unit name for this job as arguments. `JobRemoved()` also includes a result string which is one of `done`, `canceled`, `timeout`, `failed`, `dependency`, or `skipped`. `done` indicates successful execution of a job. `canceled` indicates that a job has been canceled (via `CancelJob()` above) before it finished execution (this does not necessarily mean though that the job operation is actually cancelled too, see above). `timeout` indicates that the job timeout was reached. `failed` indicates that the job failed. `dependency` indicates that a job this job depended on failed and the job hence was removed as well. `skipped` indicates that a job was skipped because it did not apply to the unit's current state. `StartupFinished()` is sent out when startup finishes. It carries six microsecond timespan values, each indicating how much boot time has been spent in the firmware (if known), in the boot loader (if known), in the kernel initialization phase, in the initrd (if known), in userspace and in total. These values may also be calculated from the `FirmwareTimestampMonotonic`, `LoaderTimestampMonotonic`, `InitRDTimestampMonotonic`, `UserspaceTimestampMonotonic`, and `FinishTimestampMonotonic` properties (see below). `UnitFilesChanged()` is sent out each time the list of enabled or masked unit files on disk have changed. `Reloading()` is sent out immediately before a daemon reload is done (with the boolean parameter set to True) and after a daemon reload is completed (with the boolean parameter set to False). This may be used by UIs to optimize UI updates. ## Properties Most properties simply reflect the respective options in `/etc/systemd/system.conf` and the kernel command line. The others: `Version` encodes the version string of the running systemd instance. Note that the version string is purely informational. It should not be parsed and one may not assume the version to be formatted in any particular way. We take the liberty to change the versioning scheme at any time and it is not part of the public API. `Features` encodes the features that have been enabled and disabled for this build. Enabled options are prefixed with `+`, disabled options with `-`. `Tainted` encodes taint flags as a colon-separated list. When systemd detects it is running on a system with a certain problem, it will set an appropriate taint flag. Taints may be used to lower the chance of bogus bug reports. The following taints are currently known: `unmerged-usr` `/bin`, `/sbin` and `/lib*` are not symlinks to their counterparts under `/usr/`. For more information on this issue consult [The Case for the /usr Merge](https://systemd.io/THE_CASE_FOR_THE_USR_MERGE). `unmerged-bin` `/usr/sbin` is not a symlink to `/usr/bin/`. `var-run-bad` `/run/` does not exist or `/var/run` is not a symlink to `/run/`. `cgroupsv1` The system is using the deprecated cgroup v1 hierarchy. `local-hwclock` The local hardware clock (RTC) is configured to be in local time rather than UTC. `support-ended` The system is running past the end of support declared by the vendor. See the description of `SUPPORT_END=` in `os-release(5)`. `old-kernel` The system is running a kernel version that is older than the minimum supported by this version of systemd. `overflowuid-not-65534`; `overflowgid-not-65534` The kernel overflow UID or GID have a value other than 65534. `short-uid-range`; `short-gid-range` The UID or GID range assigned to the running systemd instance covers less than 0…65534. `FirmwareTimestamp`, `FirmwareTimestampMonotonic`, `LoaderTimestamp`, `LoaderTimestampMonotonic`, `KernelTimestamp`, `KernelTimestampMonotonic`, `InitRDTimestamp`, `InitRDTimestampMonotonic`, `UserspaceTimestamp`, `UserspaceTimestampMonotonic`, `FinishTimestamp`, `FinishTimestampMonotonic`, `ShutdownStartTimestamp` and `ShutdownStartTimestampMonotonic` encode `CLOCK_REALTIME` and `CLOCK_MONOTONIC` microsecond timestamps taken when the firmware first began execution, when the boot loader first began execution, when the kernel first began execution, when the initrd first began execution, when the main systemd instance began execution, when all queued startup jobs finished execution and finally, when a shutdown operation first began execution. These values are useful for determining boot-time performance. Note that as monotonic time begins with the kernel startup, the `KernelTimestampMonotonic` timestamp will always be 0 and `FirmwareTimestampMonotonic` and `LoaderTimestampMonotonic` are to be read as negative values. Also, not all fields are always available, depending on the used firmware, boot loader or initrd implementation. In these cases the respective pairs of timestamps are both 0, indicating that no data is available. `ShutdownFinishTimestamp` and `ShutdownFinishTimestampMonotonic` encode `CLOCK_REALTIME` and `CLOCK_MONOTONIC` microsecond timestamps taken when all units have finished stopping during shutdown, i.e. when `shutdown.target` is reached. Together with `ShutdownStartTimestamp` (which is taken when unit stopping begins) they bracket the time spent stopping units. `PreviousShutdownStartTimestamp`, `PreviousShutdownFinishTimestamp`, `PreviousShutdownLateStartTimestamp`, `PreviousShutdownLateFinishTimestamp` and their `Monotonic` counterparts encode `CLOCK_REALTIME` and `CLOCK_MONOTONIC` microsecond timestamps describing the shutdown of the *previous* boot, restored from the Live Update Orchestrator (LUO) payload after a kexec-based live update. `PreviousShutdownStartTimestamp` and `PreviousShutdownFinishTimestamp` bracket the unit-stopping phase of that previous boot, while `PreviousShutdownLateStartTimestamp` and `PreviousShutdownLateFinishTimestamp` are taken by `systemd-shutdown` itself when it began execution and when it was about to `kexec()` into the current kernel, respectively. Unlike the current cycle's `ShutdownStartTimestamp` and `ShutdownFinishTimestamp` (which describe an in-progress shutdown of the running system), these always refer to a previous, already-completed boot, similar to the firmware, boot loader and kernel timestamps. They are populated only after a kexec-based live update and are useful for determining shutdown and live-update performance; otherwise they are all 0. `UnitsLoadTimestamp` and `UnitsLoadTimestampMonotonic` encode `CLOCK_REALTIME` and `CLOCK_MONOTONIC` microseconds timestamps (as described above). The timestamps are taken every time when the manager starts loading unit files. Similarly, the `SecurityStartTimestamp`, `GeneratorsStartTimestamp` and `LoadUnitTimestamp` (as well as their monotonic and stop counterparts) expose performance data for uploading the security policies to the kernel (such as the SELinux, IMA, or SMACK policies), for running the generator tools and for loading the unit files. `NNames` encodes how many unit names are currently known. This only includes names of units that are currently loaded and can be more than the amount of actually loaded units since units may have more than one name. `NJobs` encodes how many jobs are currently queued. `NInstalledJobs` encodes how many jobs have ever been queued in total. `NFailedJobs` encodes how many jobs have ever failed in total. `TransactionsWithOrderingCycle` encodes IDs of transactions that encountered ordering cycle. `Progress` encodes boot progress as a floating point value between 0.0 and 1.0. This value begins at 0.0 at early-boot and ends at 1.0 when boot is finished and is based on the number of executed and queued jobs. After startup, this field is always 1.0 indicating a finished boot. `Environment` encodes the environment block passed to all executed services. It may be altered with bus calls such as `SetEnvironment()` (see above). `ShowStatus` encodes systemd's current policy for displaying status messages during bootup and shutdown. Its value can be any valid value for the `systemd.show_status` kernel parameter (see `systemd(1)`). It may be altered using `SetShowStatus()` (see above). `UnitPath` encodes the currently active unit file search path. It is an array of file system paths encoded as strings. `SoftRebootsCount` encodes how many soft-reboots were successfully completed since the last full boot. Starts at `0`. `KExecCount` encodes how many kexec-based live updates were successfully completed since the last full boot. Starts at `0`. The counter is preserved across the kexec through the Live Update Orchestrator (LUO), and is hence `0` when the kernel does not provide LUO support. `ReloadCount` encodes the number of successfully completed configuration reloads of the manager. The counter is reset to `0` on `daemon-reexec` and on the initial boot. `Virtualization` contains a short ID string describing the virtualization technology the system runs in. On bare-metal hardware this is the empty string. Otherwise, it contains an identifier such as `kvm`, `vmware` and so on. For a full list of IDs see `systemd-detect-virt(1)`. Note that only the "innermost" virtualization technology is exported here. This detects both full-machine virtualizations (VMs) and shared-kernel virtualization (containers). `ConfidentialVirtualization` contains a short ID string describing the confidential virtualization technology the system runs in. On bare-metal hardware this is the empty string. Otherwise, it contains an identifier such as `sev`, `sev-es`, `sev-snp`, `tdx` and so on. For a full list of IDs see `systemd-detect-virt(1)` . `Architecture` contains a short ID string describing the architecture the systemd instance is running on. This follows the same vocabulary as `ConditionArchitectures=`. `ControlGroup` contains the root control group path of this system manager. Note that the root path is encoded as the empty string here (not as `/`!), so that it can be appended to `/sys/fs/cgroup/systemd` easily. This value will be set to the empty string for the host instance and some other string for container instances. `AccessSELinuxContext` contains the SELinux context that is used to control access to the unit. It's read from the unit file when it is loaded and cached until the service manager is reloaded. This property contains an empty string if SELinux is not used or if no label could be read (for example because the unit is not backed by a file on disk). `SystemState` contains the current state of the system manager. The possible values are: `initializing` The system is booting, and `basic.target` has not been reached yet. `starting` The system is booting, and `basic.target` has been reached. `running` The system has finished booting, and no units are in the failed state. `degraded` The system has finished booting, but some units are in the failed state. `maintenance` The system has finished booting, but it has been put in rescue or maintenance mode. `stopping` The system is shutting down. ## Security Read access is generally granted to all clients. Additionally, for unprivileged clients, some operations are allowed through the polkit privilege system. Operations which modify unit state (`StartUnit()`, `StopUnit()`, `KillUnit()`, `KillUnitSubgroup()`, `QueueSignalUnit()`, `RestartUnit()` and similar, `SetUnitProperties()`) require org.freedesktop.systemd1.manage-units. Operations which modify unit file enablement state (`EnableUnitFiles()`, `DisableUnitFiles()`, `EnableUnitFilesWithFlags()`, `DisableUnitFilesWithFlags()`, `ReenableUnitFiles()`, `LinkUnitFiles()`, `PresetUnitFiles()`, `MaskUnitFiles()`, and similar) require org.freedesktop.systemd1.manage-unit-files. Operations which modify the exported environment (`SetEnvironment()`, `UnsetEnvironment()`, `UnsetAndSetEnvironment()`) require org.freedesktop.systemd1.set-environment. `Reload()` and `Reexecute()` require org.freedesktop.systemd1.reload-daemon. Operations which dump internal state require org.freedesktop.systemd1.bypass-dump-ratelimit to avoid rate limits. # Unit Objects node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { interface org.freedesktop.systemd1.Unit { methods: Start(in s mode, out o job); Stop(in s mode, out o job); Reload(in s mode, out o job); Restart(in s mode, out o job); TryRestart(in s mode, out o job); ReloadOrRestart(in s mode, out o job); ReloadOrTryRestart(in s mode, out o job); EnqueueJob(in s job_type, in s job_mode, out u job_id, out o job_path, out s unit_id, out o unit_path, out s job_type, out a(uosos) affected_jobs); Kill(in s whom, in i signal); KillSubgroup(in s subgroup, in i signal); QueueSignal(in s whom, in i signal, in i value); ResetFailed(); SetProperties(in b runtime, in a(sv) properties); Ref(); Unref(); Clean(in as mask); Freeze(); Thaw(); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Id = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Names = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Following = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Requires = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Requisite = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Wants = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as BindsTo = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as PartOf = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Upholds = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as RequiredBy = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as RequisiteOf = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as WantedBy = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as BoundBy = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as UpheldBy = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ConsistsOf = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Conflicts = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ConflictedBy = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Before = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as After = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as OnSuccess = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as OnSuccessOf = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as OnFailure = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as OnFailureOf = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Triggers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as TriggeredBy = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as PropagatesReloadTo = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ReloadPropagatedFrom = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as PropagatesStopTo = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as StopPropagatedFrom = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as JoinsNamespaceOf = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SliceOf = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as RequiresMountsFor = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as WantsMountsFor = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Documentation = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Description = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s AccessSELinuxContext = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s LoadState = '...'; readonly s ActiveState = '...'; readonly s FreezerState = '...'; readonly s SubState = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s FragmentPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SourcePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as DropInPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s UnitFileState = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s UnitFilePreset = '...'; readonly t StateChangeTimestamp = ...; readonly t StateChangeTimestampMonotonic = ...; readonly t InactiveExitTimestamp = ...; readonly t InactiveExitTimestampMonotonic = ...; readonly t ActiveEnterTimestamp = ...; readonly t ActiveEnterTimestampMonotonic = ...; readonly t ActiveExitTimestamp = ...; readonly t ActiveExitTimestampMonotonic = ...; readonly t InactiveEnterTimestamp = ...; readonly t InactiveEnterTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CanStart = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CanStop = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CanReload = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CanIsolate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as CanClean = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CanFreeze = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CanLiveMount = ...; readonly (uo) Job = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b StopWhenUnneeded = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RefuseManualStart = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RefuseManualStop = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b AllowIsolate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DefaultDependencies = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SurviveFinalKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s OnSuccessJobMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s OnFailureJobMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b IgnoreOnIsolate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b NeedDaemonReload = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as Markers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t JobTimeoutUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t JobRunningTimeoutUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s JobTimeoutAction = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s JobTimeoutRebootArgument = '...'; readonly b ConditionResult = ...; readonly b AssertResult = ...; readonly t ConditionTimestamp = ...; readonly t ConditionTimestampMonotonic = ...; readonly t AssertTimestamp = ...; readonly t AssertTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sbbsi) Conditions = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sbbsi) Asserts = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (ss) LoadError = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b Transient = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b Perpetual = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t StartLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u StartLimitBurst = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StartLimitAction = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s FailureAction = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i FailureActionExitStatus = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SuccessAction = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SuccessActionExitStatus = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RebootArgument = '...'; readonly ay InvocationID = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s CollectMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as Refs = ['...', ...]; readonly a(ss) ActivationDetails = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b DebugInvocation = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `Start()`, `Stop()`, `Reload()`, `Restart()`, `TryRestart()`, `ReloadOrRestart()`, `ReloadOrTryRestart()`, `Kill()`, `KillSubgroup()`, `QueueSignal()`, `ResetFailed()`, and `SetProperties()` implement the same operation as the respective methods on the Manager object (see above). However, these methods operate on the unit object and hence do not take a unit name parameter. Invoking the methods directly on the Manager object has the advantage of not requiring a `GetUnit()` call to get the unit object for a specific unit name. Calling the methods on the Manager object is hence a round trip optimization. ## Properties `Id` contains the primary name of the unit. `Names` contains all names of the unit, including the primary name that is also exposed in `Id`. `Following` either contains the empty string or contains the name of another unit that this unit follows in state. This is used for some device units which reflect the unit state machine of another unit, and which other unit this is might possibly change. `Requires`, `RequiresOverridable`, `Requisite`, `RequisiteOverridable`, `Wants`, `BindsTo`, `RequiredBy`, `RequiredByOverridable`, `WantedBy`, `BoundBy`, `Conflicts`, `ConflictedBy`, `Before`, `After`, `OnFailure`, `Triggers`, `TriggeredBy`, `PropagatesReloadTo`, and `RequiresMountsFor` contain arrays which encode the dependencies and their inverse dependencies (where this applies) as configured in the unit file or determined automatically. `Description` contains the human-readable description string for the unit. `SourcePath` contains the path to a configuration file this unit is automatically generated from in case it is not a native unit (in which case it contains the empty string). For example, all mount units generated from `/etc/fstab` have this field set to `/etc/fstab`. `Documentation` contains a string array with URLs of documentation for this unit. `LoadState` contains a state value that reflects whether the configuration file of this unit has been loaded. The following states are currently defined: `loaded`, `error`, and `masked`. `loaded` indicates that the configuration was successfully loaded. `error` indicates that the configuration failed to load. The `LoadError` field (see below) contains information about the cause of this failure. `masked` indicates that the unit is currently masked out (i.e. symlinked to `/dev/null` or empty). Note that the `LoadState` is fully orthogonal to the `ActiveState` (see below) as units without valid loaded configuration might be active (because configuration might have been reloaded at a time where a unit was already active). `ActiveState` contains a state value that reflects whether the unit is currently active or not. The following states are currently defined: `SubState` encodes states of the same state machine that `ActiveState` covers, but knows more fine-grained states that are unit-type-specific. Where `ActiveState` only covers eight high-level states, `SubState` covers possibly many more low-level unit-type-specific states that are mapped to the eight high-level states. Note that multiple low-level states might map to the same high-level state, but not vice versa. Not all high-level states have low-level counterparts on all unit types. At this point the low-level states are not documented here, and are more likely to be extended later on than the common high-level states explained above. `FragmentPath` contains the unit file path this unit was read from, if there is one (if not, it contains the empty string). `UnitFileState` encodes the install state of the unit file of `FragmentPath`. It currently knows the following states: `enabled`, `enabled-runtime`, `linked`, `linked-runtime`, `masked`, `masked-runtime`, `static`, `disabled`, and `invalid`. `enabled` indicates that a unit file is permanently enabled. `enable-runtime` indicates the unit file is only temporarily enabled and will no longer be enabled after a reboot (that means, it is enabled via `/run/` symlinks, rather than `/etc/`). `linked` indicates that a unit is linked into `/etc/` permanently. `linked-runtime` indicates that a unit is linked into `/run/` temporarily (until the next reboot). `masked` indicates that the unit file is masked permanently. `masked-runtime` indicates that it is masked in `/run/` temporarily (until the next reboot). `static` indicates that the unit is statically enabled, i.e. always enabled and does not need to be enabled explicitly. `invalid` indicates that it could not be determined whether the unit file is enabled. `InactiveExitTimestamp`, `InactiveExitTimestampMonotonic`, `ActiveEnterTimestamp`, `ActiveEnterTimestampMonotonic`, `ActiveExitTimestamp`, `ActiveExitTimestampMonotonic`, `InactiveEnterTimestamp`, and `InactiveEnterTimestampMonotonic` contain `CLOCK_REALTIME` and `CLOCK_MONOTONIC` 64-bit microsecond timestamps of the last time a unit left the inactive state, entered the active state, exited the active state, or entered an inactive state. These are the points in time where the unit transitioned `inactive`/`failed` → `activating`, `activating` → `active`, `active` → `deactivating`, and finally `deactivating` → `inactive`/`failed`. The fields are 0 in case such a transition has not yet been recorded on this boot. `CanStart`, `CanStop`, and `CanReload` encode as booleans whether the unit supports the start, stop or reload operations. Even if a unit supports such an operation, the client might not necessary have the necessary privileges to execute them. `CanIsolate` encodes as a boolean whether the unit may be started in isolation mode. `Job` encodes the job ID and job object path of the job currently scheduled or executed for this unit, if there is any. If no job is scheduled or executed, the job id field will be 0. `StopWhenUnneeded`, `RefuseManualStart`, `RefuseManualStop`, `AllowIsolate`, `DefaultDependencies`, `OnFailureIsolate`, `IgnoreOnIsolate`, `IgnoreOnSnapshot` map directly to the corresponding configuration booleans in the unit file. `NeedDaemonReload` is a boolean that indicates whether the configuration file this unit is loaded from (i.e. `FragmentPath` or `SourcePath`) has changed since the configuration was read and hence whether a configuration reload is recommended. `Markers` is an array of string flags that can be set using `SetUnitProperties()` to indicate that the service should be reloaded or restarted. Currently known values are `needs-restart`, `needs-stop`, `needs-start` and `needs-reload`. Package scripts may use the first three to mark units for later restart or start or stop when a new version of the package is installed or removed. Configuration management scripts may use the fourth to mark units for a later reload when the configuration is adjusted. Those flags are not set by the manager, except to unset as appropriate when the unit is stopped, restarted, or reloaded. When markers are set, they are normalized according to the following precedence rules, modeled after the job type merging logic. When new markers are applied incrementally (using the `+` prefix), conflicting existing markers are cleared before the new markers are merged in: - `needs-reload` loses against all other markers. If any of `needs-restart`, `needs-start`, or `needs-stop` is set, `needs-reload` is cleared. - `needs-stop` wins against `needs-restart` and `needs-reload`, clearing both. - `needs-start` wins against `needs-stop`, clearing it. - `needs-restart` wins against `needs-start`. If both are set, `needs-start` is cleared. For example, if a unit currently has `needs-stop` set and a new `+needs-start` marker is applied, the existing `needs-stop` is cleared and only `needs-start` remains. Conversely, applying `+needs-stop` to any existing marker will clear all other markers, as `needs-stop` takes precedence over `needs-restart` and `needs-reload`, and the new marker clears conflicting existing ones. `JobTimeoutUSec` maps directly to the corresponding configuration setting in the unit file. `ConditionTimestamp` and `ConditionTimestampMonotonic` contain the `CLOCK_REALTIME`/`CLOCK_MONOTONIC` microsecond timestamps of the last time the configured conditions of the unit have been checked or 0 if they have never been checked. Conditions are checked when a unit is requested to start. `ConditionResult` contains the condition result of the last time the configured conditions of this unit were checked. `Conditions` contains all configured conditions of the unit. For each condition, five fields are given: condition type (e.g. `ConditionPathExists`), whether the condition is a trigger condition, whether the condition is reversed, the right hand side of the condition (e.g. the path in case of `ConditionPathExists`), and the status. The status can be 0, in which case the condition has not been checked yet, a positive value, in which case the condition passed, or a negative value, in which case the condition is not met. Currently only 0, +1, and -1 are used, but additional values may be used in the future, retaining the meaning of zero/positive/negative values. `LoadError` contains a pair of strings. If the unit failed to load (as encoded in `LoadState`, see above), then this will include a D-Bus error pair consisting of the error ID and an explanatory human-readable string of what happened. If it loaded successfully, this will be a pair of empty strings. `Transient` contains a boolean that indicates whether the unit was created as a transient unit (i.e. via `StartTransientUnit()` on the manager object). `ActivationDetails` contains a list of string pairs, key and value, that describe the event that caused the unit to be activated, if any. The key describes the information (e.g.: `trigger_unit`, with value `foo.service`). This is only filled in if the unit was triggered by a `Path` or `Timer` unit, and it is only provided in a best effort fashion: it is not guaranteed to be set, and it is not guaranteed to be the only trigger. It is only guaranteed to be a valid trigger that caused the activation job to be enqueued and complete successfully. The key value pairs correspond (in lowercase) to the environment variables described in the `Environment Variables Set or Propagated by the Service Manager` section in `systemd.exec(5)`. Note that new key value pair may be added at any time in future versions. Existing entries will not be removed. `DebugInvocation` contains a boolean that will change to `true` when the unit is restarted with log level set to debug due to an earlier failure, and will change back to `false` when either the unit successfully starts or the restart rate limit is reached. See the `RestartMode=` section in `systemd.service(5)` for more details. `OOMKills` contains a different value depending on whether `OOMPolicy=kill` is enabled for the unit or not. If enabled, the property contains the number of times the kernel OOM killer killed all the processes in the unit's cgroup and its descendant cgroups. If disabled, the property contains the number of processes the kernel OOM killer has killed in the unit's cgroup and its descendant cgroups. When the corresponding cgroups have not been realized, it reports `18446744073709551615` (`2^64 - 1`). `ManagedOOMKills` contains the number of times `systemd-oomd` killed all the processes in the unit's cgroup and its descendant cgroups. When the corresponding cgroups have not been realized yet, it reports `18446744073709551615` (`2^64 - 1`). ## Security Similarly to methods on the Manager object, read-only access is allowed for everyone. All operations are allowed for clients when the org.freedesktop.systemd1.manage-units privilege is granted by polkit. # Service Unit Objects All service unit objects implement the org.freedesktop.systemd1.Service interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { interface org.freedesktop.systemd1.Service { methods: BindMount(in s source, in s destination, in b read_only, in b mkdir); MountImage(in s source, in s destination, in b read_only, in b mkdir, in a(ss) options); DumpFileDescriptorStore(out a(suuutuusu) entries); GetProcesses(out a(sus) processes); AttachProcesses(in s subcgroup, in au pids); RemoveSubgroup(in s subcgroup, in t flags); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Type = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ExitType = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Restart = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RestartMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PIDFile = '...'; readonly s NotifyAccess = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RestartUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u RestartSteps = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RestartMaxDelayUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RestartRandomizedDelayUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t RestartUSecNext = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutStartUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutStopUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TimeoutAbortUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s TimeoutStartFailureMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s TimeoutStopFailureMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RuntimeMaxUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RuntimeRandomizedExtraUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t WatchdogUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t WatchdogTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t WatchdogTimestampMonotonic = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RootDirectoryStartOnly = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RemainAfterExit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b GuessMainPID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (aiai) RestartPreventExitStatus = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (aiai) RestartForceExitStatus = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (aiai) SuccessExitStatus = ...; readonly u MainPID = ...; readonly u ControlPID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BusName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u FileDescriptorStoreMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NFileDescriptorStore = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s FileDescriptorStorePreserve = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as LUOSession = ['...', ...]; readonly s StatusText = '...'; readonly i StatusErrno = ...; readonly s StatusBusError = '...'; readonly s StatusVarlinkError = '...'; readonly s Result = '...'; readonly s ReloadResult = '...'; readonly s CleanResult = '...'; readonly s LiveMountResult = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s USBFunctionDescriptors = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s USBFunctionStrings = '...'; readonly u UID = ...; readonly u GID = ...; readonly u NRestarts = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s OOMPolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) OpenFile = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExtraFileDescriptorNames = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i ReloadSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as RefreshOnReload = ['...', ...]; readonly t ExecMainStartTimestamp = ...; readonly t ExecMainStartTimestampMonotonic = ...; readonly t ExecMainExitTimestamp = ...; readonly t ExecMainExitTimestampMonotonic = ...; readonly t ExecMainHandoffTimestamp = ...; readonly t ExecMainHandoffTimestampMonotonic = ...; readonly u ExecMainPID = ...; readonly i ExecMainCode = ...; readonly i ExecMainStatus = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecCondition = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasasttttuii) ExecConditionEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecStartPre = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasasttttuii) ExecStartPreEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecStart = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasasttttuii) ExecStartEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecStartPost = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasasttttuii) ExecStartPostEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecReload = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasasttttuii) ExecReloadEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecReloadPost = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasasttttuii) ExecReloadPostEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecStop = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasasttttuii) ExecStopEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecStopPost = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasasttttuii) ExecStopPostEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Slice = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ControlGroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ControlGroupId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryAvailable = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUUsageNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveTasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t OOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b Delegate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DelegateControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DelegateSubgroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupCPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPerSecUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPeriodUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUSetPartition = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IOAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupIOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceWeight = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceLatencyTargetUSec = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMin = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryZSwapWriteback = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DevicePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) DeviceAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b TasksAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IPAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPIngressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPEgressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DisableControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMSwap = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMMemoryPressure = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u ManagedOOMMemoryPressureLimit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMMemoryPressureDurationUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMPreference = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as OOMRules = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) BPFProgram = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (bas) RestrictNetworkInterfaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s BindNetworkInterface = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s MemoryPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s IOPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiss) NFTSet = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b CoredumpReceive = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Environment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sb) EnvironmentFiles = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as PassEnvironment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as UnsetEnvironment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u UMask = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCPU = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCPUSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitFSIZE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitFSIZESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitDATA = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitDATASoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSTACK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSTACKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCORE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCORESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRSS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRSSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNOFILE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNOFILESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitAS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitASSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNPROC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNPROCSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMEMLOCK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMEMLOCKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitLOCKS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitLOCKSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSIGPENDING = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSIGPENDINGSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMSGQUEUE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMSGQUEUESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNICE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNICESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTPRIO = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTPRIOSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTTIME = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTTIMESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s WorkingDirectory = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootDirectory = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootImage = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) RootImageOptions = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay RootHash = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootHashPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay RootHashSignature = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootHashSignaturePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootVerity = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RootEphemeral = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootMStack = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExtensionDirectories = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sba(ss)) ExtensionImages = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssba(ss)) MountImages = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i OOMScoreAdjust = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t CoredumpFilter = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i Nice = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IOSchedulingClass = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IOSchedulingPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i CPUSchedulingPolicy = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i CPUSchedulingPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay CPUAffinity = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CPUAffinityFromNUMA = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i NUMAPolicy = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay NUMAMask = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimerSlackNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CPUSchedulingResetOnFork = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b NonBlocking = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardInput = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardInputFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay StandardInputData = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardOutput = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardOutputFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardError = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardErrorFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s TTYPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYReset = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYVHangup = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYVTDisallocate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly q TTYRows = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly q TTYColumns = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SyslogIdentifier = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SyslogLevelPrefix = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogLevel = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogFacility = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i LogLevelMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LogRateLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u LogRateLimitBurst = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly aay LogExtraFields = [[...], ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(bs) LogFilterPatterns = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s LogNamespace = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SecureBits = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t CapabilityBoundingSet = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t AmbientCapabilities = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s User = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Group = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DynamicUser = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SetLoginEnvironment = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RemoveIPC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(say) SetCredential = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(say) SetCredentialEncrypted = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) LoadCredential = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) LoadCredentialEncrypted = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ImportCredential = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) ImportCredentialEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SupplementaryGroups = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PAMName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ReadWritePaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ReadOnlyPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as InaccessiblePaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExecPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as NoExecPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExecSearchPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t MountFlags = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateTmp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateTmpEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateDevices = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectClock = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelTunables = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelModules = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelLogs = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectControlGroups = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectControlGroupsEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateNetwork = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateUsers = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateUsersEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateMounts = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateIPC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivatePIDs = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectHome = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectSystem = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SameProcessGroup = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UtmpIdentifier = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UtmpMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) SELinuxContext = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) AppArmorProfile = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) SmackProcessLabel = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b IgnoreSIGPIPE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b NoNewPrivileges = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) SystemCallFilter = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SystemCallArchitectures = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SystemCallErrorNumber = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) SystemCallLog = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Personality = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b LockPersonality = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) RestrictAddressFamilies = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) RuntimeDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RuntimeDirectoryPreserve = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u RuntimeDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as RuntimeDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) StateDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u StateDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b StateDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) StateDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as StateDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) CacheDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u CacheDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CacheDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) CacheDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as CacheDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) LogsDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u LogsDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b LogsDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) LogsDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as LogsDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) ConfigurationDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u ConfigurationDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ConfigurationDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutCleanUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MemoryDenyWriteExecute = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RestrictRealtime = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RestrictSUIDSGID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RestrictNamespaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DelegateNamespaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) RestrictFileSystems = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssbt) BindPaths = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssbt) BindReadOnlyPaths = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) TemporaryFileSystem = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MountAPIVFS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b BindLogSockets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KeyringMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectProc = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProcSubset = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectHostname = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (ss) ProtectHostnameEx = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateBPF = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateCommands = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateMaps = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegatePrograms = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateAttachments = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MemoryKSM = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s MemoryTHP = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UserNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s NetworkNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s MountImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ExtensionImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) StateDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) CacheDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) LogsDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i RestartKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i FinalKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGKILL = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGHUP = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i WatchdogSignal = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; ## Methods `BindMount()` and `MountImage()` implement the same operations as the respective methods on the Manager object (see above). However, these methods operate on the service object and hence do not take a unit name parameter. Invoking the methods directly on the Manager object has the advantage of not requiring a `GetUnit()` call to get the unit object for a specific unit name. Calling the methods on the Manager object is hence a round trip optimization. `DumpFileDescriptorStore()` returns an array with information about the file descriptors currently in the file descriptor store of the service. Each entry consists of a file descriptor name (i.e. the `FDNAME=` field), the file descriptor inode type and access mode as integer (i.e. a `mode_t` value, flags such as `S_IFREG`, `S_IRUSR`, …), the major and minor numbers of the device number of the file system backing the inode of the file descriptor, the inode number, the major and minor numbers of the device number if this refers to a character or block device node, a file system path pointing to the inode, and the file descriptor flags (i.e. `O_RDWR`, `O_RDONLY`, …). ## Properties Most properties of the Service interface map directly to the corresponding settings in service unit files. For the sake of brevity, here's a list of all exceptions only: `TimeoutStartUSec`, `TimeoutStopUSec` and `TimeoutAbortUSec` contain the start, stop and abort timeouts, in microseconds. Note the slight difference in naming when compared to the matching unit file settings (see `systemd.service(5)`): these bus properties strictly use microseconds (and thus are suffixed `…USec`) while the unit file settings default to a time unit of seconds (and thus are suffixed `…Sec`), unless a different unit is explicitly specified. This reflects that fact that internally the service manager deals in microsecond units only, and the bus properties are a relatively low-level (binary) concept exposing this. The unit file settings on the other hand are relatively high-level (string-based) concepts and thus support more user friendly time specifications which default to second time units but allow other units too, if specified. `WatchdogTimestamp` and `WatchdogTimestampMonotonic` contain `CLOCK_REALTIME`/`CLOCK_MONOTONIC` microsecond timestamps of the last watchdog ping received from the service, or 0 if none was ever received. `ExecStartPre`, `ExecStart`, `ExecStartPost`, `ExecReload`, `ExecReloadPost`, `ExecStop`, and `ExecStopPost` are arrays of structures where each struct contains: the binary path to execute; an array with all arguments to pass to the executed command, starting with argument 0; a boolean whether it should be considered a failure if the process exits uncleanly; two pairs of `CLOCK_REALTIME`/`CLOCK_MONOTONIC` microsecond timestamps when the process began and finished running the last time, or 0 if it never ran or never finished running; the PID of the process, or 0 if it has not run yet; the exit code and status of the last run. This field hence maps more or less to the corresponding setting in the service unit file but is augmented with runtime data. `LimitCPU` (and related properties) map more or less directly to the corresponding settings in the service unit files except that if they are not set their value is 18446744073709551615 (i.e. -1). `Capabilities` contains the configured capabilities, as formatted with `cap_to_text(3)`. `SecureBits`, `CapabilityBoundingSet`, `MountFlags` also correspond to the configured settings of the unit files, but instead of being formatted as strings, they are encoded as the actual binary flags they are. `ExecMainStartTimestamp`, `ExecMainStartTimestampMonotonic`, `ExecMainExitTimestamp`, `ExecMainExitTimestampMonotonic`, `ExecMainHandoffTimestamp`, `ExecMainHandoffTimestampMonotonic`, `ExecMainPID`, `ExecMainCode`, `ExecMainStatus` contain information about the main process of the service as far as it is known. The `ExecMainStartTimestamp` timestamps record when the main process of the service is created. `ExecMainExitTimestamp` timestamps record when the main process exit has been detected by the service manager. `ExecMainHandoffTimestamp` timestamps records when the service binary is about to be executed by `systemd-executor` (this timestamp is recorded regardless if the immediately following `execve()` system call succeeds or fails). This is often the same runtime information that is also maintained for `ExecStart=`. However, it deviates for services with `Type=forking` as well as services that use `MAINPID=` `sd_notify()` messages as the main process of the service is not forked off by the service manager directly in that case. These fields either contain information of the last run of the process or of the current running process. `MainPID` and `ControlPID` contain the main and control PID of the service. The main PID is the current main PID of the service and is 0 when the service currently has no main PID. The control PID is the PID of the current start/stop/reload process running and is 0 if no such process is currently running. That means that `ExecMainPID` and `MainPID` differ in the way that the latter immediately reflects whether a main process is currently running while the former possibly contains information collected from the last run even if the process is no longer around. `StatusText`, `StatusErrno`, `StatusBusError`, and `StatusVarlinkError` contain the status text, the error number, and the D-Bus/Varlink error name passed to the service manager via `sd_notify(3)`, respectively. They may be used by services to inform the service manager about its internal state. `Result` encodes the execution result of the last run of the service. It is useful to determine the reason a service failed if it is in the `failed` state (see `ActiveState` above). The following values are currently known: `success` is set if the unit did not fail. `resources` indicates that not enough resources were available to fork off and execute the service processes. `timeout` indicates that a timeout occurred while executing a service operation. `exit-code` indicates that a service process exited with an unclean exit code. `signal` indicates that a service process exited with an uncaught signal. `core-dump` indicates that a service process exited uncleanly and dumped core. `watchdog` indicates that a service did not send out watchdog ping messages often enough. `start-limit-hit` indicates that a service has been started too frequently in a specific time frame (as configured in `StartLimitInterval`, `StartLimitBurst`). `oom-kill` indicates that a service was terminated due to an out-of-memory (OOM) situation. `ControlGroup` indicates the control group path the processes of this service unit are placed in. The following properties map 1:1 to corresponding settings in the unit file: `RootDirectory` `RootImage` `RootImageOptions` `RootVerity` `RootHash` `RootHashSignature` `MountImages` `ExtensionImages` `ExtensionDirectories` `RootMStack` see systemd.exec(5) for their meaning. `MemoryAvailable` takes into account unit's and parents' `MemoryMax` or `MemoryHigh` or physically available RAM versus given level's memory consumption and takes minimum. Beware that other units below the tightest parent slice may consume the memory quicker and less than reported value would remain for own allocation. It works better in conjunction with `MemoryAccounting=yes` on involved units. `DelegateSubgroup` contains the cgroup subgroup to place invoked unit processes in. As configured by the option of the same name in unit files. This is set to the empty string when it does not apply or no subgroup has been configured. `RuntimeDirectorySymlink`, `StateDirectorySymlink`, `CacheDirectorySymlink` and `LogsDirectorySymlink` respectively implement the destination parameter of the unit files settings `RuntimeDirectory`, `StateDirectory`, `CacheDirectory` and `LogsDirectory`, which will create a symlink of the given name to the respective directory. The messages take a `flags` parameter that make the directory read only: #define SD_EXEC_DIRECTORY_READ_ONLY (UINT64_C(1) << 0) `ConfigurationDirectory` lists the configuration directories of the unit, as configured by the unit file setting of the same name, and `ConfigurationDirectorySymlink` exposes the same `flags` parameter for them. Unlike the other directory types, `ConfigurationDirectory` does not support symlinks, so the destination member of `ConfigurationDirectorySymlink` must be left empty and is always returned as an empty string. The property retains the same tuple signature and naming convention as the other directory types so clients can handle their flags uniformly. `ExtraFileDescriptorNames` contains file descriptor names passed to the service via the `ExtraFileDescriptors` property in the `StartTransientUnit()` method. See `sd_listen_fds(3)` for more details on how to retrieve these file descriptors. Unlike the `ExtraFileDescriptors` input property, `ExtraFileDescriptorNames` only contains names and not the file descriptors. `ManagedOOMMemoryPressureDurationUSec` implements the destination parameter of the unit file setting `ManagedOOMMemoryPressureDurationSec=` listed in `systemd.resource-control(5)`. Note the time unit is expressed in `μs`. `ProtectControlGroupsEx` implements the destination parameter of the unit file setting `ProtectControlGroups=` listed in `systemd.exec(5)`. Unlike boolean `ProtectControlGroups`, `ProtectControlGroupsEx` is a string type. `PrivatePIDs` implements the destination parameter of the unit file setting `PrivatePIDs=` listed in `systemd.exec(5)`. Note `PrivatePIDs` is a string type to allow adding more values in the future. `ProtectHostnameEx` implements the destination parameter of the unit file setting `ProtectHostname=` listed in `systemd.exec(5)`. Unlike boolean `ProtectHostname`, `ProtectHostnameEx` is a pair of strings, the first one is a boolean string or special value `private`, and the second one is an optional private hostname that will be set in a new UTS namespace for the unit. # Socket Unit Objects node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { interface org.freedesktop.systemd1.Socket { methods: GetProcesses(out a(sus) processes); AttachProcesses(in s subcgroup, in au pids); RemoveSubgroup(in s subcgroup, in t flags); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BindIPv6Only = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u Backlog = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BindToDevice = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SocketUser = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SocketGroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u SocketMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u DirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b Accept = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b FlushPending = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b Writable = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b KeepAlive = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t KeepAliveTimeUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t KeepAliveIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u KeepAliveProbes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DeferAcceptUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b NoDelay = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i Priority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t ReceiveBuffer = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t SendBuffer = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IPTOS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IPTTL = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PipeSize = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b FreeBind = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b Transparent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b Broadcast = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PassCredentials = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PassPIDFD = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PassSecurity = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PassPacketInfo = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b AcceptFileDescriptors = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Timestamping = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RemoveOnStop = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) Listen = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Symlinks = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) XAttrEntryPoint = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) XAttrListen = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) XAttrAccept = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i Mark = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u MaxConnections = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u MaxConnectionsPerSource = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly x MessageQueueMaxMessages = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly x MessageQueueMessageSize = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s TCPCongestion = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ReusePort = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SmackLabel = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SmackLabelIPIn = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SmackLabelIPOut = '...'; readonly u ControlPID = ...; readonly s Result = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NConnections = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NAccepted = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NRefused = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s FileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SocketProtocol = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TriggerLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u TriggerLimitBurst = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PollLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u PollLimitBurst = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s DeferTrigger = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DeferTriggerMaxUSec = ...; readonly u UID = ...; readonly u GID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PassFileDescriptorsToExec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecStartPre = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecStartPost = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecStopPre = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecStopPost = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Slice = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ControlGroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ControlGroupId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryAvailable = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUUsageNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveTasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t OOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b Delegate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DelegateControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DelegateSubgroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupCPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPerSecUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPeriodUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUSetPartition = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IOAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupIOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceWeight = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceLatencyTargetUSec = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMin = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryZSwapWriteback = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DevicePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) DeviceAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b TasksAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IPAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPIngressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPEgressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DisableControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMSwap = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMMemoryPressure = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u ManagedOOMMemoryPressureLimit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMMemoryPressureDurationUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMPreference = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as OOMRules = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) BPFProgram = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (bas) RestrictNetworkInterfaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s BindNetworkInterface = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s MemoryPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s IOPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiss) NFTSet = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b CoredumpReceive = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Environment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sb) EnvironmentFiles = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as PassEnvironment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as UnsetEnvironment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u UMask = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCPU = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCPUSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitFSIZE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitFSIZESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitDATA = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitDATASoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSTACK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSTACKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCORE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCORESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRSS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRSSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNOFILE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNOFILESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitAS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitASSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNPROC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNPROCSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMEMLOCK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMEMLOCKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitLOCKS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitLOCKSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSIGPENDING = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSIGPENDINGSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMSGQUEUE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMSGQUEUESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNICE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNICESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTPRIO = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTPRIOSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTTIME = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTTIMESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s WorkingDirectory = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootDirectory = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootImage = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) RootImageOptions = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay RootHash = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootHashPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay RootHashSignature = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootHashSignaturePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootVerity = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RootEphemeral = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootMStack = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExtensionDirectories = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sba(ss)) ExtensionImages = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssba(ss)) MountImages = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i OOMScoreAdjust = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t CoredumpFilter = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i Nice = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IOSchedulingClass = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IOSchedulingPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i CPUSchedulingPolicy = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i CPUSchedulingPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay CPUAffinity = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CPUAffinityFromNUMA = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i NUMAPolicy = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay NUMAMask = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimerSlackNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CPUSchedulingResetOnFork = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b NonBlocking = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardInput = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardInputFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay StandardInputData = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardOutput = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardOutputFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardError = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardErrorFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s TTYPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYReset = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYVHangup = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYVTDisallocate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly q TTYRows = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly q TTYColumns = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SyslogIdentifier = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SyslogLevelPrefix = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogLevel = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogFacility = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i LogLevelMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LogRateLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u LogRateLimitBurst = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly aay LogExtraFields = [[...], ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(bs) LogFilterPatterns = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s LogNamespace = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SecureBits = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t CapabilityBoundingSet = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t AmbientCapabilities = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s User = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Group = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DynamicUser = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SetLoginEnvironment = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RemoveIPC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(say) SetCredential = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(say) SetCredentialEncrypted = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) LoadCredential = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) LoadCredentialEncrypted = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ImportCredential = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) ImportCredentialEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SupplementaryGroups = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PAMName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ReadWritePaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ReadOnlyPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as InaccessiblePaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExecPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as NoExecPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExecSearchPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t MountFlags = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateTmp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateTmpEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateDevices = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectClock = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelTunables = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelModules = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelLogs = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectControlGroups = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectControlGroupsEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateNetwork = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateUsers = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateUsersEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateMounts = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateIPC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivatePIDs = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectHome = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectSystem = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SameProcessGroup = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UtmpIdentifier = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UtmpMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) SELinuxContext = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) AppArmorProfile = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) SmackProcessLabel = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b IgnoreSIGPIPE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b NoNewPrivileges = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) SystemCallFilter = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SystemCallArchitectures = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SystemCallErrorNumber = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) SystemCallLog = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Personality = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b LockPersonality = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) RestrictAddressFamilies = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) RuntimeDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RuntimeDirectoryPreserve = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u RuntimeDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as RuntimeDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) StateDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u StateDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b StateDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) StateDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as StateDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) CacheDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u CacheDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CacheDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) CacheDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as CacheDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) LogsDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u LogsDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b LogsDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) LogsDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as LogsDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) ConfigurationDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u ConfigurationDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ConfigurationDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutCleanUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MemoryDenyWriteExecute = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RestrictRealtime = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RestrictSUIDSGID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RestrictNamespaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DelegateNamespaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) RestrictFileSystems = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssbt) BindPaths = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssbt) BindReadOnlyPaths = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) TemporaryFileSystem = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MountAPIVFS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b BindLogSockets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KeyringMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectProc = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProcSubset = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectHostname = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (ss) ProtectHostnameEx = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateBPF = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateCommands = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateMaps = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegatePrograms = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateAttachments = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MemoryKSM = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s MemoryTHP = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UserNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s NetworkNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s MountImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ExtensionImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) StateDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) CacheDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) LogsDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i RestartKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i FinalKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGKILL = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGHUP = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i WatchdogSignal = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; The `PollLimitIntervalUSec` and `PollLimitBurst` properties configure the polling limit for the socket unit. Expects a time in µs and unsigned integer, respectively. If either is set to zero the limiting feature is turned off. ## Properties Most of the properties map directly to the corresponding settings in socket unit files. As socket units can include `ExecStartPre` (and similar) fields which contain information about processes to execute. They also share most of the fields related to the execution context that Service objects expose (see above). In addition to these properties there are the following: `NAccepted` contains the accumulated number of connections ever accepted on this socket. This only applies to sockets with `Accept` set to `yes`, i.e. those where systemd is responsible for accepted connections. Similarly `NConnections` contains the number of currently open connections on this socket. It only applies only to socket units with `Accept` set to `yes`. `Result` encodes the reason why a socket unit failed if it is in the `failed` state (see `ActiveState` above). The values `success`, `resources`, `timeout`, `exit-code`, `signal` and `core-dump` have the same meaning as they have for the corresponding field of service units (see above). In addition to that, the value `service-failed-permanent` indicates that the service of this socket failed continuously. `FlushPending` specifies whether to flush the socket just before entering the listening state. This setting only applies to sockets with `Accept=` set to `no`. `XAttrEntryPoint`, `XAttrListen` and `XAttrAccept` each contain a list of extended attributes (as `NAME`/`VALUE` pairs) to set on socket inodes. `XAttrEntryPoint` applies to the file-system inode an `AF_UNIX` socket is bound to, `XAttrListen` applies to the listening socket, and `XAttrAccept` applies to connection sockets accepted off the listening socket. See the `XAttrEntryPoint=`, `XAttrListen=` and `XAttrAccept=` settings in `systemd.socket(5)` for details. # Target Unit Objects node /org/freedesktop/systemd1/unit/basic_2etarget { interface org.freedesktop.systemd1.Target { }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; Target units have neither type-specific methods nor properties. # Device Unit Objects All device unit objects implement the org.freedesktop.systemd1.Device interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). node /org/freedesktop/systemd1/unit/dev_2dttyS0_2edevice { interface org.freedesktop.systemd1.Device { properties: readonly s SysFSPath = '...'; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; ## Properties Device units only expose a single type-specific property: `SysFSPath` contains the sysfs path of the kernel device this object corresponds to. # Mount Unit Objects All mount unit objects implement the org.freedesktop.systemd1.Mount interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). node /org/freedesktop/systemd1/unit/home_2emount { interface org.freedesktop.systemd1.Mount { methods: GetProcesses(out a(sus) processes); AttachProcesses(in s subcgroup, in au pids); RemoveSubgroup(in s subcgroup, in t flags); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Where = '...'; readonly s What = '...'; readonly s Options = '...'; readonly s Type = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutUSec = ...; readonly u ControlPID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u DirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SloppyOptions = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b LazyUnmount = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ForceUnmount = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ReadWriteOnly = ...; readonly s Result = '...'; readonly s ReloadResult = '...'; readonly s CleanResult = '...'; readonly u UID = ...; readonly u GID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecMount = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecUnmount = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecRemount = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Slice = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ControlGroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ControlGroupId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryAvailable = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUUsageNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveTasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t OOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b Delegate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DelegateControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DelegateSubgroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupCPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPerSecUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPeriodUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUSetPartition = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IOAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupIOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceWeight = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceLatencyTargetUSec = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMin = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryZSwapWriteback = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DevicePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) DeviceAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b TasksAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IPAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPIngressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPEgressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DisableControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMSwap = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMMemoryPressure = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u ManagedOOMMemoryPressureLimit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMMemoryPressureDurationUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMPreference = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as OOMRules = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) BPFProgram = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (bas) RestrictNetworkInterfaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s BindNetworkInterface = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s MemoryPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s IOPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiss) NFTSet = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b CoredumpReceive = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Environment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sb) EnvironmentFiles = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as PassEnvironment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as UnsetEnvironment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u UMask = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCPU = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCPUSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitFSIZE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitFSIZESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitDATA = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitDATASoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSTACK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSTACKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCORE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCORESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRSS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRSSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNOFILE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNOFILESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitAS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitASSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNPROC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNPROCSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMEMLOCK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMEMLOCKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitLOCKS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitLOCKSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSIGPENDING = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSIGPENDINGSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMSGQUEUE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMSGQUEUESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNICE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNICESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTPRIO = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTPRIOSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTTIME = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTTIMESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s WorkingDirectory = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootDirectory = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootImage = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) RootImageOptions = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay RootHash = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootHashPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay RootHashSignature = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootHashSignaturePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootVerity = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RootEphemeral = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootMStack = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExtensionDirectories = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sba(ss)) ExtensionImages = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssba(ss)) MountImages = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i OOMScoreAdjust = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t CoredumpFilter = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i Nice = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IOSchedulingClass = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IOSchedulingPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i CPUSchedulingPolicy = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i CPUSchedulingPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay CPUAffinity = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CPUAffinityFromNUMA = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i NUMAPolicy = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay NUMAMask = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimerSlackNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CPUSchedulingResetOnFork = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b NonBlocking = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardInput = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardInputFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay StandardInputData = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardOutput = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardOutputFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardError = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardErrorFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s TTYPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYReset = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYVHangup = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYVTDisallocate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly q TTYRows = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly q TTYColumns = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SyslogIdentifier = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SyslogLevelPrefix = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogLevel = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogFacility = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i LogLevelMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LogRateLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u LogRateLimitBurst = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly aay LogExtraFields = [[...], ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(bs) LogFilterPatterns = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s LogNamespace = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SecureBits = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t CapabilityBoundingSet = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t AmbientCapabilities = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s User = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Group = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DynamicUser = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SetLoginEnvironment = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RemoveIPC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(say) SetCredential = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(say) SetCredentialEncrypted = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) LoadCredential = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) LoadCredentialEncrypted = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ImportCredential = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) ImportCredentialEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SupplementaryGroups = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PAMName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ReadWritePaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ReadOnlyPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as InaccessiblePaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExecPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as NoExecPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExecSearchPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t MountFlags = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateTmp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateTmpEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateDevices = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectClock = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelTunables = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelModules = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelLogs = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectControlGroups = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectControlGroupsEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateNetwork = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateUsers = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateUsersEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateMounts = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateIPC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivatePIDs = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectHome = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectSystem = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SameProcessGroup = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UtmpIdentifier = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UtmpMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) SELinuxContext = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) AppArmorProfile = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) SmackProcessLabel = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b IgnoreSIGPIPE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b NoNewPrivileges = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) SystemCallFilter = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SystemCallArchitectures = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SystemCallErrorNumber = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) SystemCallLog = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Personality = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b LockPersonality = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) RestrictAddressFamilies = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) RuntimeDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RuntimeDirectoryPreserve = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u RuntimeDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as RuntimeDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) StateDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u StateDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b StateDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) StateDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as StateDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) CacheDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u CacheDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CacheDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) CacheDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as CacheDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) LogsDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u LogsDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b LogsDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) LogsDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as LogsDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) ConfigurationDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u ConfigurationDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ConfigurationDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutCleanUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MemoryDenyWriteExecute = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RestrictRealtime = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RestrictSUIDSGID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RestrictNamespaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DelegateNamespaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) RestrictFileSystems = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssbt) BindPaths = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssbt) BindReadOnlyPaths = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) TemporaryFileSystem = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MountAPIVFS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b BindLogSockets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KeyringMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectProc = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProcSubset = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectHostname = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (ss) ProtectHostnameEx = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateBPF = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateCommands = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateMaps = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegatePrograms = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateAttachments = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MemoryKSM = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s MemoryTHP = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UserNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s NetworkNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s MountImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ExtensionImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) StateDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) CacheDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) LogsDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i RestartKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i FinalKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGKILL = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGHUP = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i WatchdogSignal = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; ## Properties Most of the properties map directly to the corresponding settings in mount unit files. As mount units invoke the `/usr/bin/mount` command, their bus objects include implicit `ExecMount` (and similar) fields which contain information about processes to execute. They also share most of the fields related to the execution context that Service objects expose (see above). In addition to these properties there are the following: `ControlPID` contains the PID of the currently running `/usr/bin/mount` or `/usr/bin/umount` command if there is one running, otherwise 0. `Result` contains a value explaining why a mount unit failed if it failed. It can take the values `success`, `resources`, `timeout`, `exit-code`, `signal`, or `core-dump` which have the identical meaning as the corresponding values of the corresponding field of service unit objects (see above). # Automount Unit Objects All automount unit objects implement the org.freedesktop.systemd1.Automount interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount { interface org.freedesktop.systemd1.Automount { properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Where = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ExtraOptions = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u DirectoryMode = ...; readonly s Result = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutIdleUSec = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; ## Properties Most of the properties map directly to the corresponding settings in the automount unit files. `Result` knows the values `success` and `resources` at this time. They have the same meanings as the corresponding values of the corresponding field of the Service object. # Timer Unit Objects All timer unit objects implement the org.freedesktop.systemd1.Timer interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer { interface org.freedesktop.systemd1.Timer { properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Unit = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(stt) TimersMonotonic = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sst) TimersCalendar = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b OnClockChange = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b OnTimezoneChange = ...; readonly t NextElapseUSecRealtime = ...; readonly t NextElapseUSecMonotonic = ...; readonly t LastTriggerUSec = ...; readonly t LastTriggerUSecMonotonic = ...; readonly s Result = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t AccuracyUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RandomizedDelayUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RandomizedOffsetUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b FixedRandomDelay = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b Persistent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b WakeSystem = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RemainAfterElapse = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DeferReactivation = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; ## Properties `Unit` contains the name of the unit to activate when the timer elapses. `TimersMonotonic` contains an array of structs that contain information about all monotonic timers of this timer unit. The structs contain a string identifying the timer base, which is one of `OnActiveUSec`, `OnBootUSec`, `OnStartupUSec`, `OnUnitActiveUSec`, or `OnUnitInactiveUSec` which correspond to the settings of the same names in the timer unit files; the microsecond offset from this timer base in monotonic time; the next elapsation point on the `CLOCK_MONOTONIC` clock, relative to its epoch. `TimersCalendar` contains an array of structs that contain information about all realtime/calendar timers of this timer unit. The structs contain a string identifying the timer base, which may only be `OnCalendar` for now; the calendar specification string; the next elapsation point on the `CLOCK_REALTIME` clock, relative to its epoch. `NextElapseUSecRealtime` contains the next elapsation point on the `CLOCK_REALTIME` clock in microseconds since the epoch, or 0 if this timer event does not include at least one calendar event. Similarly, `NextElapseUSecMonotonic` contains the next elapsation point on the `CLOCK_MONOTONIC` clock in microseconds since the epoch, or 0 if this timer event does not include at least one monotonic event. `Result` knows the values `success` and `resources` with the same meanings as the matching values of the corresponding property of the service interface. # Swap Unit Objects All swap unit objects implement the org.freedesktop.systemd1.Swap interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { interface org.freedesktop.systemd1.Swap { methods: GetProcesses(out a(sus) processes); AttachProcesses(in s subcgroup, in au pids); RemoveSubgroup(in s subcgroup, in t flags); properties: readonly s What = '...'; readonly i Priority = ...; readonly s Options = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutUSec = ...; readonly u ControlPID = ...; readonly s Result = '...'; readonly u UID = ...; readonly u GID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecActivate = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") readonly a(sasbttttuii) ExecDeactivate = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Slice = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ControlGroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ControlGroupId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryAvailable = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUUsageNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveTasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t OOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b Delegate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DelegateControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DelegateSubgroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupCPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPerSecUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPeriodUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUSetPartition = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IOAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupIOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceWeight = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceLatencyTargetUSec = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMin = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryZSwapWriteback = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DevicePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) DeviceAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b TasksAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IPAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPIngressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPEgressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DisableControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMSwap = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMMemoryPressure = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u ManagedOOMMemoryPressureLimit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMMemoryPressureDurationUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMPreference = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as OOMRules = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) BPFProgram = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (bas) RestrictNetworkInterfaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s BindNetworkInterface = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s MemoryPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s IOPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiss) NFTSet = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b CoredumpReceive = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as Environment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sb) EnvironmentFiles = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as PassEnvironment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as UnsetEnvironment = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u UMask = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCPU = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCPUSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitFSIZE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitFSIZESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitDATA = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitDATASoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSTACK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSTACKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCORE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitCORESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRSS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRSSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNOFILE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNOFILESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitAS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitASSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNPROC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNPROCSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMEMLOCK = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMEMLOCKSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitLOCKS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitLOCKSSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSIGPENDING = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitSIGPENDINGSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMSGQUEUE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitMSGQUEUESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNICE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitNICESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTPRIO = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTPRIOSoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTTIME = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LimitRTTIMESoft = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s WorkingDirectory = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootDirectory = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootImage = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) RootImageOptions = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay RootHash = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootHashPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay RootHashSignature = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootHashSignaturePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootVerity = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RootEphemeral = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootMStack = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExtensionDirectories = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sba(ss)) ExtensionImages = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssba(ss)) MountImages = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i OOMScoreAdjust = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t CoredumpFilter = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i Nice = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IOSchedulingClass = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i IOSchedulingPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i CPUSchedulingPolicy = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i CPUSchedulingPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay CPUAffinity = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CPUAffinityFromNUMA = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i NUMAPolicy = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay NUMAMask = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimerSlackNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CPUSchedulingResetOnFork = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b NonBlocking = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardInput = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardInputFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly ay StandardInputData = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardOutput = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardOutputFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardError = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s StandardErrorFileDescriptorName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s TTYPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYReset = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYVHangup = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b TTYVTDisallocate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly q TTYRows = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly q TTYColumns = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogPriority = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s SyslogIdentifier = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SyslogLevelPrefix = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogLevel = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SyslogFacility = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i LogLevelMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t LogRateLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u LogRateLimitBurst = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly aay LogExtraFields = [[...], ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(bs) LogFilterPatterns = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s LogNamespace = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SecureBits = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t CapabilityBoundingSet = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t AmbientCapabilities = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s User = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Group = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b DynamicUser = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SetLoginEnvironment = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RemoveIPC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(say) SetCredential = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(say) SetCredentialEncrypted = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) LoadCredential = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) LoadCredentialEncrypted = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ImportCredential = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) ImportCredentialEx = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SupplementaryGroups = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PAMName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ReadWritePaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ReadOnlyPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as InaccessiblePaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExecPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as NoExecPaths = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ExecSearchPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t MountFlags = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateTmp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateTmpEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateDevices = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectClock = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelTunables = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelModules = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectKernelLogs = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectControlGroups = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectControlGroupsEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateNetwork = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateUsers = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateUsersEx = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateMounts = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateIPC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivatePIDs = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectHome = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectSystem = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SameProcessGroup = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UtmpIdentifier = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UtmpMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) SELinuxContext = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) AppArmorProfile = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bs) SmackProcessLabel = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b IgnoreSIGPIPE = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b NoNewPrivileges = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) SystemCallFilter = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as SystemCallArchitectures = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i SystemCallErrorNumber = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) SystemCallLog = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Personality = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b LockPersonality = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) RestrictAddressFamilies = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) RuntimeDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RuntimeDirectoryPreserve = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u RuntimeDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as RuntimeDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) StateDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u StateDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b StateDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) StateDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as StateDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) CacheDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u CacheDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b CacheDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) CacheDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as CacheDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) LogsDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u LogsDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b LogsDirectoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (tus) LogsDirectoryQuota = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as LogsDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(sst) ConfigurationDirectorySymlink = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u ConfigurationDirectoryMode = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly as ConfigurationDirectory = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutCleanUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MemoryDenyWriteExecute = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RestrictRealtime = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b RestrictSUIDSGID = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RestrictNamespaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t DelegateNamespaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (bas) RestrictFileSystems = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssbt) BindPaths = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ssbt) BindReadOnlyPaths = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) TemporaryFileSystem = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MountAPIVFS = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b BindLogSockets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KeyringMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProtectProc = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ProcSubset = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectHostname = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (ss) ProtectHostnameEx = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s PrivateBPF = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateCommands = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateMaps = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegatePrograms = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s BPFDelegateAttachments = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MemoryKSM = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s MemoryTHP = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s UserNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s NetworkNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IPCNamespacePath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s RootImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s MountImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s ExtensionImagePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) StateDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) CacheDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (tt) LogsDirectoryQuotaUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i RestartKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i FinalKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGKILL = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGHUP = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i WatchdogSignal = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; ## Properties Most of the properties map directly to the corresponding settings in swap unit files. As mount units invoke the `swapon(8)` command, their bus objects include implicit `ExecActivate` (and similar) fields which contain information about processes to execute. They also share most of the fields related to the execution context that Service objects expose (see above). In addition to these properties there are the following: `ControlPID` contains the PID of the currently running `swapon(8)` or `swapoff(8)` command if there is one running, otherwise 0. `Result` contains a value explaining why a mount unit failed if it failed. It can take the values `success`, `resources`, `timeout`, `exit-code`, `signal`, or `core-dump` which have the identical meanings as the corresponding values of the corresponding field of service unit objects (see above). # Path Unit Objects node /org/freedesktop/systemd1/unit/cups_2epath { interface org.freedesktop.systemd1.Path { properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Unit = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) Paths = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b MakeDirectory = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u DirectoryMode = ...; readonly s Result = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TriggerLimitIntervalUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u TriggerLimitBurst = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; ## Properties Most properties correspond directly with the matching settings in path unit files. The others: `Paths` contains an array of structs. Each struct contains the condition to watch, which can be one of `PathExists`, `PathExistsGlob`, `PathChanged`, `PathModified`, or `DirectoryNotEmpty` which correspond directly to the matching settings in the path unit files; and the path to watch, possibly including glob expressions. `Result` contains a result value which can be `success` or `resources` which have the same meaning as the corresponding field of the Service interface. # Slice Unit Objects All slice unit objects implement the org.freedesktop.systemd1.Slice interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). node /org/freedesktop/systemd1/unit/system_2eslice { interface org.freedesktop.systemd1.Slice { methods: GetProcesses(out a(sus) processes); AttachProcesses(in s subcgroup, in au pids); RemoveSubgroup(in s subcgroup, in t flags); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u ConcurrencyHardMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u ConcurrencySoftMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u ActivatingConcurrencyMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u NCurrentlyActive = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Slice = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ControlGroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ControlGroupId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryAvailable = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUUsageNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveTasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t OOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b Delegate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DelegateControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DelegateSubgroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupCPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPerSecUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPeriodUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUSetPartition = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IOAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupIOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceWeight = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceLatencyTargetUSec = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMin = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryZSwapWriteback = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DevicePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) DeviceAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b TasksAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IPAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPIngressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPEgressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DisableControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMSwap = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMMemoryPressure = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u ManagedOOMMemoryPressureLimit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMMemoryPressureDurationUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMPreference = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as OOMRules = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) BPFProgram = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (bas) RestrictNetworkInterfaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s BindNetworkInterface = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s MemoryPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s IOPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiss) NFTSet = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b CoredumpReceive = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; ## Properties Most properties correspond directly with the matching settings in slice unit files. `ManagedOOMMemoryPressureDurationUSec` implements the destination parameter of the unit file setting `ManagedOOMMemoryPressureDurationSec=` listed in `systemd.resource-control(5)`. Note the time unit is expressed in `μs`. # Scope Unit Objects All scope unit objects implement the org.freedesktop.systemd1.Scope interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). node /org/freedesktop/systemd1/unit/session_2d1_2escope { interface org.freedesktop.systemd1.Scope { methods: Abandon(); GetProcesses(out a(sus) processes); AttachProcesses(in s subcgroup, in au pids); RemoveSubgroup(in s subcgroup, in t flags); signals: RequestStop(); properties: readonly s Controller = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t TimeoutStopUSec = ...; readonly s Result = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RuntimeMaxUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RuntimeRandomizedExtraUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s OOMPolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Slice = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ControlGroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ControlGroupId = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapPeak = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryAvailable = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUUsageNSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay EffectiveMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksCurrent = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t EffectiveTasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPIngressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IPEgressPackets = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOReadOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteBytes = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWriteOperations = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t OOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMKills = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b Delegate = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DelegateControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DelegateSubgroup = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupCPUWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPerSecUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUQuotaPeriodUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedCPUs = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay AllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly ay StartupAllowedMemoryNodes = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUSetPartition = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IOAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupIOWeight = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceWeight = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteBandwidthMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOReadIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IOWriteIOPSMax = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(st) IODeviceLatencyTargetUSec = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMin = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryLow = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryHigh = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemorySwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t StartupMemoryZSwapMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b MemoryZSwapWriteback = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s DevicePolicy = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) DeviceAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b TasksAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TasksMax = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b IPAccounting = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iayu) IPAddressDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPIngressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as IPEgressFilterPath = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as DisableControllers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMSwap = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMMemoryPressure = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly u ManagedOOMMemoryPressureLimit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ManagedOOMMemoryPressureDurationUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ManagedOOMPreference = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as OOMRules = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(ss) BPFProgram = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindAllow = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiqq) SocketBindDeny = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (bas) RestrictNetworkInterfaces = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s BindNetworkInterface = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s MemoryPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t MemoryPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s CPUPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CPUPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s IOPressureWatch = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t IOPressureThresholdUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly a(iiss) NFTSet = [...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b CoredumpReceive = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s KillMode = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i KillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i RestartKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i FinalKillSignal = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGKILL = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b SendSIGHUP = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly i WatchdogSignal = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; interface org.freedesktop.systemd1.Unit { ... }; }; ## Methods `Abandon()` may be used to place a scope unit in the "abandoned" state. This may be used to inform the system manager that the manager that created the scope lost interest in the scope (for example, because it is terminating), without wanting to shut down the scope entirely. ## Signals `RequestStop()` is sent to the peer that is configured in the `Controller` property when systemd is requested to terminate the scope unit. A program registering a scope can use this to cleanly shut down the processes it added to the scope instead of letting systemd do it with the usual `SIGTERM` logic. ## Properties All properties correspond directly with the matching properties of service units. `Controller` contains the bus name (unique or well-known) that is notified when the scope unit is to be shut down via a `RequestStop()` signal (see below). This is set when the scope is created. If not set, the scope's processes will be terminated with `SIGTERM` directly. `ManagedOOMMemoryPressureDurationUSec` implements the destination parameter of the unit file setting `ManagedOOMMemoryPressureDurationSec=` listed in `systemd.resource-control(5)`. Note the time unit is expressed in `μs`. # Job Objects Job objects encapsulate scheduled or running jobs. Each unit can have none or one jobs in the execution queue. Each job is attached to exactly one unit. node /org/freedesktop/systemd1/job/666 { interface org.freedesktop.systemd1.Job { methods: Cancel(); GetAfter(out a(usssoo) jobs); GetBefore(out a(usssoo) jobs); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly u Id = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly (so) Unit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s JobType = '...'; readonly s State = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly a(ss) ActivationDetails = [...]; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `Cancel()` cancels the job. Note that this will remove a job from the queue if it is not yet executed but generally will not cause a job that is already in the process of being executed to be aborted. This operation may also be requested via the `CancelJob()` method of the Manager object (see above), which is sometimes useful to reduce roundtrips. ## Properties `Id` is the numeric Id of the job. During the runtime of a systemd instance each numeric ID is only assigned once. `Unit` refers to the unit this job belongs to. It is a structure consisting of the name of the unit and a bus path to the unit's object. `JobType` refers to the job's type and is one of `start`, `verify-active`, `stop`, `reload`, `restart`, `try-restart`, or `reload-or-start`. Note that later versions might define additional values. `State` refers to the job's state and is one of `waiting` and `running`. The former indicates that a job is currently queued but has not begun to execute yet. The latter indicates that a job is currently being executed. `ActivationDetails` has the same content as the property of the same name under the `org.freedesktop.systemd1.Unit` interface. # Examples
Introspect org.freedesktop.systemd1.Manager on the bus
$ gdbus introspect --system \ --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1
Introspect a unit on the bus
$ busctl introspect org.freedesktop.systemd1 \ $(busctl call org.freedesktop.systemd1 \ /org/freedesktop/systemd1 \ org.freedesktop.systemd1.Manager \ GetUnit s systemd-resolved.service | cut -d'"' -f2)
Introspect org.freedesktop.systemd1.Job on the bus
$ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/job/1292
# History ## The Manager Object `RuntimeWatchdogPreUSec` and `RuntimeWatchdogPreGovernor` were added in version 251. `WatchdogDevice`, `WatchdogLastPingTimestamp`, `WatchdogLastPingTimestampMonotonic`, `DefaultDeviceTimeoutUSec`, `DumpUnitsMatchingPatterns()`, and `DumpUnitsMatchingPatternsByFileDescriptor()` were added in version 252. `GetUnitByPIDFD()` and `DisableUnitFilesWithFlagsAndInstallInfo()` were added in version 253. `ConfidentialVirtualization`, `DefaultIOAccounting`, `DefaultIPAccounting`, `DefaultMemoryPressureThresholdUSec`, `DefaultMemoryPressureWatch`, `QueueSignalUnit()`, `SoftReboot()`, and `DumpUnitFileDescriptorStore()` were added in version 254. `StartAuxiliaryScope()` was added in version 256, deprecated in version 257, removed in version 258. `ShutdownStartTimestamp`, `ShutdownStartTimestampMonotonic`, and `SoftRebootsCount` were added in version 256. `DefaultRestrictSUIDSGID`, `RemoveSubgroupFromUnit()`, and `KillUnitSubgroup()` were added in version 258. `TransactionsWithOrderingCycle` was added in version 259. `DefaultMemoryZSwapWriteback`, `DefaultCPUPressureThresholdUSec`, `DefaultCPUPressureWatch`, `DefaultIOPressureThresholdUSec`, `DefaultIOPressureWatch`, `ReloadCount`, `EventLoopRateLimitIntervalUSec`, and `EventLoopRateLimitBurst` were added in version 261. `KExecCount`, `EnqueueUnitJobMany()`, `ShutdownFinishTimestamp`, `ShutdownFinishTimestampMonotonic`, `PreviousShutdownStartTimestamp`, `PreviousShutdownStartTimestampMonotonic`, `PreviousShutdownFinishTimestamp`, `PreviousShutdownFinishTimestampMonotonic`, `PreviousShutdownLateStartTimestamp`, `PreviousShutdownLateStartTimestampMonotonic`, `PreviousShutdownLateFinishTimestamp`, and `PreviousShutdownLateFinishTimestampMonotonic` were added in version 262. ## Unit Objects `Upholds` and `UpheldBy` were added in version 251. `AccessSELinuxContext` and `ActivationDetails` were added in version 252. `QueueSignal()` was added in version 254. `SurviveFinalKillSignal` was added in version 255. `WantsMountsFor` was added in version 256. `DebugInvocation`, and `CanLiveMount` were added in version 257. ## Service Unit Objects `ControlGroupId` and `ExtensionDirectories` were added in version 251. `OpenFile`, `ReloadSignal`, `MemoryZSwapMax`, and `LogFilterPatterns` were added in version 253. `RestartMode`, `RestartSteps`, `RestartMaxDelayUSec`, `RestartUSecNext`, `FileDescriptorStorePreserve`, `DumpFileDescriptorStore()`, `DelegateSubgroup`, `DefaultStartupMemoryLow`, `StartupMemoryLow`, `StartupMemoryHigh`, `StartupMemoryMax`, `StartupMemorySwapMax`, `StartupMemoryZSwapMax`, `MemoryPressureWatch`, `MemoryPressureThresholdUSec`, `RootEphemeral`, `ImportCredential`, `MemoryKSM`, `RootImagePolicy`, `MountImagePolicy`, and `ExtensionImagePolicy` were added in version 254. `NFTSet`, `SetLoginEnvironment`, `CoredumpReceive`, `MemoryPeak`, `MemorySwapCurrent`, `MemorySwapPeak`, and `MemoryZSwapCurrent` were added in version 255. `EffectiveMemoryHigh`, `EffectiveMemoryMax`, `EffectiveTasksMax`, `MemoryZSwapWriteback`, `ExecMainHandoffTimestampMonotonic`, and `ExecMainHandoffTimestamp` were added in version 256. `StatusBusError`, `StatusVarlinkError`, `LiveMountResult`, `PrivateTmpEx`, `ImportCredentialEx`, `ExtraFileDescriptorNames`, `ManagedOOMMemoryPressureDurationUSec`, `BindLogSockets`, `ProtectControlGroupsEx`, `PrivateUsersEx`, and `PrivatePIDs` were added in version 257. `ProtectHostnameEx`, `DelegateNamespaces`, `PrivateBPF`, `BPFDelegateCommands`, `BPFDelegateMaps`, `BPFDelegatePrograms`, `BPFDelegateAttachments`, `RemoveSubGroup()`, `StateDirectoryQuota`, `StateDirectoryQuotaUsage`, `StateDirectoryAccounting`, `CacheDirectoryQuota`, `CacheDirectoryQuotaUsage`, `CacheDirectoryAccounting`, `LogsDirectoryQuota`, `LogsDirectoryQuotaUsage`, `LogsDirectoryAccounting`, and `KillSubgroup()` were added in version 258. `UserNamespacePath`, `OOMKills`, `ManagedOOMKills`, `ExecReloadPost`, and `ExecReloadPostEx` were added in version 259. `BindNetworkInterface`, `MemoryTHP`, `RefreshOnReload`, and `RootMStack` were added in version 260. `CPUPressureThresholdUSec`, `CPUPressureWatch`, `IOPressureThresholdUSec`, `IOPressureWatch`, `CPUSetPartition`, and `OOMRules` were added in version 261. `LUOSession` was added in version 262. `RestartRandomizedDelayUSec` was added in version 262. `ConfigurationDirectorySymlink` was added in version 263. ## Socket Unit Objects `ControlGroupId` and `ExtensionDirectories` were added in version 251. `MemoryZSwapMax` and `LogFilterPatterns` were added in version 253. `DelegateSubgroup`, `DefaultStartupMemoryLow`, `StartupMemoryLow`, `StartupMemoryHigh`, `StartupMemoryMax`, `StartupMemorySwapMax`, `StartupMemoryZSwapMax`, `MemoryPressureWatch`, `MemoryPressureThresholdUSec`, `RootEphemeral`, `ImportCredential`, `MemoryKSM`, `RootImagePolicy`, `MountImagePolicy`, and `ExtensionImagePolicy` were added in version 254. `PollLimitIntervalUSec`, `PollLimitBurst`, `NFTSet`, `SetLoginEnvironment`, `CoredumpReceive`, `MemoryPeak`, `MemorySwapCurrent`, `MemorySwapPeak`, and `MemoryZSwapCurrent` were added in version 255. `EffectiveMemoryHigh`, `EffectiveMemoryMax`, `EffectiveTasksMax`, `MemoryZSwapWriteback`, and `PassFileDescriptorsToExec` were added in version 256. `PrivateTmpEx`, `ImportCredentialEx`, `BindLogSockets`, `PrivateUsersEx`, `ManagedOOMMemoryPressureDurationUSec`, `ProtectControlGroupsEx`, and `PrivatePIDs` were added in version 257. `ProtectHostnameEx`, `PassPIDFD`, `AcceptFileDescriptors`, `DelegateNamespaces`, `PrivateBPF`, `BPFDelegateCommands`, `BPFDelegateMaps`, `BPFDelegatePrograms`, `BPFDelegateAttachments`, `RemoveSubgroup()`, `DeferTrigger`, `DeferTriggerMaxUSec`, `StateDirectoryQuota`, `StateDirectoryQuotaUsage`, `StateDirectoryAccounting`, `CacheDirectoryQuota`, `CacheDirectoryQuotaUsage`, `CacheDirectoryAccounting`, `LogsDirectoryQuota`, `LogsDirectoryQuotaUsage`, `LogsDirectoryAccounting`, and `KillSubgroup()` were added in version 258. `UserNamespacePath`, `OOMKills`, and `ManagedOOMKills` were added in 259. `BindNetworkInterface` `MemoryTHP`, and `RootMStack` were added in version 260. `CPUPressureThresholdUSec`, `CPUPressureWatch`, `IOPressureThresholdUSec`, `IOPressureWatch`, `CPUSetPartition`, and `OOMRules` were added in version 261. `XAttrEntryPoint`, `XAttrListen`, and `XAttrAccept` were added in version 262. `ConfigurationDirectorySymlink` was added in version 263. ## Mount Unit Objects `ControlGroupId` and `ExtensionDirectories` were added in version 251. `MemoryZSwapMax` and `LogFilterPatterns` were added in version 253. `DelegateSubgroup`, `DefaultStartupMemoryLow`, `StartupMemoryLow`, `StartupMemoryHigh`, `StartupMemoryMax`, `StartupMemorySwapMax`, `StartupMemoryZSwapMax`, `MemoryPressureWatch`, `MemoryPressureThresholdUSec`, `RootEphemeral`, `ImportCredential`, `MemoryKSM`, `RootImagePolicy`, `MountImagePolicy`, and `ExtensionImagePolicy` were added in version 254. `NFTSet`, `SetLoginEnvironment`, `CoredumpReceive`, `MemoryPeak`, `MemorySwapCurrent`, `MemorySwapPeak`, and `MemoryZSwapCurrent` were added in version 255. `EffectiveMemoryHigh`, `EffectiveMemoryMax`, `EffectiveTasksMax`, and `MemoryZSwapWriteback` were added in version 256. `PrivateTmpEx`, `ImportCredentialEx`, `BindLogSockets`, `PrivateUsersEx`, `ManagedOOMMemoryPressureDurationUSec`, `ProtectControlGroupsEx`, and `PrivatePIDs` were added in version 257. `ProtectHostnameEx`, `DelegateNamespaces`, `PrivateBPF`, `BPFDelegateCommands`, `BPFDelegateMaps`, `BPFDelegatePrograms`, `BPFDelegateAttachments`, `RemoveSubgroup()`, `ReloadResult`, `CleanResult`, `StateDirectoryQuota`, `StateDirectoryQuotaUsage`, `StateDirectoryAccounting`, `CacheDirectoryQuota`, `CacheDirectoryQuotaUsage`, `CacheDirectoryAccounting`, `LogsDirectoryQuota`, `LogsDirectoryQuotaUsage`, `LogsDirectoryAccounting`, and `KillSubgroup()` were added in version 258. `UserNamespacePath`, `OOMKills`, and `ManagedOOMKills` were added in 259. `BindNetworkInterface` `MemoryTHP`, and `RootMStack` were added in version 260. `CPUPressureThresholdUSec`, `CPUPressureWatch`, `IOPressureThresholdUSec`, `IOPressureWatch`, `CPUSetPartition`, and `OOMRules` were added in version 261. `ConfigurationDirectorySymlink` was added in version 263. ## Swap Unit Objects `ControlGroupId` and `ExtensionDirectories` were added in version 251. `MemoryZSwapMax` and `LogFilterPatterns` were added in version 253. `DelegateSubgroup`, `DefaultStartupMemoryLow`, `StartupMemoryLow`, `StartupMemoryHigh`, `StartupMemoryMax`, `StartupMemorySwapMax`, `StartupMemoryZSwapMax`, `MemoryPressureWatch`, `MemoryPressureThresholdUSec`, `RootEphemeral`, `ImportCredential`, `MemoryKSM`, `RootImagePolicy`, `MountImagePolicy`, and `ExtensionImagePolicy` were added in version 254. `NFTSet`, `SetLoginEnvironment`, `CoredumpReceive`, `MemoryPeak`, `MemorySwapCurrent`, `MemorySwapPeak`, and `MemoryZSwapCurrent` were added in version 255. `EffectiveMemoryHigh`, `EffectiveMemoryMax`, `EffectiveTasksMax`, and `MemoryZSwapWriteback` were added in version 256. `PrivateTmpEx`, `ImportCredentialEx`, `BindLogSockets`, `PrivateUsersEx`, `ManagedOOMMemoryPressureDurationUSec`, `ProtectControlGroupsEx`, and `PrivatePIDs` were added in version 257. `ProtectHostnameEx`, `DelegateNamespaces`, `PrivateBPF`, `BPFDelegateCommands`, `BPFDelegateMaps`, `BPFDelegatePrograms`, `BPFDelegateAttachments`, `RemoveSubgroup()`, `StateDirectoryQuota`, `StateDirectoryQuotaUsage`, `StateDirectoryAccounting`, `CacheDirectoryQuota`, `CacheDirectoryQuotaUsage`, `CacheDirectoryAccounting`, `LogsDirectoryQuota`, `LogsDirectoryQuotaUsage`, `LogsDirectoryAccounting`, and `KillSubgroup()` were added in version 258. `UserNamespacePath`, `OOMKills`, and `ManagedOOMKills` were added in 259. `BindNetworkInterface`, `MemoryTHP`, and `RootMStack` were added in version 260. `CPUPressureThresholdUSec`, `CPUPressureWatch`, `IOPressureThresholdUSec`, `IOPressureWatch`, `CPUSetPartition`, and `OOMRules` were added in version 261. `ConfigurationDirectorySymlink` was added in version 263. ## Slice Unit Objects `ControlGroupId` was added in version 251. `MemoryZSwapMax` was added in version 253. `DelegateSubgroup`, `DefaultStartupMemoryLow`, `StartupMemoryLow`, `StartupMemoryHigh`, `StartupMemoryMax`, `StartupMemorySwapMax`, `StartupMemoryZSwapMax`, `MemoryPressureWatch`, and `MemoryPressureThresholdUSec` were added in version 254. `NFTSet`, `CoredumpReceive`, `MemoryPeak`, `MemorySwapCurrent`, `MemorySwapPeak`, and `MemoryZSwapCurrent` were added in version 255. `EffectiveMemoryHigh`, `EffectiveMemoryMax`, `EffectiveTasksMax`, and `MemoryZSwapWriteback` were added in version 256. `ManagedOOMMemoryPressureDurationUSec` was added in version 257. `ConcurrencyHardMax`, `ConcurrencySoftMax`, `NCurrentlyActive`, `RemoveSubgroup()`, and `KillSubgroup()` were added in version 258. `OOMKills`, and `ManagedOOMKills` were added in 259. `BindNetworkInterface` was added in version 260. `CPUPressureThresholdUSec`, `CPUPressureWatch`, `IOPressureThresholdUSec`, `IOPressureWatch`, `CPUSetPartition`, and `OOMRules` were added in version 261. `ActivatingConcurrencyMax` was added in version 262. ## Scope Unit Objects `ControlGroupId` was added in version 251. `OOMPolicy` and `MemoryZSwapMax` were added in version 253. `DelegateSubgroup`, `DefaultStartupMemoryLow`, `StartupMemoryLow`, `StartupMemoryHigh`, `StartupMemoryMax`, `StartupMemorySwapMax`, `StartupMemoryZSwapMax`, `MemoryPressureWatch`, and `MemoryPressureThresholdUSec` were added in version 254. `NFTSet`, `CoredumpReceive`, `MemoryPeak`, `MemorySwapCurrent`, `MemorySwapPeak`, and `MemoryZSwapCurrent` were added in version 255. `EffectiveMemoryHigh`, `EffectiveMemoryMax`, `EffectiveTasksMax`, and `MemoryZSwapWriteback` were added in version 256. `ManagedOOMMemoryPressureDurationUSec` was added in version 257. `RemoveSubgroup()` and `KillSubgroup()` were added in version 258. `OOMKills`, and `ManagedOOMKills` were added in 259. `BindNetworkInterface` was added in version 260. `CPUPressureThresholdUSec`, `CPUPressureWatch`, `IOPressureThresholdUSec`, `IOPressureWatch`, `CPUSetPartition`, and `OOMRules` were added in version 261. ## Job Objects `ActivationDetails` was added in version 252. ## Timer Objects `DeferReactivation` was added in version 257. `RandomizedOffsetUSec` was added in version 258. # See Also `systemd(1)`, `systemctl(1)` # org.freedesktop.sysupdate1 systemd org.freedesktop.sysupdate1 5 org.freedesktop.sysupdate1 The D-Bus interface of systemd-sysupdated # Introduction `systemd-sysupdated.service(8)` is a system service that allows unprivileged clients to update the system. This page describes the D-Bus interface. *WARNING!* This API is currently *unstable* and is thus subject to breaking changes between versions of systemd. # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/sysupdate1 { interface org.freedesktop.sysupdate1.Manager { methods: ListTargets(out a(sso) targets); ListJobs(out a(tsuo) jobs); ListAppStream(out as urls); signals: JobRemoved(t id, o path, i status); }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `ListTargets()` returns a list all known update targets. It returns an array of structures which consist of a string indicating the target's class (see Target's `Class` property below for an explanation of the possible values), a string with the name of the target, and the target object path. `ListJobs()` returns a list all ongoing jobs. It returns an array of structures which consist of a numeric job ID, a string indicating the job type (see Job's `Type` property below for an explanation of the possible values), the job's progress, and the job's object path. `ListAppStream()` returns an array of all the appstream catalog URLs that this service knows about. See Target's `GetAppStream()` method below for more details. ## Signals The `JobRemoved()` signal is sent each time a job finishes, is canceled or fails. It also carries the job ID and object path, followed by a numeric status code. If the status is zero, the job has succeeded. A positive status should be treated as an exit code (i.e. `EXIT_FAILURE`), and a negative status should be treated as a negative errno-style error code (i.e. `-EINVAL`). # The Target Object A target is a component of the system (i.e. the host itself, a sysext, a confext, etc.) that can be updated by `systemd-sysupdate(8)`. The service exposes the following interfaces on Target objects on the bus: node /org/freedesktop/sysupdate1/target/host { interface org.freedesktop.sysupdate1.Target { methods: List(in t flags, out as versions); Describe(in s version, in t flags, out s json); CheckNew(out s new_version); Acquire(in s new_version, in t flags, out s new_version, out t job_id, out o job_path); Install(in s new_version, in t flags, out s new_version, out t job_id, out o job_path); Vacuum(out u instances, out u disabled_transfers); GetAppStream(out as appstream); GetVersion(out s version); ListFeatures(in t flags, out as features); DescribeFeature(in s feature, in t flags, out s json); SetFeatureEnabled(in s feature, in i enabled, in t flags); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Class = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Name = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Path = '...'; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods `List()` returns a list of versions available for this target. Additional options may be passed through the `flags` argument. Valid flags are defined as follows: #define SD_SYSUPDATE_OFFLINE (UINT64_C(1) << 0) When `SD_SYSUPDATE_OFFLINE` is set, this method returns only the versions installed locally. Otherwise, this method pulls metadata from the network and returns all versions available for this target. Use `Describe()` to query more information about each version returned by this method. `Describe()` returns all known information about a given version as a JSON object. The `version` argument is used to pass the version to be described. Additional options may be passed through the `flags` argument. This method supports the same flags as `List()`. The returned JSON object contains several known keys. More keys may be added in the future. The currently known keys are as follows: `version` A string containing the version number. `newest` A boolean indicating whether this version is the latest available for the target. `available` A boolean indicating whether this version is available for download. `installed` A boolean indicating whether this version is installed locally. `obsolete` A boolean indicating whether this version is considered obsolete by the service, and is therefore disallowed from being installed. `protected` A boolean indicating whether this version is exempt from deletion by a `Vacuum()` operation. `incomplete` A boolean indicating whether this version is incomplete, which means that it is missing some file. Note that only installed incomplete versions will be offered by the service; versions that are incomplete on the server-side are completely ignored. Incomplete versions can be repaired in-place by calling `Acquire()` and `Install()` on that version. `changelogUrls` A list of strings that contain user-presentable URLs to change logs associated with this version. `CheckNew()` checks if a newer version is available for this target. This method pulls metadata from the network. If a newer version is found, this method returns the version number. If no newer version is found, this method returns an empty string. Use `Describe()` to query more information about the version returned by this method. `Acquire()` downloads an update for this target, if one is available. If a `new_version` is specified, that is the version that gets downloaded. Otherwise, the latest version is downloaded. Call `Install()` to install the acquired update. The `flags` argument is added for future extensibility. No flags are currently defined, and the argument is required to be set to `0`. This method pulls both metadata and payload data from the network. `Install()` installs an already-acquired update for this target. If a `new_version` is specified, that is the version that gets installed, assuming it has already been acquired. Otherwise, the latest acquired version is installed. The `flags` argument is added for future extensibility. No flags are currently defined, and the argument is required to be set to `0`. Unlike all the other methods in this interface, `Acquire()` and `Install()` do not wait for their jobs to complete. Instead, they return the job's numeric ID and object path as soon as the job begins, so that the caller can listen for progress updates or cancel the operation. These methods also return the version the target will be updated to, for cases where no version was specified by the caller. Listen for the Manager's `JobRemoved()` signal to detect when the job is complete. `Vacuum()` deletes old installed versions of this target to free up space. It returns the number of instances that have been deleted. `GetAppStream()` returns a list of HTTP/HTTPS URLs to this target's [appstream catalog](https://wwww.freedesktop.org/software/appstream/docs/chap-CatalogData.html) XML files. If this target has no appstream catalogs, the method will return an empty list. These catalog files can be used by software centers (such as GNOME Software or KDE Discover) to present rich metadata about the target, including a display name, changelog, icon, and more. The returned catalogs will include [special metadata](https://systemd.io/APPSTREAM_BUNDLE) to allow the software center to correctly associate the catalogs with this target. `GetVersion()` returns the current version of this target, if any. The current version is the newest version that is installed. Note that this is not necessarily the same thing as the booted or currently-in-use version of the target. For example, on the host system the booted version is the current version most of the time, but if an update is installed and pending a reboot it will become the current version instead. You can query the booted version of the host system via `IMAGE_VERSION` in `/etc/os-release`. If the target has no current version, the function will return an empty string. `ListFeatures()` returns a list of this target's optional features, by ID. The `flags` argument is added for future extensibility, and must be set to 0. If the target has no optional features, the method returns an empty array. `DescribeFeature()` returns all known information about a given optional feature. The `feature` argument is used to pass the ID of the feature to be described. The `flags` argument is added for future extensibility, and must be set to 0. The returned JSON object contains several known keys. More keys may be added in the future. The currently known keys are as follows: `id` A string containing the feature's ID. `description` An optional string that contains a user-presentable description that identifies this feature `enabled` A boolean indicating whether this feature is enabled. `suggested` An optional boolean indicating whether this feature is suggested for enablement. If omitted, it could not be determined whether the feature is suggested. `documentation` An optional array of strings containing user-presentable HTTP/HTTPS URLs to documentation about this feature. `appStream` An optional array of strings containing HTTP/HTTPS URLs to [appstream catalog](https://wwww.freedesktop.org/software/appstream/docs/chap-CatalogData.html) XML files containing metadata about this feature. `transfers` An optional array of strings that list which transfer definitions belong to this feature. `SetFeatureEnabled()` writes an appropriate drop-in file to enable or disable the specified optional feature. If `enable` is zero, the feature is disabled. When greater than zero, the feature is enabled. When less than zero, the feature is reset to the distribution's default. The `flags` argument is added for future extensibility, and must be set to 0. The feature does not have to exist; this allows for graceful handling of masked features, and for preemptive decisions to be made about features that are planned to appear in future releases of the OS. The drop-in will have a filename of `50-systemd-sysupdate-enabled.conf`. This method only changes configuration files; to actually apply the changes, clients will need to call `Acquire()` and `Install()`. Depending on the exact needs of the client, it can choose to update the system to the latest available version, or it can extend the newest existing installation in-place (by passing in the version returned by `GetVersion()`). For now, this method only works with the `host` target. ## Properties The `Class` property exposes the class of this target, which describes where it was enumerated. Possible values include: `machine` for containers and virtual machines managed by `systemd-machined.service(8)`, `portable` for [portable services](https://systemd.io/PORTABLE_SERVICES), `sysext` for system extensions managed by `systemd-sysext(8)`, `confext` for configuration extensions managed by `systemd-confext(8)`, `component` for components accepted by the `--component=` option of `systemd-sysupdate(8)`, and `host` for the host system itself. At most one target will have a class of `host`. The `Path` property exposes more detail about where this target was found. For `machine`, `portable`, `extension`, and `confext` targets, this is the file path to the image. For `component` and `host` targets, this is the name of a `sysupdate.d(5)` directory. The `Name` property exposes the name of this target. Note that the name is unique within a class but is not necessarily unique between classes. For instance, it is possible to have both a `portable` target named `foobar` and an `extension` target named `foobar`, but it is not possible to have two `portable` targets named `foobar`. ## Security Method calls on this service are authenticated via [polkit](https://www.freedesktop.org/software/polkit/docs/latest/). `List()`, `Describe()`, and `CheckNew()` use the polkit action org.freedesktop.sysupdate1.check. By default, this action is permitted without administrator authentication. Cancellation of these methods uses the polkit action org.freedesktop.sysupdate1.cancel-check. By default, this cancellation action is permitted without administrator authentication. `Acquire()` and `Install()` use the polkit action org.freedesktop.sysupdate1.update when no version is specified. By default, this action is permitted without administrator authentication. When a version is specified, org.freedesktop.sysupdate1.update-to-version is used instead. By default, this alternate action requires administrator authentication. Cancellation of these methods uses the polkit actions org.freedesktop.sysupdate1.cancel-update and org.freedesktop.sysupdate1.cancel-update-to-version. By default, these cancellation actions are permitted without administrator authentication. `Vacuum()` uses the polkit action org.freedesktop.sysupdate1.vacuum. By default, this action requires administrator authentication. Cancellation of this method uses the polkit action org.freedesktop.sysupdate1.cancel-vacuum. By default, this cancellation action is permitted without administrator authentication. `SetFeatureEnabled()` uses the polkit action org.freedesktop.sysupdate1.manage-features. By default, this action requires administrator authentication. Cancellation is not supported for this method. `GetAppStream()`, `GetVersion()`, `ListFeatures()`, and `DescribeFeature()` are unauthenticated and may be called by anybody. Cancellation is not supported for these methods, or is always allowed without administrator authentication. All methods called on this interface expose additional variables to the polkit rules. `class` contains the class of the Target being acted upon, and `name` contains the name of the same Target. Additionally, each method exposes its arguments to the rule. Flags are mapped as follows: - `SD_SYSUPDATE_OFFLINE` → `update` # The Job Object A job is an ongoing operation, started by one of the methods on a Target object. The service exposes the following interfaces on Job objects on the bus: node /org/freedesktop/sysupdate1/job/_1 { interface org.freedesktop.sysupdate1.Job { methods: Cancel(); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t Id = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s Type = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b Offline = ...; readonly u Progress = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods The `Cancel()` method may be used to cancel the job. It takes no parameters. ## Properties The `Id` property exposes the numeric job ID of the job object. The `Type` property exposes the type of operation (one of: `list`, `describe`, `check-new`, `acquire`, `install`, `vacuum`, or `describe-feature`). The `Offline` property exposes whether the job is permitted to access the network or not. The `Progress` property exposes the current progress of the job as a value between 0 and 100. It is only available for `acquire` and `install` jobs; for all other jobs it is always 0. ## Security `Cancel()` uses the polkit action that corresponds to the method that started this job. For instance, trying to cancel a `list` job will require polkit to permit the org.freedesktop.sysupdate1.check action. # Examples
Introspect org.freedesktop.sysupdate1.Manager on the bus
$ gdbus introspect --system \ --dest org.freedesktop.sysupdate1 \ --object-path /org/freedesktop/sysupdate1
Introspect org.freedesktop.sysupdate1.Target on the bus
$ gdbus introspect --system \ --dest org.freedesktop.sysupdate1 \ --object-path /org/freedesktop/sysupdate1/target/host
Introspect org.freedesktop.sysupdate1.Job on the bus
$ gdbus introspect --system \ --dest org.freedesktop.sysupdate1 \ --object-path /org/freedesktop/sysupdate1/job/_1
# History ## The Manager Object `ListTargets()`, `ListJobs()`, `ListAppStream()`, and `JobRemoved()` were added in version 257. ## The Target Object `List()`, `Describe()`, `CheckNew()`, `Acquire()`, `Install()`, `Vacuum()`, `GetAppStream()`, `GetVersion()`, `ListFeatures()`, `DescribeFeature()`, `SetFeatureEnabled()`, `Class`, `Name`, and `Path` were added in version 257. ## The Job Object `Cancel()`, `Id`, `Type`, `Offline`, and `Progress` were added in version 257. # See Also `systemd(1)`, `systemd-sysupdated.service(8)`, `updatectl(1)` # org.freedesktop.timedate1 systemd org.freedesktop.timedate1 5 org.freedesktop.timedate1 The D-Bus interface of systemd-timedated # Introduction `systemd-timedated.service(8)` is a system service that can be used to control the system time and related settings. This page describes the D-Bus interface. # The D-Bus API The service exposes the following interfaces on the bus: node /org/freedesktop/timedate1 { interface org.freedesktop.timedate1 { methods: SetTime(in x usec_utc, in b relative, in b interactive); SetTimezone(in s timezone, in b interactive); SetLocalRTC(in b local_rtc, in b fix_system, in b interactive); SetNTP(in b use_ntp, in b interactive); ListTimezones(out as timezones); properties: readonly s Timezone = '...'; readonly b LocalRTC = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b CanNTP = ...; readonly b NTP = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b NTPSynchronized = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t TimeUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t RTCTimeUSec = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; ## Methods Use `SetTime()` to change the system clock. Pass a value of microseconds since the UNIX epoch (1 Jan 1970 UTC). If `relative` is true, the passed usec value will be added to the current system time. If it is false, the current system time will be set to the passed usec value. If the system time is set with this method, the RTC will be updated as well. Use `SetTimezone()` to set the system timezone. Pass a value like `Europe/Berlin` to set the timezone. Valid timezones are listed in `/usr/share/zoneinfo/zone.tab`. If the RTC is configured to be maintained in local time, it will be updated accordingly. Use `SetLocalRTC()` to control whether the RTC is in local time or UTC. It is strongly recommended to maintain the RTC in UTC. However, some OSes (Windows) maintain the RTC in local time, which might make it necessary to enable this feature. Note that this might create various problems as daylight changes could be missed. If `fix_system` is `true`, the time from the RTC is read again and the system clock is adjusted according to the new setting. If `fix_system` is `false`, the system time is written to the RTC taking the new setting into account. Use `fix_system=true` in installers and livecds where the RTC is probably more reliable than the system time. Use `fix_system=false` in configuration UIs that are run during normal operation and where the system clock is probably more reliable than the RTC. Use `SetNTP()` to control whether the system clock is synchronized with the network using `systemd-timesyncd`. This will enable and start or disable and stop the chosen time synchronization service. `ListTimezones()` returns a list of time zones known on the local system as an array of names (`["Africa/Abidjan", "Africa/Accra", ..., "UTC"]`). ## Properties `Timezone` shows the currently configured time zone. `LocalRTC` shows whether the RTC is configured to use UTC (false), or the local time zone (true). `CanNTP` shows whether a service to perform time synchronization over the network is available, and `NTP` shows whether such a service is enabled. `NTPSynchronized` shows whether the kernel reports the time as synchronized (c.f. `adjtimex(3)`). `TimeUSec` and `RTCTimeUSec` show the current time on the system and in the RTC. The purpose of those three properties is to allow remote clients to access this information over D-Bus. Local clients can access the information directly. Whenever the `Timezone` and `LocalRTC` settings are changed via the daemon, `PropertyChanged` signals are sent out to clients which have subscribed. Note that this service will not inform you about system time changes. Use `timerfd(3)` with `CLOCK_REALTIME` and `TFD_TIMER_CANCEL_ON_SET` for that. ## Security The `interactive` boolean parameters can be used to control whether [polkit](https://www.freedesktop.org/software/polkit/docs/latest/) should interactively ask the user for authentication credentials if required. The polkit action for `SetTimezone()` is org.freedesktop.timedate1.set-timezone. For `SetLocalRTC()` it is org.freedesktop.timedate1.set-local-rtc, for `SetTime()` it is org.freedesktop.timedate1.set-time and for `SetNTP()` it is org.freedesktop.timedate1.set-ntp. `ListTimezones()` does not require any privileges. # Examples
Introspect org.freedesktop.timedate1 on the bus
$ gdbus introspect --system \ --dest org.freedesktop.timedate1 \ --object-path /org/freedesktop/timedate1
# See Also `systemd(1)`, `systemd-timedated.service(8)`, `timedatectl(1)`, [More information on how the system clock and RTC interact](https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html) # org.freedesktop.timesync1 systemd org.freedesktop.timesync1 5 org.freedesktop.timesync1 The D-Bus interface of systemd-timesyncd # Introduction `systemd-timesyncd.service(8)` is a system service that may be used to synchronize the local system clock with a remote Network Time Protocol (NTP) server. This page describes the D-Bus interface. # The Manager Object The service exposes the following interfaces on the Manager object on the bus: node /org/freedesktop/timesync1 { interface org.freedesktop.timesync1.Manager { methods: SetRuntimeNTPServers(in as runtime_servers); properties: readonly as LinkNTPServers = ['...', ...]; readonly as SystemNTPServers = ['...', ...]; readonly as RuntimeNTPServers = ['...', ...]; readonly as FallbackNTPServers = ['...', ...]; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s ServerName = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (iay) ServerAddress = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t RootDistanceMaxUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PollIntervalMinUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t PollIntervalMaxUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t PollIntervalUSec = ...; readonly (uuuuittayttttbtt) NTPMessage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly x Frequency = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; }; Provides information about the manager. # Examples
Introspect org.freedesktop.timesync1.Manager on the bus
$ gdbus introspect --system \ --dest org.freedesktop.timesync1 \ --object-path /org/freedesktop/timesync1
# See Also `systemd(1)`, `systemd-timesyncd.service(8)` # os-release systemd os-release 5 os-release initrd-release extension-release Operating system identification `/etc/os-release`, `/usr/lib/os-release`, `/etc/initrd-release`, `/usr/lib/extension-release.d/extension-release.IMAGE` # Description The `/etc/os-release` and `/usr/lib/os-release` files contain operating system identification data. The format of `os-release` is a newline-separated list of environment-like shell-compatible variable assignments. It is possible to source the configuration from Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this means variable expansion is explicitly not supported), allowing applications to read the file without implementing a shell compatible execution engine. Variable assignment values must be enclosed in double or single quotes if they include spaces, semicolons or other special characters outside of A–Z, a–z, 0–9. (Assignments that do not include these special characters may be enclosed in quotes too, but this is optional.) Shell special characters ("\$", quotes, backslash, backtick) must be escaped with backslashes, following shell style. All strings should be in UTF-8 encoding, and non-printable characters should not be used. Concatenation of multiple individually quoted strings is not supported. Lines beginning with "#" are treated as comments. Blank lines are permitted and ignored. The file `/etc/os-release` takes precedence over `/usr/lib/os-release`. Applications should check for the former, and exclusively use its data if it exists, and only fall back to `/usr/lib/os-release` if that is missing. Applications should not combine the data from both files. `/usr/lib/os-release` is the recommended place to store OS release information as part of vendor trees. `/etc/os-release` should be a relative symlink to `/usr/lib/os-release`, to provide compatibility with applications only looking at `/etc/`. A relative symlink instead of an absolute symlink is necessary to avoid breaking the link in a chroot or initrd environment. `os-release` contains data that is defined by the operating system vendor and should generally not be changed by the administrator. As this file only encodes names and identifiers it should not be localized. The `/etc/os-release` and `/usr/lib/os-release` files might be symlinks to other files, but it is important that the file is available from earliest boot on, and hence must be located on the root file system. `os-release` must not contain repeating keys. Nevertheless, readers should pick the entries later in the file in case of repeats, similarly to how a shell sourcing the file would. A reader may warn about repeating entries. For a longer rationale for `os-release` please refer to the [Announcement of `/etc/os-release`](https://0pointer.de/blog/projects/os-release). ## `/etc/initrd-release` In the [initrd](https://docs.kernel.org/admin-guide/initrd.html) and exitrd, `/etc/initrd-release` plays the same role as `os-release` in the main system. Additionally, the presence of that file means that the system is in the initrd/exitrd phase. `/etc/os-release` should be symlinked to `/etc/initrd-release` (or vice versa), so programs that only look for `/etc/os-release` (as described above) work correctly. The rest of this document that talks about `os-release` should be understood to apply to `initrd-release` too. ## `/usr/lib/extension-release.d/extension-release.IMAGE` `/usr/lib/extension-release.d/extension-release.IMAGE` plays the same role for extension images as `os-release` for the main system, and follows the syntax and rules as described in the [Portable Services](https://systemd.io/PORTABLE_SERVICES) page. The purpose of this file is to identify the extension and to allow the operating system to verify that the extension image matches the base OS. This is typically implemented by checking that the extension `ID=` option either matches the host `ID=` option or is included the host `ID_LIKE=` option, and either `SYSEXT_LEVEL=` exists and matches too, or if it is not present, `VERSION_ID=` exists and matches. If the extension image sets `IMAGE_ID=` and/or `IMAGE_VERSION=`, the host must also declare these fields and the values must match. This ensures ABI/API compatibility between the layers and prevents merging of an incompatible image in an overlay. In order to identify the extension image itself, the same fields defined below can be added to the `extension-release` file with a `SYSEXT_` prefix (to disambiguate from fields used to match on the base image). E.g.: `SYSEXT_ID=myext`, `SYSEXT_VERSION_ID=1.2.3`. In the `extension-release.IMAGE` filename, the \ part must exactly match the file name of the containing image with the suffix removed. In case it is not possible to guarantee that an image file name is stable and does not change between the build and the deployment phases, it is possible to relax this check: if exactly one file whose name matches `extension-release.*` is present in this directory, and the file is tagged with a `user.extension-release.strict` `xattr(7)` set to the string `0`, it will be used instead. The rest of this document that talks about `os-release` should be understood to apply to `extension-release` too. # Options The following OS identifications parameters may be set using `os-release`: ## General information identifying the operating system `NAME=` A string identifying the operating system, without a version component, and suitable for presentation to the user. If not set, a default of `NAME=Linux` may be used. Examples: `NAME=Fedora`, `NAME="Debian GNU/Linux"`. `ID=` A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "\_" and "-") identifying the operating system, excluding any version information and suitable for processing by scripts or usage in generated filenames. If not set, a default of `ID=linux` may be used. Note that even though this string may not include characters that require shell quoting, quoting may nevertheless be used. Examples: `ID=fedora`, `ID=debian`. `ID_LIKE=` A space-separated list of operating system identifiers in the same syntax as the `ID=` setting. It should list identifiers of operating systems that are closely related to the local operating system in regards to packaging and programming interfaces, for example listing one or more OS identifiers the local OS is a derivative from. An OS should generally only list other OS identifiers it itself is a derivative of, and not any OSes that are derived from it, though symmetric relationships are possible. Build scripts and similar should check this variable if they need to identify the local operating system and the value of `ID=` is not recognized. Operating systems should be listed in order of how closely the local operating system relates to the listed ones, starting with the closest. This field is optional. Examples: for an operating system with `ID=centos`, an assignment of `ID_LIKE="rhel fedora"` would be appropriate. For an operating system with `ID=ubuntu`, an assignment of `ID_LIKE=debian` is appropriate. `PRETTY_NAME=` A pretty operating system name in a format suitable for presentation to the user. May or may not contain a release code name or OS version of some kind, as suitable. If not set, a default of `PRETTY_NAME="Linux"` may be used. Example: `PRETTY_NAME="Fedora 17 (Beefy Miracle)"` `FANCY_NAME=` Similar to `PRETTY_NAME=`, but may contain ANSI sequences and fancy UTF-8 characters such as emojis. If defined this shall preferably used when displaying the OS name on modern terminal emulators. If the terminal emulator does not support emojis, `PRETTY_NAME=` shall be shown instead, possibly with `ANSI_COLOR=` coloring. Use `\033` to encode the ESC character and `\\` to encode the backslash character. Unlike `PRETTY_NAME=` this field must not contain information that is present in other fields, in particular the version (already specified in `VERSION=`) or the codename (already specified in `VERSION_CODENAME=`). Example: `FANCY_NAME="🍅 \033[31mTomato\033[0;1mOS\033[0m"` `CPE_NAME=` A CPE name for the operating system, in URI binding syntax, following the [Common Platform Enumeration Specification](http://scap.nist.gov/specifications/cpe/) as proposed by the NIST. This field is optional. Example: `CPE_NAME="cpe:/o:fedoraproject:fedora:17"` `VARIANT=` A string identifying a specific variant or edition of the operating system suitable for presentation to the user. This field may be used to inform the user that the configuration of this system is subject to a specific divergent set of rules or default configuration settings. This field is optional and may not be implemented on all systems. Examples: `VARIANT="Server Edition"`, `VARIANT="Smart Refrigerator Edition"`. Note: this field is for display purposes only. The `VARIANT_ID` field should be used for making programmatic decisions. `VARIANT_ID=` A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "\_" and "-"), identifying a specific variant or edition of the operating system. This may be interpreted by other packages in order to determine a divergent default configuration. This field is optional and may not be implemented on all systems. Examples: `VARIANT_ID=server`, `VARIANT_ID=embedded`. ## Information about the version of the operating system `VERSION=` A string identifying the operating system version, excluding any OS name information, possibly including a release code name, and suitable for presentation to the user. This field is optional. Examples: `VERSION=17`, `VERSION="17 (Beefy Miracle)"`. `VERSION_ID=` A string (lower-case recommended, no spaces or other characters outside of 0–9, a–z, A-Z, ".", "-", "~", "^", "+" and "\_") identifying the operating system version, excluding any OS name information or release code name, and suitable for processing by scripts or usage in generated filenames. This field is optional. It is recommended to follow the [UAPI.10 Version Format Specification](https://uapi-group.org/specifications/specs/version_format_specification/) for this version string, but this is generally not enforced. Examples: `VERSION_ID=17`, `VERSION_ID=11.04`. `VERSION_CODENAME=` A string (lower-case recommended, no spaces or other characters outside of 0–9, a–z, A-Z, ".", "-", "~", "^", "+", and "\_") identifying the operating system release code name, excluding any OS name information or release version, and suitable for processing by scripts or usage in generated filenames. This field is optional and may not be implemented on all systems. Examples: `VERSION_CODENAME=buster`, `VERSION_CODENAME=xenial`. `BUILD_ID=` A string uniquely identifying the system image originally used as the installation base. In most cases, `VERSION_ID` or `IMAGE_ID`+`IMAGE_VERSION` are updated when the entire system image is replaced during an update. `BUILD_ID` may be used in distributions where the original installation image version is important: `VERSION_ID` would change during incremental system updates, but `BUILD_ID` would not. This field is optional. Examples: `BUILD_ID="2013-03-20.3"`, `BUILD_ID=201303203`. `IMAGE_ID=` A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "\_" and "-"), identifying a specific image of the operating system. This is supposed to be used for environments where OS images are prepared, built, shipped and updated as comprehensive, consistent OS images. This field is optional and may not be implemented on all systems, in particularly not on those that are not managed via images but put together and updated from individual packages and on the local system. When used in an `extension-release` file, this field is matched against the host `os-release`. If the extension declares `IMAGE_ID=`, the host must also set `IMAGE_ID=` with the same value, or the extension is rejected. To describe the extension image itself rather than constrain the host, use the prefixed variant (e.g. `SYSEXT_IMAGE_ID=`) instead. Examples: `IMAGE_ID=vendorx-cashier-system`, `IMAGE_ID=netbook-image`. `IMAGE_VERSION=` A string (lower-case recommended, no spaces or other characters outside of 0–9, a–z, A-Z, ".", "-", "~", "^", "+" and "\_") identifying the OS image version. This is supposed to be used together with `IMAGE_ID` described above, to discern different versions of the same image. It is recommended to follow the [UAPI.10 Version Format Specification](https://uapi-group.org/specifications/specs/version_format_specification/) for this version string, but this is generally not enforced. When used in an `extension-release` file, this field is matched against the host `os-release`, analogous to `IMAGE_ID=` described above. Examples: `IMAGE_VERSION=33`, `IMAGE_VERSION=47.1rc1`. `RELEASE_TYPE=` A lower-case string (no spaces or other characters outside of 0-9, a-z, ".", "\_", and "-"), describing what kind of release this version of the OS is. Known values follow: - `stable` is for normal releases of the system, suitable for production use. Generally, stable releases become end-of-life soon after the next major stable release is out, although this might not be the case if, for example, a distribution adopts a rolling release model and still be production ready. Examples include Fedora 40, Ubuntu 23.10, OpenSUSE Tumbleweed, and Arch Linux. - `lts` is for long term support releases of the system, suitable for production use and supported for an extended period of time. Generally, LTS releases continue to receive support even if newer major releases of the distribution are available. Examples include Ubuntu 24.04, Debian 12 Bookworm, and RHEL 9.4. - `development` is for unstable versions of the system, unsuitable for production use, such as alpha, beta, or rolling unstable releases. Examples include Fedora Rawhide, Debian Testing, Fedora 40 Beta, and GNOME OS Nightly. - `experiment` is for experimental builds of the system, created specifically to test some work-in-progress feature. This is meant to be used in combination with `EXPERIMENT=`. If unset, or an unknown value, assume that the release is `stable`. Examples: `RELEASE_TYPE=development`, `RELEASE_TYPE=lts`. To summarize: if the image updates are built and shipped as comprehensive units, `IMAGE_ID`+`IMAGE_VERSION` is the best fit. Otherwise, if updates eventually completely replace previously installed contents, as in a typical binary distribution, `VERSION_ID` should be used to identify major releases of the operating system. `BUILD_ID` may be used instead or in addition to `VERSION_ID` when the original system image version is important. ## Presentation information and links `HOME_URL=`; `DOCUMENTATION_URL=`; `SUPPORT_URL=`; `BUG_REPORT_URL=`; `PRIVACY_POLICY_URL=` Links to resources on the Internet related to the operating system. `HOME_URL=` should refer to the homepage of the operating system, or alternatively some homepage of the specific version of the operating system. `DOCUMENTATION_URL=` should refer to the main documentation page for this operating system. `SUPPORT_URL=` should refer to the main support page for the operating system, if there is any. This is primarily intended for operating systems which vendors provide support for. `BUG_REPORT_URL=` should refer to the main bug reporting page for the operating system, if there is any. This is primarily intended for operating systems that rely on community QA. `PRIVACY_POLICY_URL=` should refer to the main privacy policy page for the operating system, if there is any. These settings are optional, and providing only some of these settings is common. These URLs are intended to be exposed in "About this system" UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a Bug", or "Privacy Policy". The values should be in [RFC3986 format](https://tools.ietf.org/html/rfc3986), and should be `http:` or `https:` URLs, and possibly `mailto:` or `tel:`. Only one URL shall be listed in each setting. If multiple resources need to be referenced, it is recommended to provide an online landing page linking all available resources. Examples: `HOME_URL="https://fedoraproject.org/"`, `BUG_REPORT_URL="https://bugzilla.redhat.com/"`. `SUPPORT_END=` The date at which support for this version of the OS ends. (What exactly "lack of support" means varies between vendors, but generally users should assume that updates, including security fixes, will not be provided.) The value is a date in the ISO 8601 format `YYYY-MM-DD`, and specifies the first day on which support *is not* provided. For example, `SUPPORT_END=2001-01-01` means that the system was supported until the end of the last day of the previous millennium. `LOGO=` A string, specifying the name of an icon as defined by [freedesktop.org Icon Theme Specification](https://standards.freedesktop.org/icon-theme-spec/latest). This can be used by graphical applications to display an operating system's or distributor's logo. This field is optional and may not necessarily be implemented on all systems. Examples: `LOGO=fedora-logo`, `LOGO=distributor-logo-opensuse` `ANSI_COLOR=` A suggested presentation (foreground) text color when showing the OS name on the console. This should be specified as string suitable for inclusion in the ESC \[ m ANSI/ECMA-48 escape code for setting graphical rendition. This field is optional. Examples: `ANSI_COLOR="0;31"` for red, `ANSI_COLOR="1;34"` for light blue, or `ANSI_COLOR="0;38;2;60;110;180"` for Fedora blue. `ANSI_COLOR_REVERSE=` Similar to `ANSI_COLOR=`, but should encode the desired presentation color as background color, along with a suitable foreground color. This is may be used by console applications to set off "chrome" UI elements from the main terminal contents. This field is optional. `VENDOR_NAME=` The name of the OS vendor. This is the name of the organization or company which produces the OS. This field is optional. This name is intended to be exposed in "About this system" UIs or software update UIs when needed to distinguish the OS vendor from the OS itself. It is intended to be human-readable. Examples: `VENDOR_NAME="Fedora Project"` for Fedora Linux, `VENDOR_NAME="Canonical"` for Ubuntu. `VENDOR_URL=` The homepage of the OS vendor. This field is optional. The `VENDOR_NAME=` field should be set if this one is, although clients must be robust against either field not being set. The value should be in [RFC3986 format](https://tools.ietf.org/html/rfc3986), and should be `http:` or `https:` URLs. Only one URL shall be listed in the setting. Examples: `VENDOR_URL="https://fedoraproject.org/"`, `VENDOR_URL="https://canonical.com/"`. `EXPERIMENT=` A human-presentable description of what makes this build of the OS experimental. This field is optional. The `RELEASE_TYPE` field should be set to `experiment` if this field is set, otherwise clients should ignore this field. This description is intended to be exposed at system installation time, or in "About this system" UIs, to warn the user that they're installing/running an experimental build of the OS. If `RELEASE_TYPE` is `experiment` but this field is unset, the UI should still warn the user, but it will be unable to explain what exactly is experimental about the current build of the OS. Examples: `EXPERIMENT="Switch to DNF5"` for an experimental build of Fedora Linux made to test DNF5, `EXPERIMENT="Port to Apple M3 chip"` for experimental builds of Asahi Linux ported to the Apple M3 SoC, `EXPERIMENT="Mutter !1441: Dynamic triple/double buffering (v4)"` for builds of GNOME OS created by Mutter's CI for merge request !1441. `EXPERIMENT_URL=` The main informational page about what makes the current OS build experimental, where users can learn more about the experiment's status and potentially leave feedback. This field is optional. The `EXPERIMENT=` field should be set if this one is, although clients must be robust against either field not being set. The value should be in [RFC3986 format](https://tools.ietf.org/html/rfc3986), and should be `http:` or `https:` URLs. Only one URL shall be listed in the setting. Examples, corresponding to the examples above in `EXPERIMENT=`: `EXPERIMENT_URL="https://fedoraproject.org/wiki/Changes/SwitchToDnf5"`, `EXPERIMENT_URL="https://github.com/AsahiLinux/docs/wiki/M3-Series-Feature-Support"`, `EXPERIMENT_URL="https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/1441"`. ## Distribution-level defaults and metadata `DEFAULT_HOSTNAME=` A string specifying the hostname if `hostname(5)` is not present and no other configuration source specifies the hostname. Must be either a single DNS label (a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the format allowed for DNS domain name labels), or a sequence of such labels separated by single dots that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux limitation (DNS allows longer names). See `org.freedesktop.hostname1(5)` for a description of how `systemd-hostnamed.service(8)` determines the fallback hostname. `ARCHITECTURE=` A string that specifies which CPU architecture the userspace binaries require. The architecture identifiers are the same as for `ConditionArchitecture=` described in `systemd.unit(5)`. The field is optional and should only be used when just single architecture is supported. It may provide redundant information when used in a GPT partition with a GUID type that already encodes the architecture. If this is not the case, the architecture should be specified in e.g., an extension image, to prevent an incompatible host from loading it. `SYSEXT_LEVEL=` A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, a–z, ".", "\_" and "-") identifying the operating system extensions support level, to indicate which extension images are supported. See `/usr/lib/extension-release.d/extension-release.IMAGE`, [initrd](https://docs.kernel.org/admin-guide/initrd.html) and `systemd-sysext(8)`) for more information. Examples: `SYSEXT_LEVEL=2`, `SYSEXT_LEVEL=15.14`. `CONFEXT_LEVEL=` Semantically the same as `SYSEXT_LEVEL=` but for confext images. See `/etc/extension-release.d/extension-release.IMAGE` for more information. Examples: `CONFEXT_LEVEL=2`, `CONFEXT_LEVEL=15.14`. `SYSEXT_SCOPE=` Takes a space-separated list of one or more of the strings `system`, `initrd` and `portable`. This field is only supported in `extension-release.d/` files and indicates what environments the system extension is applicable to: i.e. to regular systems, to initrds and exitrds, or to portable service images. If not specified, `SYSEXT_SCOPE=system portable` is implied, i.e. any system extension without this field is applicable to regular systems and to portable service environments, but not to initrd/exitrd environments. `CONFEXT_SCOPE=` Semantically the same as `SYSEXT_SCOPE=` but for confext images. `PORTABLE_PREFIXES=` Takes a space-separated list of one or more valid prefix match strings for the [Portable Services](https://systemd.io/PORTABLE_SERVICES) logic. This field serves two purposes: it is informational, identifying portable service images as such (and thus allowing them to be distinguished from other OS images, such as bootable system images). It is also used when a portable service image is attached: the specified or implied portable service prefix is checked against the list specified here, to enforce restrictions how images may be attached to a system. `PORTABLE_SCOPE=` Specifies the scope of the portable service. Takes one of `system`, `user`, or `any`. When set to `system`, the portable service can only be attached to the system instance of `systemd-portabled`. When set to `user`, the portable service can only be attached to the user instance of `systemd-portabled`. When set to `any`, the portable service can be attached to both the system and user instances of `systemd-portabled`. If not set, `PORTABLE_SCOPE=system` is implied. ## Notes If you are using this file to determine the OS or a specific version of it, use the `ID` and `VERSION_ID` fields, possibly with `ID_LIKE` as fallback for `ID`. When looking for an OS identification string for presentation to the user use the `PRETTY_NAME` field. Note that operating system vendors may choose not to provide version information, for example to accommodate for rolling releases. In this case, `VERSION` and `VERSION_ID` may be unset. Applications should not rely on these fields to be set. Operating system vendors may extend the file format and introduce new fields. It is highly recommended to prefix new fields with an OS-specific name in order to avoid name clashes. Applications reading this file must ignore unknown fields. Example: `DEBIAN_BTS="debbugs://bugs.debian.org/"`. Container and sandbox runtime managers may make the host's identification data available to applications by providing the host's `/etc/os-release` (if available, otherwise `/usr/lib/os-release` as a fallback) as `/run/host/os-release`. # Examples
`os-release` file for Fedora Workstation
NAME=Fedora VERSION="32 (Workstation Edition)" ID=fedora VERSION_ID=32 PRETTY_NAME="Fedora 32 (Workstation Edition)" ANSI_COLOR="0;38;2;60;110;180" LOGO=fedora-logo-icon CPE_NAME="cpe:/o:fedoraproject:fedora:32" HOME_URL="https://fedoraproject.org/" DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/" SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help" BUG_REPORT_URL="https://bugzilla.redhat.com/" REDHAT_BUGZILLA_PRODUCT="Fedora" REDHAT_BUGZILLA_PRODUCT_VERSION=32 REDHAT_SUPPORT_PRODUCT="Fedora" REDHAT_SUPPORT_PRODUCT_VERSION=32 PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy" VARIANT="Workstation Edition" VARIANT_ID=workstation
`extension-release` file for an extension for Fedora Workstation 32
ID=fedora VERSION_ID=32
Reading `os-release` in `sh(1)`
Reading `os-release` in `python(1)` (versions \>= 3.10)
See docs for `platform.freedesktop_os_release` for more details.
Reading `os-release` in `python(1)` (any version)
Note that the above version that uses the built-in implementation is preferred in most cases, and the open-coded version here is provided for reference.
# See Also `systemd(1)`, `lsb_release(1)`, `hostname(5)`, `machine-id(5)`, `machine-info(5)` # pam_systemd systemd pam_systemd 8 pam_systemd Register user sessions in the systemd login manager `pam_systemd.so` # Description `pam_systemd` registers user sessions with the systemd login manager `systemd-logind.service(8)`, and hence the systemd control group hierarchy. The module also applies various resource management and runtime parameters to the new session, as configured in the [JSON User Records](https://systemd.io/USER_RECORD) of the user, when one is defined. On login, this module — in conjunction with `systemd-logind.service` — ensures the following: 1. If it does not exist yet, the user runtime directory `/run/user/$UID` is either created or mounted as new `tmpfs` file system with quota applied, and its ownership changed to the user that is logging in. 2. The `$XDG_SESSION_ID` environment variable is initialized. If auditing is available and `pam_loginuid.so` was run before this module (which is highly recommended), the variable is initialized from the auditing session id (`/proc/self/sessionid`). Otherwise, an independent session counter is used. 3. A new systemd scope unit is created for the session. If this is the first concurrent session of the user, an implicit per-user slice unit below `user.slice` is automatically created and the scope placed into it. An instance of the system service `user@.service`, which runs the systemd user manager instance, is started. 4. The `$TZ`, `$EMAIL` and `$LANG` environment variables are configured for the user, based on the respective data from the user's JSON record (if it is defined). Moreover, any environment variables explicitly configured in the user record are imported, and the umask, nice level, and resource limits initialized. On logout, this module ensures the following: 1. If enabled in `logind.conf(5)` (`KillUserProcesses=`), all processes of the session are terminated. If the last concurrent session of a user ends, the user's systemd instance will be terminated too, and so will the user's slice unit. 2. If the last concurrent session of a user ends, the user runtime directory `/run/user/$UID` and all its contents are removed, too. If the system was not booted up with systemd as init system, this module does nothing and immediately returns `PAM_SUCCESS`. # Options The following options are understood: `class=` Takes a string argument which sets the session class. The `XDG_SESSION_CLASS` environment variable (see below) takes precedence. See `sd_session_get_class(3)` for a way to query the class of a session. The following session classes are defined: | Name | Explanation | |----|----| | `user` | A regular interactive user session. This is the default class for sessions for which a TTY or X display is known at session registration time. | | `user-early` | Similar to `user` but sessions of this class are not ordered after `systemd-user-sessions.service(8)`, i.e. may be started before regular sessions are allowed to be established. This session class is the default for sessions of the root user that would otherwise qualify for the `user` class, see above. (Added in v256.) | | `user-light` | Similar to `user`, but sessions of this class will not pull in the `user@.service(5)` of the user, and thus possibly have no service manager of the user running. (Added in v258.) | | `user-early-light` | Similar to `user-early`, but sessions of this class will not pull in the `user@.service(5)` of the user, and thus possibly have no service manager of the user running. (Added in v258.) | | `user-incomplete` | Similar to `user` but for sessions which are not fully set up yet, i.e. have no home directory mounted or similar. This is used by `systemd-homed.service(8)` to allow users to log in via `ssh(1)` before their home directory is mounted, delaying the mount until the user provided the unlock password. Sessions of this class are upgraded to the regular `user` class once the home directory is activated. | | `greeter` | Similar to `user` but for sessions that are spawned by a display manager ephemerally and which prompt the user for login credentials. | | `lock-screen` | Similar to `user` but for sessions that are spawned by a display manager ephemerally and which show a lock screen that can be used to unlock locked user accounts or sessions. | | `background` | Used for background sessions, such as those invoked by `cron(8)` and similar tools. This is the default class for sessions for which no TTY or X display is known at session registration time. | | `background-light` | Similar to `background`, but sessions of this class will not pull in the `user@.service(5)` of the user, and thus possibly have no service manager of the user running. (Added in v256.) | | `manager` | The `user@.service(5)` service of the user is registered under this session class. (Added in v256.) | | `manager-early` | Similar to `manager`, but for the root user. Compare with the `user` vs. `user-early` situation. (Added in v256.) | | `none` | Skips registering this session with logind. No session scope will be created, and the user service manager will not be started. (Added in v258.) | Session Classes If no session class is specified via either the PAM module option or via the `$XDG_SESSION_CLASS` environment variable, the class is automatically chosen, depending on various session parameters, such as the session type (if known), whether the session has a TTY or X11 display, and the user disposition. Note that various tools allow setting the session class for newly allocated PAM sessions explicitly by means of the `$XDG_SESSION_CLASS` environment variable. For example, classic UNIX cronjobs support environment variable assignments (see `crontab(5)`), which may be used to choose between the `background` and `background-light` session class individually per cronjob, or `run0 --setenv=XDG_SESSION_CLASS=user-light` may be used to choose between `user` and `user-light` for invoked privileged sessions. `type=` Takes a string argument which sets the session type. The `XDG_SESSION_TYPE` environment variable (see below) takes precedence. One of `unspecified`, `tty`, `x11`, `wayland`, `mir`, or `web`. See `sd_session_get_type(3)` for details about the session type. `desktop=` Takes a single, short identifier string for the desktop environment. The `XDG_SESSION_DESKTOP` environment variable (see below) takes precedence. This may be used to indicate the session desktop used, where this applies and if this information is available. For example: `GNOME`, or `KDE`. It is recommended to use the same identifiers and capitalization as for `$XDG_CURRENT_DESKTOP`, as defined by the [Desktop Entry Specification](https://standards.freedesktop.org/desktop-entry-spec/latest/). (However, note that the option only takes a single item, and not a colon-separated list like `$XDG_CURRENT_DESKTOP`.) See `sd_session_get_desktop(3)` for further details. `area=` Takes a filename as parameter. If specified and the user logs into their account the `$HOME` environment variable will be set to `~/Areas/` suffixed by the specified string, but only if that directory exists. Moreover, the `$XDG_AREA` variable will be set to the (unprefixed) parameter. This functionality may be used to maintain multiple separate secondary home directories within the primary home directory of the user. Typically, the area to log into is specified while logging in, if the account permits that (accounts provided by `pam_systemd_home(8)` do), but this parameter may be used to define a default if that's not provided. Note that this only adjusts `$HOME` during login, it does not affect the otherwise reported home directory of the user. Specifically this means that `sshd(8)` will continue to look for SSH keys of the user only in the primary home directory of the user, not in any of their areas. Note that the default area to log into can also be configured as part of the user account. The area specified via `area=` overrides the default area configured there. Also note that if the area is specified explicitly by the user at login time, it overrides both. Also note that setting this parameter to an empty string has the effect of undoing the effect of any default area configured as part of the user record, i.e. ensuring the user logs into the primary home directory of their account. For details on the area concept see `pam_systemd_home(8)`. `inhibit=` Takes a colon-separated list of inhibitor lock types to acquire for the duration of the session. The `XDG_SESSION_INHIBIT` environment variable (see below) takes precedence. Inhibitor locks prevent the system from performing certain actions, such as sleeping. The supported lock types are the same as for the `systemd-inhibit(1)` command, e.g. `shutdown`, `sleep`, `idle`. If not set, no inhibitor lock is acquired. The lock is taken in block mode, the requested actions are fully inhibited as long as the session is active. `inhibit-why=` Takes a short human-readable string describing the reason for the inhibitor lock acquired via `inhibit=`. The `XDG_SESSION_INHIBIT_WHY` environment variable (see below) takes precedence. Defaults to `Active PAM session` if not set. Only has an effect if `inhibit=` or `XDG_SESSION_INHIBIT` is set. `default-capability-bounding-set=`; `default-capability-ambient-set=` Takes a comma-separated list of process capabilities (e.g. `CAP_WAKE_ALARM`, `CAP_BLOCK_SUSPEND`, …) to set for the invoked session's processes, if the user record does not encode appropriate sets of capabilities directly. See `capabilities(7)` for details on the capabilities concept. If not specified, the default bounding set is left as is (i.e. usually contains the full set of capabilities). The default ambient set is set to `CAP_WAKE_ALARM` for regular users if the PAM session is associated with a local seat or if it is invoked for the systemd user service `user@.service`. Otherwise, defaults to the empty set. `debug`\[=\] Takes an optional boolean argument. If yes or without the argument, the module will log debugging information as it operates. # Module Types Provided Only `session` is provided. # Environment The following environment variables are initialized by the module and available to the processes of the user's session: `$XDG_SESSION_ID` A short session identifier, suitable to be used in filenames. The string itself should be considered opaque, although often it is just the audit session ID as reported by `/proc/self/sessionid`. Each ID will be assigned only once during machine uptime. It may hence be used to uniquely label files or other resources of this session. Combine this ID with the boot identifier, as returned by `sd_id128_get_boot(3)`, for a globally unique identifier. `$XDG_RUNTIME_DIR` Path to a user-private user-writable directory that is bound to the user login time on the machine. It is automatically created the first time a user logs in and removed on the user's final logout. If a user logs in twice at the same time, both sessions will see the same `$XDG_RUNTIME_DIR` and the same contents. If a user logs in once, then logs out again, and logs in again, the directory contents will have been lost in between, but applications should not rely on this behavior and must be able to deal with stale files. To store session-private data in this directory, the user should include the value of `$XDG_SESSION_ID` in the filename. This directory shall be used for runtime file system objects such as `AF_UNIX` sockets, FIFOs, PID files and similar. It is guaranteed that this directory is local and fully-featured by the standards of the operating system. For further details, see the [XDG Base Directory Specification](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html). `$XDG_RUNTIME_DIR` is not set if the current user is not the original user of the session. `$TZ`; `$EMAIL`; `$LANG` If a JSON user record is known for the user logging in these variables are initialized from the respective data in the record. `$SHELL_PROMPT_PREFIX`; `$SHELL_PROMPT_SUFFIX`; `$SHELL_WELCOME` These environment variables are initialized from the service credentials `shell.prompt.prefix`, `shell.prompt.suffix` and `shell.welcome` if set. They are passed to the invoked session processes, where they are imported into any shell prompt (specifically `$SHELL_PROMPT_PREFIX` is added as prefix to `$PS1`, and `$SHELL_PROMPT_SUFFIX` as suffix) or printed on screen when a shell first initializes. The following environment variables are read by the module and may be used by the PAM service to pass metadata to the module. If these variables are not set when the PAM module is invoked but can be determined otherwise they are set by the module, so that these variables are initialized for the session and applications if known at all. `$XDG_SESSION_TYPE` The session type. This may be used instead of `type=` on the module parameter line, and is usually preferred. `$XDG_SESSION_CLASS` The session class. This may be used instead of `class=` on the module parameter line, and is usually preferred. `$XDG_SESSION_DESKTOP` The desktop identifier. This may be used instead of `desktop=` on the module parameter line, and is usually preferred. `$XDG_SEAT` The seat name the session shall be registered for, if any. `$XDG_VTNR` The VT number the session shall be registered for, if any. (Only applies to seats with a VT available, such as `seat0`) `$XDG_AREA` If an area (secondary home directories of the user, within the primary home directory) to log into has been selected this variable is set to the area name (without any path prefix). It is otherwise unset. For details about areas, see above. `$XDG_SESSION_EXTRA_DEVICE_ACCESS` The set of additional hardware devices that the session shall be granted access to. For every `ID` in the list, the session is granted access to all devices tagged with `xaccess-ID` in udev. `$XDG_SESSION_INHIBIT` The inhibitor lock types to acquire for the duration of the session, as a colon-separated list. This may be used instead of `inhibit=` on the module parameter line. `$XDG_SESSION_INHIBIT_WHY` The reason string for the inhibitor lock. This may be used instead of `inhibit-why=` on the module parameter line. If not set, `pam_systemd` will initialize `$XDG_SEAT` and `$XDG_VTNR` based on the `$DISPLAY` variable (if the latter is set). # Session limits PAM modules earlier in the stack, that is those that come before `pam_systemd.so`, can set session scope limits using the PAM context objects. The data for these objects is provided as `NUL`-terminated C strings and maps directly to the respective unit resource control directives. Note that these limits apply to individual sessions of the user, they do not apply to all user processes as a combined whole. In particular, the per-user `user@.service` unit instance, which runs the `systemd --user` manager process and its children, and is tracked outside of any session, being shared by all the user's sessions, is not covered by these limits. See `systemd.resource-control(5)` for more information about the resources. Also, see `pam_set_data(3)` for additional information about how to set the context objects. `systemd.memory_max=` Sets unit `MemoryMax=`. `systemd.tasks_max=` Sets unit `TasksMax=`. `systemd.cpu_weight=` Sets unit `CPUWeight=`. `systemd.io_weight=` Sets unit `IOWeight=`. `systemd.runtime_max_sec=` Sets unit `RuntimeMaxSec=`. Example data as can be provided from an another PAM module: pam_set_data(handle, "systemd.memory_max", (void *)"200M", cleanup); pam_set_data(handle, "systemd.tasks_max", (void *)"50", cleanup); pam_set_data(handle, "systemd.cpu_weight", (void *)"100", cleanup); pam_set_data(handle, "systemd.io_weight", (void *)"340", cleanup); pam_set_data(handle, "systemd.runtime_max_sec", (void *)"3600", cleanup); # Example Here's an example PAM configuration fragment that allows users sessions to be managed by `systemd-logind.service`: #%PAM-1.0 -auth [success=done authtok_err=bad perm_denied=bad maxtries=bad default=ignore] pam_systemd_home.so auth sufficient pam_unix.so auth required pam_deny.so account required pam_nologin.so -account [success=done authtok_expired=bad new_authtok_reqd=bad maxtries=bad acct_expired=bad default=ignore] pam_systemd_home.so account required pam_unix.so -password sufficient pam_systemd_home.so password sufficient pam_unix.so sha512 shadow try_first_pass password required pam_deny.so -session optional pam_keyinit.so revoke -session optional pam_loginuid.so -session optional pam_systemd_home.so -session optional pam_systemd.so session required pam_unix.so # See Also `systemd(1)`, `systemd-user-sessions.service(8)`, `user@.service(5)`, `systemd-logind.service(8)`, `logind.conf(5)`, `loginctl(1)`, `pam_systemd_home(8)`, `systemd-inhibit(1)`, `pam.conf(5)`, `pam.d(5)`, `pam(8)`, `pam_loginuid(8)`, `systemd.scope(5)`, `systemd.slice(5)`, `systemd.service(5)` # pam_systemd_home systemd pam_systemd_home 8 pam_systemd_home Authenticate users and mount home directories via systemd-homed.service `pam_systemd_home.so` # Description `pam_systemd_home` ensures that home directories managed by `systemd-homed.service(8)` are automatically activated (mounted) on user login, and are deactivated (unmounted) when the last session of the user ends. For such users, it also provides authentication (when per-user disk encryption is used, the disk encryption key is derived from the authentication credential supplied at login time), account management (the [JSON user record](https://systemd.io/USER_RECORD/) embedded in the home store contains account details), and implements the updating of the encryption password (which is also used for user authentication). # Options The following options are understood: `suspend=` Takes a boolean argument. If true, the home directory of the user will be suspended automatically during system suspend; if false it will remain active. Automatic suspending of the home directory improves security substantially as secret key material is automatically removed from memory before the system is put to sleep and must be re-acquired (through user re-authentication) when coming back from suspend. It is recommended to set this parameter for all PAM applications that have support for automatically re-authenticating via PAM on system resume. If multiple sessions of the same user are open in parallel the user's home directory will be left unsuspended on system suspend as long as at least one of the sessions does not set this parameter to on. Defaults to off. Note that TTY logins generally do not support re-authentication on system resume. Re-authentication on system resume is primarily a concept implementable in graphical environments, in the form of lock screens brought up automatically when the system goes to sleep. This means that if a user concurrently uses graphical login sessions that implement the required re-authentication mechanism and console logins that do not, the home directory is not locked during suspend, due to the logic explained above. That said, it is possible to set this field for TTY logins too, ignoring the fact that TTY logins actually do not support the re-authentication mechanism. In that case the TTY sessions will appear hung until the user logs in on another virtual terminal (regardless of whether via another TTY session or graphically) which will resume the home directory and unblock the original TTY session. (Do note that lack of screen locking on TTY sessions means even though the TTY session appears hung, keypresses can still be queued into it, and the existing screen contents be read without re-authentication; this limitation is unrelated to the home directory management `pam_systemd_home` and `systemd-homed.service` implement.) Turning this option on by default is highly recommended for all sessions, but only if the service managing these sessions correctly implements the aforementioned re-authentication. Note that the re-authentication must take place from a component running outside of the user's context, so that it does not require access to the user's home directory for operation. Traditionally, most desktop environments do not implement screen locking this way, and need to be updated accordingly. This setting may also be controlled via the `$SYSTEMD_HOME_SUSPEND` environment variable (see below), which `pam_systemd_home` reads during initialization and sets for sessions. If both the environment variable is set and the module parameter specified the latter takes precedence. `debug`\[=\] Takes an optional boolean argument. If yes or without the argument, the module will log debugging information as it operates. # Home Area Support Home directories managed by `systemd-homed.service(8)` support multiple home "areas", which are additional secondary home directories of the user within the primary home directory. An example: at login time if a user `lennart` with a home directory of `/home/lennart` specifies `lennart%versuch1` as account name during login, then `pam_systemd_home` will execute a login into `lennart` but ensure that the `$HOME` variable is set to `/home/lennart/Areas/versuch1` instead of the usual `/home/lennart`. This is particularly useful when sharing the same home directory between multiple systems (for example between a host and a VM), with the desire to share the home directory to a large degree, but still have separate session configuration in place. Note that the default area to log into can also be encoded in the user record, and it can be specified among `pam_systemd(8)` configuration parameters. However, an explicit area specified at login time (via the `%` described above) overrides any such default. Also note that simply suffixing an account with `%` at login time (i.e. specifying an empty area name) has the effect of ensuring a login into the primary home directory, overriding any default area configuration via the user record or PAM. Note that not all login mechanisms are compatible with the `%` syntax at login time. Most notably `ssh(8)` is not. Note that the area directory to log into must exist for the area specification to be respected. If an area is specified during login via the `%` logic (or the other mentioned mechanisms) and it does not actually exist the request will be ignored, and the user will log into the primary home directory instead. Typically, in order to make use of the mechanism set up an area first, like this: lennart@zeta$ mkdir -p ~/Areas lennart@zeta$ cp -av /etc/skel ~/Areas/versuch1 This should be enough to log into the newly created area, either via a regular terminal (using `lennart%versuch1` when prompted for a user name), or via `run0(1)`: lennart@zeta$ run0 --area=versuch1 # Module Types Provided The module implements all four PAM operations: `auth` (to allow authentication using the encrypted data), `account` (because users with `systemd-homed.service` user accounts are described in a [JSON user record](https://systemd.io/USER_RECORD/) and may be configured in more detail than in the traditional Linux user database), `session` (because user sessions must be tracked in order to implement automatic release when the last session of the user is gone), `password` (to change the encryption password — also used for user authentication — through PAM). # Environment The following environment variables are initialized by the module and available to the processes of the user's session: `$SYSTEMD_HOME=1` Indicates that the user's home directory is managed by `systemd-homed.service`. `$SYSTEMD_HOME_SUSPEND=` Indicates whether the session has been registered with the suspend mechanism enabled or disabled (see above). The variable's value is either `0` or `1`. Note that the module both reads the variable when initializing, and sets it for sessions. # Example Here's an example PAM configuration fragment that permits users managed by `systemd-homed.service` to log in: #%PAM-1.0 -auth [success=done authtok_err=bad perm_denied=bad maxtries=bad default=ignore] pam_systemd_home.so auth sufficient pam_unix.so auth required pam_deny.so account required pam_nologin.so -account [success=done authtok_expired=bad new_authtok_reqd=bad maxtries=bad acct_expired=bad default=ignore] pam_systemd_home.so account required pam_unix.so -password sufficient pam_systemd_home.so password sufficient pam_unix.so sha512 shadow try_first_pass password required pam_deny.so -session optional pam_keyinit.so revoke -session optional pam_loginuid.so -session optional pam_systemd_home.so -session optional pam_systemd.so session required pam_unix.so # See Also `systemd(1)`, `systemd-homed.service(8)`, `homed.conf(5)`, `homectl(1)`, `pam_systemd(8)`, `pam.conf(5)`, `pam.d(5)`, `pam(8)` # pam_systemd_loadkey systemd pam_systemd_loadkey 8 pam_systemd_loadkey Read password from kernel keyring and set it as PAM authtok `pam_systemd_loadkey.so` # Description `pam_systemd_loadkey` reads a NUL-separated password list from the kernel keyring, and sets the last password in the list as the PAM authtok, which can be used by e.g. `pam_get_authtok(3)`. The password list is supposed to be stored in the "user" keyring of the root user, by an earlier call to `systemd-ask-password(1)` with `--keyname=`. You can pass the keyname to `pam_systemd_loadkey` via the `keyname=` option. # Options The following options are understood: `keyname=` Takes a string argument which sets the keyname to read. The default is `cryptsetup`. During boot, `systemd-cryptsetup@.service(8)` stores a passphrase or PIN in the keyring. The LUKS2 volume key can also be used, via the `link-volume-key` option in `crypttab(5)`. | Value | Description | |------------|----------------------------| | cryptsetup | Passphrase or recovery key | | fido2-pin | Security token PIN | | luks2-pin | LUKS2 token PIN | | tpm2-pin | TPM2 PIN | Possible values for `keyname`. `debug` The module will log debugging information as it operates. # Example This module is intended to be used when you use LUKS with a passphrase, enable autologin in the display manager, and want to unlock Gnome Keyring / KDE KWallet automatically. So in total, you only enter one password during boot. You need to set the password of your Gnome Keyring/KWallet to the same as your LUKS passphrase. Then add the following lines to your display manager's PAM config under `/etc/pam.d/` (e.g. `sddm-autologin`): -auth optional pam_systemd_loadkey.so -auth optional pam_gnome_keyring.so -session optional pam_gnome_keyring.so auto_start -session optional pam_kwallet5.so auto_start And add the following lines to your display manager's systemd service file, so it can access root's keyring: [Service] KeyringMode=inherit In this setup, early during the boot process, `systemd-cryptsetup@.service(8)` will ask for the passphrase and store it in the kernel keyring with the keyname `cryptsetup`. Then when the display manager does the autologin, `pam_systemd_loadkey` will read the passphrase from the kernel keyring, set it as the PAM authtok, and then `pam_gnome_keyring` and `pam_kwallet5` will unlock with the same passphrase. # portablectl systemd portablectl 1 portablectl Attach, detach or inspect portable service images portablectl OPTIONS COMMAND NAME # Description `portablectl` may be used to attach, detach or inspect portable service images. It's primarily a command interfacing with `systemd-portabled.service(8)`. Portable service images contain an OS file system tree along with `systemd(1)` unit file information. A service image may be "attached" to the local system. If attached, a set of unit files are copied from the image to the host, and extended with `RootDirectory=` or `RootImage=` assignments (in case of service units) pointing to the image file or directory, ensuring the services will run within the file system context of the image. Portable service images are an efficient way to bundle multiple related services and other units together, and transfer them as a whole between systems. When these images are attached to the local system, the contained units may run in most ways like regular system-provided units, either with full privileges or inside strict sandboxing, depending on the selected configuration. For more details, see [Portable Services](https://systemd.io/PORTABLE_SERVICES). Portable service images may be of the following kinds: - Directory trees containing an OS, including the top-level directories `/usr/`, `/etc/`, and so on. - btrfs subvolumes containing OS trees, similar to normal directory trees. - Binary "raw" disk images containing MBR or GPT partition tables and Linux file system partitions. (These must be regular files, with the `.raw` suffix.) # Commands The following commands are understood: `list` List available portable service images. This will list all portable service images discovered in the portable image search paths (see below), along with brief metadata and state information. Note that many of the commands below may both operate on images inside and outside of the search paths. This command is hence mostly a convenience option, the commands are generally not restricted to what this list shows. `attach` \ \[\\] Attach a portable service image to the host system. Expects a file system path to a portable service image file or directory as first argument. If the specified path contains no slash character (`/`) it is understood as image filename that is searched for in the portable service image search paths (see below). To reference a file in the current working directory prefix the filename with `./` to avoid this search path logic. When a portable service is attached four operations are executed: 1. All unit files of types `.service`, `.socket`, `.target`, `.timer` and `.path` which match the indicated unit file name prefix are copied from the image to the host's `/etc/systemd/system.attached/` directory (or `/run/systemd/system.attached/` — depending whether `--runtime` is specified, see below), which is included in the built-in unit search path of the system service manager. 2. For unit files of type `.service` a drop-in is added to these copies that adds `RootDirectory=` or `RootImage=` settings (see `systemd.unit(5)` for details), that ensures these services are run within the file system of the originating portable service image. 3. A second drop-in is created: the "profile" drop-in, that may contain additional security settings (and other settings). A number of profiles are available by default but administrators may define their own ones. See below. 4. If the portable service image file is not already in the search path (see below), a symbolic link to it is created in `/etc/portables/` or `/run/portables/`, to make sure it is included in it. By default, all unit files whose names start with a prefix generated from the image's file name are copied out. Specifically, the prefix is determined from the image file name with any suffix such as `.raw` removed, truncated at the first occurrence of an underscore character (`_`), if there is one. The underscore logic is supposed to be used for versioning so that an image file `foobar_47.11.raw` will result in a unit file matching prefix of `foobar`. This prefix is then compared with all unit files names contained in the image in the usual directories, but only unit file names where the prefix is followed by `-`, `.` or `@` are considered. Example: if a portable service image file is named `foobar_47.11.raw` then by default all its unit files with names such as `foobar-quux-waldi.service`, `foobar.service` or `foobar@.service` will be considered. It's possible to override the matching prefix: all strings listed on the command line after the image file name are considered prefixes, overriding the implicit logic where the prefix is derived from the image file name. By default, after the unit files are attached the service manager's configuration is reloaded, except when `--no-reload` is specified (see below). This ensures that the new units made available to the service manager are seen by it. If `--now` and/or `--enable` are passed, the portable services are immediately started (blocking operation unless `--no-block` is passed) and/or enabled after attaching the image. When images are attached, an image policy will be generated that pins the attached image by the exact content that was found while attaching, so that it cannot be swapped downgrading security (e.g.: removing dm-verity protection) without a full reinstallation. For more details on policies, see `systemd.image-policy(7)`. `detach` \ \[\\] Detaches a portable service image from the host. This undoes the operations executed by the `attach` command above, and removes the unit file copies, drop-ins and image symlink again. This command expects an image name or path as parameter. Note that if a path is specified only the last component of it (i.e. the file or directory name itself, not the path to it) is used for finding matching unit files. This is a convenience feature to allow all arguments passed as `attach` also to `detach`. If `--now` and/or `--enable` are passed, the portable services are immediately stopped (blocking operation) and/or disabled before detaching the image. Prefix(es) are also accepted, to be used in case the unit names do not match the image name as described in the `attach`. `reattach` \ \[\\] Detaches an existing portable service image from the host, and immediately attaches it again. This is useful in case the image was replaced. Running units are not stopped during the process. Partial matching, to allow for different versions in the image name, is allowed: only the part before the first `_` character has to match. If the new image does not exist, the existing one will not be detached. The parameters follow the same syntax as the `attach` command. If `--now` and/or `--enable` are passed, the portable services are immediately stopped if removed, started and/or enabled if added, or restarted if updated. Prefixes are also accepted, in the same way as described in the `attach` case. `inspect` \ \[\\] Extracts various metadata from a portable service image and presents it to the caller. Specifically, the `os-release(5)` file of the image is retrieved as well as all matching unit files. By default, a short summary showing the most relevant metadata in combination with a list of matching unit files is shown (that is the unit files `attach` would install to the host system). If combined with `--cat` (see above), the `os-release` data and the units files' contents is displayed unprocessed. This command is useful to determine whether an image qualifies as portable service image, and which unit files are included. This command expects the path to the image as parameter, optionally followed by a list of unit file prefixes to consider, similar to the `attach` command described above. `is-attached` \ Determines whether the specified image is currently attached or not. Unless combined with the `--quiet` switch this will show a short state identifier for the image. Specifically: | State | Description | |----|----| | `detached` | The image is currently not attached. | | `attached` | The image is currently attached, i.e. its unit files have been made available to the host system. | | `attached-runtime` | Like `attached`, but the unit files have been made available transiently only, i.e. the `attach` command has been invoked with the `--runtime` option. | | `enabled` | The image is currently attached, and at least one unit file associated with it has been enabled. | | `enabled-runtime` | Like `enabled`, but the unit files have been made available transiently only, i.e. the `attach` command has been invoked with the `--runtime` option. | | `running` | The image is currently attached, and at least one unit file associated with it is running. | | `running-runtime` | The image is currently attached transiently, and at least one unit file associated with it is running. | Image attachment states `read-only` \ \[\\] Marks or (unmarks) a portable service image read-only. Takes an image name, followed by a boolean as arguments. If the boolean is omitted, positive is implied, i.e. the image is marked read-only. `remove` \… Removes one or more portable service images. Note that this command will only remove the specified image path itself — it refers to a symbolic link then the symbolic link is removed and not the image it points to. `set-limit` \[\\] \ Sets the maximum size in bytes that a specific portable service image, or all images, may grow up to on disk (disk quota). Takes either one or two parameters. The first, optional parameter refers to a portable service image name. If specified, the size limit of the specified image is changed. If omitted, the overall size limit of the sum of all images stored locally is changed. The final argument specifies the size limit in bytes, possibly suffixed by the usual K, M, G, T units. If the size limit shall be disabled, specify `-` as size. Note that per-image size limits are only supported on btrfs file systems. Also, depending on `BindPaths=` settings in the portable service's unit files directories from the host might be visible in the image environment during runtime which are not affected by this setting, as only the image itself is counted against this limit. # Options The following options are understood: `-q`; `--quiet` Suppresses additional informational output while running. `-p` \; `--profile=PROFILE` When attaching an image, select the profile to use. By default, the `default` profile is used. Attaching fails if the selected profile does not exist. For details about profiles, see below. `--copy=` When attaching an image, select whether to prefer copying or symlinking of files installed into the host system. Takes one of `copy` (files will be copied), `symlink` (to prefer creation of symbolic links), `auto` for an intermediary mode where security profile drop-ins and images are symlinked while unit files are copied, or `mixed` (since v256) where security profile drop-ins are symlinked while unit files and images are copied. Note that this option expresses a preference only, in cases where symbolic links cannot be created — for example when the image operated on is a raw disk image, and hence not directly referentiable from the host file system — copying of files is used unconditionally. `--runtime` When specified the unit and drop-in files are placed in `/run/systemd/system.attached/` instead of `/etc/systemd/system.attached/`. Images attached with this option set hence remain attached only until the next reboot, while they are normally attached persistently. `--no-reload` Do not reload the service manager after attaching or detaching a portable service image. Normally the service manager is reloaded to ensure it is aware of added or removed unit files. `--cat` When inspecting portable service images, show the (unprocessed) contents of the metadata files pulled from the image, instead of brief summaries. Specifically, this will show the `os-release(5)` and unit file contents of the image. `--enable` Immediately enable/disable the portable service after attaching/detaching. `--now` Immediately start/stop/restart the portable service after attaching/before detaching/after upgrading. `--no-block` Do not block waiting for attach --now to complete. `--clean` When detaching ensure the configuration, state, logs, cache, and runtime data directories of the portable service are removed from the host system. `--extension=PATH` Add an additional image \ as an overlay on top of \ when attaching/detaching. This argument can be specified multiple times, in which case the order in which images are laid down follows the rules specified in `systemd.exec(5)` for the `ExtensionImages=` directive and for the `systemd-sysext(8)` and `systemd-confext(8)` tools. The images must contain an `extension-release` file with metadata that matches what is defined in the `os-release` of \. See: `os-release(5)`. Images can be block images, btrfs subvolumes or directories. For more information on portable services with extensions, see the `Extension Images` paragraph on [Portable Services](https://systemd.io/PORTABLE_SERVICES). Note that the same extensions have to be specified, in the same order, when attaching and detaching. `--force` Skip safety checks and attach or detach images (with extensions) without first ensuring that the units are not running, and do not insist that the `extension-release.NAME` file in the extension image has to match the image filename. # Files and Directories Portable service images are preferably stored in `/var/lib/portables/`, but are also searched for in `/etc/portables/`, `/run/portables/`, `/usr/local/lib/portables/` and `/usr/lib/portables/`. It's recommended not to place image files directly in `/etc/portables/` or `/run/portables/` (as these are generally not suitable for storing large or non-textual data), but use these directories only for linking images located elsewhere into the image search path. When a portable service image is attached, matching unit files are copied onto the host into the `/etc/systemd/system.attached/` and `/run/systemd/system.attached/` directories. When an image is detached, the unit files are removed again from these directories. # Profiles When portable service images are attached a "profile" drop-in is linked in, which may be used to enforce additional security (and other) restrictions locally. Four profile drop-ins are defined by default, and shipped in `/usr/lib/systemd/portable/profile/`. Additional, local profiles may be defined by placing them in `/etc/systemd/portable/profile/`. The default profiles are: | Name | Description | |----|----| | `default` | This is the default profile if no other profile name is set via the `--profile=` (see above). It's fairly restrictive, but should be useful for common, unprivileged system workloads. This includes write access to the logging framework, as well as IPC access to the D-Bus system. | | `nonetwork` | Very similar to `default`, but networking is turned off for any services of the portable service image. | | `strict` | A profile with very strict settings. This profile excludes IPC (D-Bus) and network access. | | `trusted` | A profile with very relaxed settings. In this profile the services run with full privileges. | Profiles For details on these profiles and their effects see their precise definitions, e.g. `/usr/lib/systemd/portable/profile/default/service.conf` and similar. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-sysext(8)`, `org.freedesktop.portable1(5)`, `systemd-portabled.service(8)`, `importctl(1)` # poweroff systemd poweroff 8 poweroff reboot halt Power off, reboot, or halt the machine poweroff OPTIONS reboot OPTIONS halt OPTIONS # Description `poweroff`, `reboot`, and `halt` may be used to power off, reboot, or halt the machine. All three commands take the same options. # Options The following options are understood: `--help` `--halt` Halt the machine, regardless of which one of the three commands is invoked. `-p`; `--poweroff` Power off the machine, when either `halt` or `poweroff` is invoked. This option is ignored when `reboot` is invoked. `--reboot` Reboot the machine, regardless of which one of the three commands is invoked. `-f`; `--force` Force immediate power-off, halt, or reboot. If specified, the command does not contact the init system. In most cases, filesystems are not properly unmounted before shutdown. For example, the command `reboot -f` is mostly equivalent to `systemctl reboot -ff`, instead of `systemctl reboot -f`. `-w`; `--wtmp-only` Only write wtmp shutdown entry, do not actually power off, reboot, or halt. `-d`; `--no-wtmp` Do not write wtmp shutdown entry. `-n`; `--no-sync` Do not sync hard disks/storage media before power-off, reboot, or halt. `--no-wall` Do not send wall message before power-off, reboot, or halt. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Notes These commands are implemented in a way that preserves basic compatibility with the original SysV commands. `systemctl(1)` verbs `poweroff`, `reboot`, `halt` provide the same functionality with some additional features. Note that on many SysV systems `halt` used to be synonymous to `poweroff`, i.e. both commands would equally result in powering the machine off. systemd is more accurate here, and `halt` results in halting the machine only (leaving power on), and `poweroff` is required to actually power it off. # See Also `systemd(1)`, `systemctl(1)`, `shutdown(8)`, `wall(1)` # pstore.conf systemd pstore.conf 5 pstore.conf pstore.conf.d PStore configuration file `/etc/systemd/pstore.conf`, `/run/systemd/pstore.conf`, `/usr/local/lib/systemd/pstore.conf`, `/usr/lib/systemd/pstore.conf`, `/etc/systemd/pstore.conf.d/*.conf`, `/run/systemd/pstore.conf.d/*.conf`, `/usr/local/lib/systemd/pstore.conf.d/*.conf`, `/usr/lib/systemd/pstore.conf.d/*.conf` # Description This file configures the behavior of `systemd-pstore(8)`, a tool for archiving the contents of the persistent storage filesystem, [pstore](https://docs.kernel.org/admin-guide/abi-testing.html#abi-sys-fs-pstore). # Options All options are configured in the \[PStore\] section: `Storage=` Controls where to archive (i.e. copy) files from the pstore filesystem. One of `none`, `external`, and `journal`. When `none`, the tool exits without processing files in the pstore filesystem. When `external` (the default), files are archived into `/var/lib/systemd/pstore/`, and logged into the journal. When `journal`, pstore file contents are logged only in the journal. `Unlink=` Controls whether or not files are removed from pstore after processing. Takes a boolean value. When true, a pstore file is removed from the pstore once it has been archived (either to disk or into the journal). When false, processing of pstore files occurs normally, but the files remain in the pstore. The default is true in order to maintain the pstore in a nearly empty state, so that the pstore has storage available for the next kernel error event. Use systemd-analyze cat-config systemd/pstore.conf to display the full config. # See Also `systemd-pstore.service(8)` # ptyctl systemd ptyctl 1 ptyctl List, monitor and hang up pseudo TTYs registered with the pseudo TTY broker ptyctl OPTIONS COMMAND NAME # Description `ptyctl` may be used to introspect and control the pseudo TTY allocations registered with the pseudo TTY broker, `systemd-ptybrokerd.service(8)`. The broker keeps the frontend (i.e. the `master`) side of registered pseudo TTYs open, while the payload — a service, a container, a virtual machine console, or similar — runs connected to the backend (i.e. the `slave`) side. `ptyctl` permits listing these pseudo TTYs, interactively connecting to them, and hanging them up. Pseudo TTYs are registered with the broker for example via `--console=broker` of `systemd-pty-forward(1)`, `systemd-nspawn(1)` and `systemd-vmspawn(1)`, or via `StandardOutput=broker` in service units, see `systemd.exec(5)`. # Commands The following commands are understood: `list` List the pseudo TTYs currently registered with the broker, showing their name, description, log tag, frontend and backend types, and backend TTY path. This command is the default if no command is specified. `monitor` \ Connect interactively to the pseudo TTY registered under the specified name: its output is forwarded to the local terminal, and local input is forwarded back to it. To disconnect, press Ctrl+\] three times within one second. Disconnecting only ends the monitor connection, the pseudo TTY itself remains registered with the broker and the payload continues to run. `hangup` \… Hang up the pseudo TTYs registered under the specified names. This executes the equivalent of `vhangup(2)` on the pseudo TTY, disconnecting the session running on its backend side. # Options The following options are understood: `--system`; `--user` Selects whether to talk to the system-wide instance or the per-user instance of `systemd-ptybrokerd.service(8)`. Defaults to `--system`. `--background=COLOR` Change the terminal background color to the specified ANSI color while monitoring a pseudo TTY. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as `40`, `41`, …, `47`, `48;2;…`, `48;5;…`. See [ANSI Escape Code (Wikipedia)](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters) for details. Only has an effect on the `monitor` command. Example: `--background=44` for a blue background. `--title=TITLE` Change the terminal title to the specified string while monitoring a pseudo TTY. Only has an effect on the `monitor` command. `--quiet`; `-q` Suppresses additional informational output while running. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-ptybrokerd.service(8)`, `systemd-pty-forward(1)`, `systemd-nspawn(1)`, `systemd-vmspawn(1)`, `systemd.exec(5)` # repart.d systemd repart.d 5 repart.d Partition Definition Files for Automatic Boot-Time Repartitioning `/etc/repart.d/*.conf`, `/run/repart.d/*.conf`, `/usr/local/lib/repart.d/*.conf`, `/usr/lib/repart.d/*.conf` # Description `repart.d/*.conf` files describe basic properties of partitions of block devices of the local system. They may be used to declare types, names and sizes of partitions that shall exist. The `systemd-repart(8)` service reads these files and attempts to add new partitions currently missing and enlarge existing partitions according to these definitions. Operation is generally incremental, i.e. when applied, what exists already is left intact, and partitions are never shrunk, moved or deleted. These definition files are useful for implementing operating system images that are prepared and delivered with minimally sized images (for example lacking any state or swap partitions), and which on first boot automatically take possession of any remaining disk space following a few basic rules. Currently, support for partition definition files is only implemented for GPT partition tables. Partition files are generally matched against any partitions already existing on disk in a simple algorithm: the partition files are sorted by their filename (ignoring the directory prefix), and then compared in order against existing partitions matching the same partition type UUID. Specifically, the first existing partition with a specific partition type UUID is assigned the first definition file with the same partition type UUID, and the second existing partition with a specific type UUID the second partition file with the same type UUID, and so on. Any left-over partition files that have no matching existing partition are assumed to define new partition that shall be created. Such partitions are appended to the end of the partition table, in the order defined by their names utilizing the first partition slot greater than the highest slot number currently in use. Any existing partitions that have no matching partition file are left as they are. Note that these definitions may only be used to create and initialize new partitions or to grow existing ones. In the latter case, it will not grow the contained files systems however; separate mechanisms, such as `systemd-growfs(8)` may be used to grow the file systems inside of these partitions. Partitions may also be marked for automatic growing via the `GrowFileSystem=` setting, in which case the file system is grown on first mount by tools that respect this flag. See below for details. # \[Partition\] Section Options `Type=` The GPT partition type UUID to match. This may be a GPT partition type UUID such as `4f68bce3-e8cd-4db1-96e7-fbcaf984b709`, or an identifier. The supported identifiers are: | Identifier | Explanation | |----|----| | `esp` | EFI System Partition | | `xbootldr` | Extended Boot Loader Partition | | `swap` | Swap partition | | `home` | Home (`/home/`) partition | | `srv` | Server data (`/srv/`) partition | | `var` | Variable data (`/var/`) partition | | `tmp` | Temporary data (`/var/tmp/`) partition | | `linux-generic` | Generic Linux file system partition | | `root` | Root file system partition type appropriate for the local architecture (an alias for an architecture root file system partition type listed below, e.g. `root-x86-64`) | | `root-verity`, `root-vty` | Verity data for the root file system partition for the local architecture | | `root-verity-sig`, `root-vsig` | Verity signature data for the root file system partition for the local architecture | | `root-secondary`, `root2` | Root file system partition of the secondary architecture of the local architecture (usually the matching 32-bit architecture for the local 64-bit architecture) | | `root-secondary-verity`, `root-vty2` | Verity data for the root file system partition of the secondary architecture | | `root-secondary-verity-sig`, `root-vsig2` | Verity signature data for the root file system partition of the secondary architecture | | `root-{arch}` | Root file system partition of the given architecture (such as `root-x86-64` or `root-riscv64`) | | `root-{arch}-verity`, `root-{arch}-vty` | Verity data for the root file system partition of the given architecture | | `root-{arch}-verity-sig`, `root-{arch}-vsig` | Verity signature data for the root file system partition of the given architecture | | `usr` | `/usr/` file system partition type appropriate for the local architecture (an alias for an architecture `/usr/` file system partition type listed below, e.g. `usr-x86-64`) | | `usr-verity`, `usr-vty` | Verity data for the `/usr/` file system partition for the local architecture | | `usr-verity-sig`, `usr-vsig` | Verity signature data for the `/usr/` file system partition for the local architecture | | `usr-secondary`, `usr2` | `/usr/` file system partition of the secondary architecture of the local architecture (usually the matching 32-bit architecture for the local 64-bit architecture) | | `usr-secondary-verity`, `usr-vty2` | Verity data for the `/usr/` file system partition of the secondary architecture | | `usr-secondary-verity-sig`, `usr-vsig2` | Verity signature data for the `/usr/` file system partition of the secondary architecture | | `usr-{arch}` | `/usr/` file system partition of the given architecture | | `usr-{arch}-verity`, `usr-{arch}-vty` | Verity data for the `/usr/` file system partition of the given architecture | | `usr-{arch}-verity-sig`, `usr-{arch}-vsig` | Verity signature data for the `/usr/` file system partition of the given architecture | GPT partition type identifiers Architecture specific partition types can use one of these architecture identifiers: `alpha`, `arc`, `arm` (32-bit), `arm64` (64-bit, aka aarch64), `ia64`, `loongarch64`, `mips-le`, `mips64-le`, `parisc`, `ppc`, `ppc64`, `ppc64-le`, `riscv32`, `riscv64`, `s390`, `s390x`, `tilegx`, `x86` (32-bit, aka i386) and `x86-64` (64-bit, aka amd64). In partition type identifiers, `-vty` stands for `-verity`, `-vsig` stands for `-verity-sig`, and a `2` suffix stands for `-secondary`. For example, `usr-vsig2` is the same partition type as `usr-secondary-verity-sig`. The partition identifiers in `systemd.image-policy(7)` and `systemd.image-filter(7)` accept the same abbreviations. GPT limits partition labels to 36 characters. Use an abbreviated identifier in `Label=` to leave more room for a version string, for example `usr-x86-64-vsig_1.2.3`. The label that `systemd-repart(8)` derives from the partition type when `Label=` is not set uses the long spelling. `systemd-repart` always shows partition types with the long spelling. Most of the partition type UUIDs listed above are defined in the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). `Label=` The textual label to assign to the partition if none is assigned yet. Note that this setting is not used for matching. It is also not used when a label is already set for an existing partition. It is thus only used when a partition is newly created or when an existing one had no label set (that is: an empty label). If not specified, a label derived from the partition type is automatically used. Simple specifier expansion is supported, see below. `VolumeLabel=` The textual label to assign to the LUKS superblock if applicable. If not specified defaults to the same string as the partition label (see `Label=` above), however prefixed with `luks-`. This setting has no effect if encryption is not enabled for this partition. `UUID=` The UUID to assign to the partition if none is assigned yet. Note that this setting is not used for matching. It is also not used when a UUID is already set for an existing partition. It is thus only used when a partition is newly created or when an existing one had a all-zero UUID set. If set to `null`, the UUID is set to all zeroes. If not specified a UUID derived from the partition type is automatically used. `Priority=` A numeric priority to assign to this partition, in the range -2147483648…2147483647, with smaller values indicating higher priority, and higher values indicating smaller priority. This priority is used in case the configured size constraints on the defined partitions do not permit fitting all partitions onto the available disk space. If the partitions do not fit, the highest numeric partition priority of all defined partitions is determined, and all defined partitions with this priority are removed from the list of new partitions to create (which may be multiple, if the same priority is used for multiple partitions). The fitting algorithm is then tried again. If the partitions still do not fit, the now highest numeric partition priority is determined, and the matching partitions removed too, and so on. Partitions of a priority of 0 or lower are never removed. If all partitions with a priority above 0 are removed and the partitions still do not fit on the device the operation fails. Note that this priority has no effect on ordering partitions, for that use the alphabetical order of the filenames of the partition definition files. Defaults to 0. `Weight=` A numeric weight to assign to this partition in the range 0…1000000. Available disk space is assigned the defined partitions according to their relative weights (subject to the size constraints configured with `SizeMinBytes=`, `SizeMaxBytes=`), so that a partition with weight 2000 gets double the space as one with weight 1000, and a partition with weight 333 a third of that. Defaults to 1000. The `Weight=` setting is used to distribute available disk space in an "elastic" fashion, based on the disk size and existing partitions. If a partition shall have a fixed size use both `SizeMinBytes=` and `SizeMaxBytes=` with the same value in order to fixate the size to one value, in which case the weight has no effect. `PaddingWeight=` Similar to `Weight=`, but sets a weight for the free space after the partition (the "padding"). When distributing available space the weights of all partitions and all defined padding is summed, and then each partition and padding gets the fraction defined by its weight. Defaults to 0, i.e. by default no padding is applied. Padding is useful if empty space shall be left for later additions or a safety margin at the end of the device or between partitions. `SizeMinBytes=`; `SizeMaxBytes=` Specifies minimum and maximum size constraints in bytes. Takes the usual K, M, G, T, … suffixes (to the base of 1024). If `SizeMinBytes=` is specified the partition is created at or grown to at least the specified size. If `SizeMaxBytes=` is specified the partition is created at or grown to at most the specified size. The precise size is determined through the weight value configured with `Weight=`, see above. When `SizeMinBytes=` is set equal to `SizeMaxBytes=` the configured weight has no effect as the partition is explicitly sized to the specified fixed value. Note that partitions are never created smaller than 4096 bytes, and since partitions are never shrunk the previous size of the partition (in case the partition already exists) is also enforced as lower bound for the new size. The values should be specified as multiples of 4096 bytes, and are rounded upwards (in case of `SizeMinBytes=`) or downwards (in case of `SizeMaxBytes=`) otherwise. If the backing device does not provide enough space to fulfill the constraints placing the partition will fail. For partitions that shall be created, depending on the setting of `Priority=` (see above) the partition might be dropped and the placing algorithm restarted. By default, a minimum size constraint of 10M and no maximum size constraint is set. If `Format=` is set, the minimum size is automatically raised to the minimum file system size for the selected file system type, if known. Moreover, for the ESP/XBOOTLDR partitions the minimum is raised to 100M (for 512b sector images) or 260M (for 4K sector images) automatically, if specified smaller. `PaddingMinBytes=`; `PaddingMaxBytes=` Specifies minimum and maximum size constraints in bytes for the free space after the partition (the "padding"). Semantics are similar to `SizeMinBytes=` and `SizeMaxBytes=`, except that unlike partition sizes free space can be shrunk and can be as small as zero. By default, no size constraints on padding are set, so that only `PaddingWeight=` determines the size of the padding applied. `CopyBlocks=` Takes a path to a regular file, block device node, char device node or directory, or the special value `auto`. If specified and the partition is newly created, the data from the specified path is written to the newly created partition, on the block level. If a directory is specified, the backing block device of the file system the directory is on is determined, and the data read directly from that. This option is useful to efficiently replicate existing file systems onto new partitions on the block level — for example to build a simple OS installer or an OS image builder. Specify `/dev/urandom` as value to initialize a partition with random data. If the special value `auto` is specified, the source to copy from is automatically picked up from the running system (or the image specified with `--image=` — if used). A partition that matches both the configured partition type (as declared with `Type=` described above), and the currently mounted directory appropriate for that partition type is determined. For example, if the partition type is set to `root` the partition backing the root directory (`/`) is used as source to copy from — if its partition type is set to `root` as well. If the declared type is `usr` the partition backing `/usr/` is used as source to copy blocks from — if its partition type is set to `usr` too. The logic is capable of automatically tracking down the backing partitions for encrypted and Verity-enabled volumes. `CopyBlocks=auto` is useful for implementing "self-replicating" systems, i.e. systems that are their own installer. The file specified here must have a size that is a multiple of the basic block size 512 and not be empty. If this option is used, the size allocation algorithm is slightly altered: the partition is created at least as big as required to fit the data in, i.e. the data size is an additional minimum size value taken into consideration for the allocation algorithm, similar to and in addition to the `SizeMinBytes=` value configured above. This option has no effect if the partition it is declared for already exists, i.e. existing data is never overwritten. Note that the data is copied in before the partition table is updated, i.e. before the partition actually is persistently created. This provides robustness: it is guaranteed that the partition either does not exist or exists fully populated; it is not possible that the partition exists but is not or only partially populated. This option cannot be combined with `Format=` or `CopyFiles=`. `Format=` Takes a file system name, such as `ext4`, `btrfs`, `xfs`, `vfat`, `erofs`, `squashfs` or the special value `swap`. If specified and the partition is newly created it is formatted with the specified file system (or as swap device). The file system UUID and label are automatically derived from the partition UUID and label. If this option is used, the size allocation algorithm is slightly altered: the partition is created at least as big as required for the minimal file system of the specified type (or 4KiB if the minimal size is not known). This also takes a special meta value `empty`. If specified this is equivalent to specifying `Label=_empty` and `NoAuto=1`. This option has no effect if the partition already exists. Similarly to the behaviour of `CopyBlocks=`, the file system is formatted before the partition is created, ensuring that the partition only ever exists with a fully initialized file system. This option cannot be combined with `CopyBlocks=`. `CopyFiles=` Takes a colon-separated triplet in the form `source[:target[:options]]`. `source` is an absolute path which refers to a source file or directory on the host. `target` is an absolute path in the file system of the newly created partition and formatted file system. `options` is a comma-separated list of options where each option is in the form `key[=value]`. This setting may be used to copy files or directories from the host into the file system that is created due to the `Format=` option. If `CopyFiles=` is used without `Format=` specified explicitly, `Format=` with a suitable default is implied (currently `vfat` for `ESP` and `XBOOTLDR` partitions, and `ext4` otherwise, but this may change in the future). This option may be used multiple times to copy multiple files or directories from host into the newly formatted file system. The `target` path may be omitted in which case the `source` path is also used as the target path (relative to the root of the newly created file system). If the source path refers to a directory it is copied recursively. The `options` may contain the following values: `fsverity=` May be set to the value `off` (the default if the option is not present) or `copy`. If set to `off` then no files copied into the filesystem from this source will have fs-verity enabled. If set to `copy` then the fs-verity information for each file will be copied from the corresponding source file. This option has no effect if the partition already exists: it cannot be used to copy additional files into an existing partition, it may only be used to populate a file system created anew. The copy operation is executed before the file system is registered in the partition table, thus ensuring that a file system populated this way only ever exists fully initialized. Note that `CopyFiles=` will skip copying files that are not supported by the target filesystem (e.g symlinks, fifos, sockets and devices on vfat). When an unsupported file type is encountered, `systemd-repart` will skip copying this file and write a log message about it. Note that `systemd-repart` does not change the UIDs/GIDs of any copied files and directories. When running `systemd-repart` as an unprivileged user to build an image of files and directories owned by the same user, you can run `systemd-repart` in a user namespace with the current user mapped to the root user to make sure the files and directories in the image are owned by the root user. This option cannot be combined with `CopyBlocks=`. When `systemd-repart(8)` is invoked with the `--copy-source=` command line switch the file paths are taken relative to the specified directory. If `--copy-source=` is not used, but the `--image=` or `--root=` switches are used, the source paths are taken relative to the specified root directory or disk image root. Note that when `CopyFiles=` is used with `Format=xfs`, `xfsprogs` 6.17 or newer is required. Note that `systemd-repart` always excludes the contents of a number of API file systems and temporary directories, namely `/proc/`, `/sys/`, `/dev/`, `/tmp/`, `/run/`, and `/var/tmp/`, as their contents are not expected to be part of a disk image. The directories themselves are still created (empty) in the new file system. When a root partition is populated, the contents below the mount points of any other partitions that are part of the same image are excluded too, so that data belonging to a separate partition is not duplicated into the root file system. For example, if an `esp` partition is part of the image, the contents of `/boot/` and `/efi/` are not copied into the root partition. To copy a directory that is excluded by the mount-point rule above, add an explicit `CopyFiles=` entry for it. For example, `CopyFiles=/boot:/boot` overrides the implicit exclusion and copies `/boot/` into the root partition. `ExcludeFiles=`; `ExcludeFilesTarget=` Takes one or more absolute paths, separated by whitespace, each referring to a source file or directory on the host. This setting may be used to exclude files or directories from the host from being copied into the file system when `CopyFiles=` is used. This option may be used multiple times to exclude multiple files or directories from host from being copied into the newly formatted file system. If the path is a directory and ends with `/`, only the directory's contents are excluded but not the directory itself. If the path is a directory and does not end with `/`, both the directory and its contents are excluded. `ExcludeFilesTarget=` is like `ExcludeFiles=` except that instead of excluding the path on the host from being copied into the partition, it excludes any files and directories from being copied into the given path in the partition. When `systemd-repart(8)` is invoked with the `--image=` or `--root=` command line switches the paths specified are taken relative to the specified root directory or disk image root. `MakeDirectories=` Takes one or more absolute paths, separated by whitespace, each declaring a directory to create within the new file system. Behaviour is similar to `CopyFiles=`, but instead of copying in a set of files this just creates the specified directories with the default mode of 0755 owned by the root user and group, plus all their parent directories (with the same ownership and access mode). To configure directories with different ownership or access mode, use `CopyFiles=` and specify a source tree to copy containing appropriately owned/configured directories. This option may be used more than once to create multiple directories. When `CopyFiles=` and `MakeDirectories=` are used together the former is applied first. If a directory listed already exists no operation is executed (in particular, the ownership/access mode of the directories is left as is). The primary use case for this option is to create a minimal set of directories that may be mounted over by other partitions contained in the same disk image. For example, a disk image where the root file system is formatted at first boot might want to automatically pre-create `/usr/` in it this way, so that the `usr` partition may over-mount it. Consider using `systemd-tmpfiles(8)` with its `--image=` option to pre-create other, more complex directory hierarchies (as well as other inodes) with fine-grained control of ownership, access modes and other file attributes. `MakeSymlinks=` Takes one or more arguments, separated by whitespace, each declaring a symlink to create within the new file system. Each argument is a pair of symlink source and target paths, separated by a colon. This option may be used more than once to create multiple symlinks. When `CopyFiles=` and `MakeSymlinks=` are used together the former is applied first. The primary use case for this option is to create symlinks that need to exist before `systemd-tmpfiles(8)` is executed. For example, when using `systemd-confext(8)`, this setting can be used to create symlinks in `/var/lib/extensions.mutable` to redirect writes to mutable confexts to a custom location. Consider using `systemd-tmpfiles(8)` with its `--image=` option to pre-create other symlinks (as well as other inodes) with fine-grained control of ownership, access modes and other file attributes. `Subvolumes=` Takes one or more absolute paths, separated by whitespace, each declaring a directory that should be a subvolume within the new file system. Each path may optionally be followed by a colon and a list of comma-separated subvolume flags. The following flags are understood: | Flag | Purpose | |-------------|--------------------------------------| | `ro` | Make this subvolume read-only. | | `nodatacow` | Disable data CoW for this subvolume. | Subvolume Flags {.flags} Note that this option does not create the directories themselves, that can be configured with `MakeDirectories=` and `CopyFiles=`. Note that this option only takes effect if the target filesystem supports subvolumes, such as `btrfs(8)`. Note that this option is only supported in combination with `--offline=yes` since `btrfs-progs` 6.12 or newer. `DefaultSubvolume=` Takes an absolute path specifying the default subvolume within the new filesystem. Note that this setting does not create the subvolume itself, that can be configured with `Subvolumes=`. Note that this option only takes effect if the target filesystem supports subvolumes, such as `btrfs(8)`. Note that this option is only supported in combination with `--offline=yes` since `btrfs-progs` 6.12 or newer. `BlockDeviceReplace=` Takes a path to a mountpoint. Its filesystem's backing device will be replaced with the newly created partition. This works only for btrfs filesystems. This option is ignored for already existing partitions. If after moving the filesystem, an error happens before the writing of the partition table is finished, there will be an attempt to move the filesystem back to its original device. But if that attempt also fails, the filesystem might be living on a partition that does not exist in the partition table and will be lost on reboot. This feature is intended to save initially volatile mounted filesystems into the new disk with no important data, like a live boot system. They might need to be recreated after a failure writing the partition table. This option is not compatible with `--offline=yes`. `VolumeName=` If an encrypted partition is created through `Encrypt=`, and it will stay activated after `systemd-repart` is done (using `BlockDeviceReplace=`), then the name of the device mapper volume created will use the name specified by `VolumeName=`. The value must be a valid filename. If not specified, it will default to the value of `VolumeLabel=` (which could be derived from `Label=`) if valid. `Encrypt=` Takes one of `off`, `key-file`, `tpm2` and `key-file+tpm2` (alternatively, also accepts a boolean value, which is mapped to `off` when false, and `key-file` when true). Defaults to `off`. If not `off` the partition will be formatted with a LUKS2 superblock, before the blocks configured with `CopyBlocks=` are copied in or the file system configured with `Format=` is created. The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. If `key-file` or `key-file+tpm2` is used, a key is added to the LUKS2 superblock, configurable with the `--key-file=` option to `systemd-repart`. If `tpm2` or `key-file+tpm2` is used, a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured with the `--tpm2-device=` and `--tpm2-pcrs=` options to `systemd-repart`. When used this slightly alters the size allocation logic as the implicit, minimal size limits of `Format=` and `CopyBlocks=` are increased by the space necessary for the LUKS2 superblock (see above). This option has no effect if the partition already exists. This option may be combined with `Verity=data` in order to place the encrypted partition inside a dm-verity protection envelope, see the description of `Verity=` below. `Discard=` Takes a boolean argument. The default is `no` if `--discard=no` is used for the invocation of `systemd-repart` or if `Integrity=inline` is set. It is `yes` otherwise. If set to `yes`, when creating the LUKS2 superblock for the partition, the `allow-discards` activation flag will be set so that future activations will allow discards by default. This option has no effect if the partition already exists or if `Encrypt=off` is used. `EncryptKDF=` Specifies the key derivation function (KDF) to use for LUKS2 encryption keyslots. Takes one of `argon2id`, `pbkdf2`, or `minimal`. If not specified, the default is determined by the cryptsetup library (typically `argon2id`). This option has no effect if `Encrypt=` is `off`. When set to `argon2id` or `pbkdf2`, the specified KDF is used with parameters benchmarked by the cryptsetup library. When set to `minimal`, PBKDF2 is used with SHA-512, 1000 iterations, and no benchmarking — this is appropriate for high-entropy keys (e.g. generated by a hardware key manager or sealed to a TPM) where the KDF only needs to satisfy the LUKS2 format requirement, not strengthen a weak passphrase. Note that Argon2-based KDFs may require significant memory (up to 1GB) during key derivation. In memory-constrained environments such as kdump with limited crashkernel memory, `minimal` or `pbkdf2` may be more appropriate. When `Encrypt=` includes `tpm2`, the TPM2 keyslot always uses a minimal PBKDF2 configuration regardless of this setting. `EncryptAddToken=` Registers a custom LUKS2 token in the partition's LUKS2 header at provisioning time. This option may be specified more than once to register multiple tokens. Each invocation adds one token entry. Assigning the empty string clears all previously assigned tokens. The syntax is: EncryptAddToken=type[:source:value] The \ field is mandatory and specifies the LUKS2 token type name (e.g. `tdx-kbs`). It must be a valid filename component (no `/`, no `.` or `..`) and corresponds to the name of the token handler plugin installed as `libcryptsetup-token-type.so`. The optional \ and \ fields supply token-plugin-specific metadata as a JSON object. Two sources are supported: `file` The \ is a path to a file containing a JSON object with the extra token metadata. Example: EncryptAddToken=tdx-kbs:file:/etc/repart/tdx-kbs-token.json `data` The \ is a Base64-encoded JSON object with the extra token metadata, suitable for embedding directly in the configuration file. Example: EncryptAddToken=tdx-kbs:data:eyJ0cnVzdGVlLmticy51cmwiOiJodHRwOi8va2JzLXNlcnZpY2U6ODA4MCJ9 The extra metadata object must not contain `type` or `keyslots` fields — these are always set by `systemd-repart`: `type` is taken from the \ argument, and `keyslots` is set to the keyslot number created for this partition. This option is supported with all `Encrypt=` modes except `off`. When used with `key-file+tpm2`, the token is bound to the key-file keyslot. When used with `tpm2`, the token is bound to the TPM2 keyslot. This option has no effect if the partition already exists. `Verity=` Takes one of `off`, `data`, `hash` or `signature`. Defaults to `off`. If set to `off` or `data`, the partition is populated with content as specified by `CopyBlocks=` or `CopyFiles=`. If set to `hash`, the partition will be populated with verity hashes from the matching verity data partition. If set to `signature`, the partition will be populated with a JSON object containing a signature of the verity root hash of the matching verity hash partition. A matching verity partition is a partition with the same verity match key (as configured with `VerityMatchKey=`). If not explicitly configured, the data partition's UUID will be set to the first 128 bits of the verity root hash. Similarly, if not configured, the hash partition's UUID will be set to the final 128 bits of the verity root hash. The verity root hash itself will be included in the output of `systemd-repart`. This option has no effect if the partition already exists. `data` may be combined with `Encrypt=`, in which case the partition is first encrypted with LUKS2 and the verity hash data is then generated from the resulting ciphertext, i.e. Verity is the outer protection envelope and LUKS2 the inner. Tools such as `systemd-dissect(1)` will then set up the dm-verity device first, and open the LUKS2 volume on top of it, so that all encrypted data read is also authenticated via the verity root hash. Note that in this case the verity hashes necessarily cover freshly generated ciphertext, hence the root hash (and thus the default partition UUIDs derived from it) will change on every build, even if the plaintext contents are fully reproducible. `Encrypt=` may not be combined with `Verity=hash` or `Verity=signature`. Since the ciphertext is only generated while the final image is built, `Minimize=` cannot be used for the hash partition of an encrypted data partition; use `SizeMaxBytes=` on the data partition to size the hash partition instead. For each unique `VerityMatchKey=` value, a single verity data partition (`Verity=data`) and a single verity hash partition (`Verity=hash`) must be defined. `VerityMatchKey=` Takes a short, user-chosen identifier string. This setting is used to find sibling verity partitions for the current verity partition. See the description for `Verity=`. `VerityDataBlockSizeBytes=` Configures the data block size of the generated verity hash partition. Must be between 512 and 4096 bytes and must be a power of 2. Defaults to the sector size if configured explicitly, or the underlying block device sector size, or 4K if `systemd-repart` is not operating on a block device. `VerityHashBlockSizeBytes=` Configures the hash block size of the generated verity hash partition. Must be between 512 and 4096 bytes and must be a power of 2. Defaults to the sector size if configured explicitly, or the underlying block device sector size, or 4K if `systemd-repart` is not operating on a block device. `FactoryReset=` Takes a boolean argument. If specified the partition is marked for removal during a factory reset operation. This functionality is useful to implement schemes where images can be reset into their original state by removing partitions and creating them anew. Defaults to off. `Flags=` Configures the 64-bit GPT partition flags field to set for the partition when creating it. This option has no effect if the partition already exists. If not specified, the flags value is set to all zeroes, except for the three bits that can also be configured via `NoAuto=`, `ReadOnly=` and `GrowFileSystem=`; see below for details on the defaults for these three flags. Specify the flags value in hexadecimal (by prefixing it with `0x`), binary (prefix `0b`) or decimal (no prefix). `NoAuto=`; `ReadOnly=`; `GrowFileSystem=` Configures the No-Auto, Read-Only and Grow-File-System partition flags (bit 63, 60 and 59) of the partition table entry, as defined by the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). Only available for partition types supported by the specification. This option is a friendly way to set bits 63, 60 and 59 of the partition flags value without setting any of the other bits, and may be set via `Flags=` too, see above. If `Flags=` is used in conjunction with one or more of `NoAuto=`/`ReadOnly=`/`GrowFileSystem=` the latter control the value of the relevant flags, i.e. the high-level settings `NoAuto=`/`ReadOnly=`/`GrowFileSystem=` override the relevant bits of the low-level setting `Flags=`. Note that the three flags affect only automatic partition mounting, as implemented by `systemd-gpt-auto-generator(8)` or the `--image=` option of various commands (such as `systemd-nspawn(1)`). It has no effect on explicit mounts, such as those done via `mount(8)` or `fstab(5)`. If both bit 60 and 59 are set for a partition (i.e. the partition is marked both read-only and marked for file system growing) the latter is typically without effect: the read-only flag takes precedence in most tools reading these flags, and since growing the file system involves writing to the partition it is consequently ignored. `NoAuto=` defaults to off. `ReadOnly=` defaults to on for Verity partition types, and off for all others. `GrowFileSystem=` defaults to on for all partition types that support it, except if the partition is marked read-only (and thus effectively, defaults to off for Verity partitions). `SplitName=` Configures the suffix to append to split artifacts when the `--split` option of `systemd-repart(8)` is used. Simple specifier expansion is supported, see below. Defaults to `%t`. To disable split artifact generation for a partition, set `SplitName=` to `-`. `Minimize=` Takes one of `off`, `best`, and `guess` (alternatively, also accepts a boolean value, which is mapped to `off` when false, and `best` when true). Defaults to `off`. If set to `best`, the partition will have the minimal size required to store the sources configured with `CopyFiles=`. `best` is currently only supported for read-only filesystems and btrfs. If set to `guess`, the partition is created at least as big as required to store the sources configured with `CopyFiles=`. Note that unless the filesystem is a read-only filesystem or btrfs, `systemd-repart` will have to populate the filesystem twice to guess the minimal required size, so enabling this option might slow down repart when populating large partitions. `MountPoint=` Specifies where and how the partition should be mounted. Takes at least one and at most two fields separated with a colon (`:`). The first field specifies where the partition should be mounted. The second field specifies extra mount options to append to the default mount options. These fields correspond to the second and fourth column of the `fstab(5)` format. As a colon is used for separating fields, each field needs to be quoted when it contains colons. E.g. MountPoint="/path/with:colon":"zstd:1,noatime,lazytime" This setting may be specified multiple times to mount the partition multiple times. This can be used to add mounts for different `btrfs(8)` subvolumes located on the same btrfs partition. Note that this setting is only taken into account when `--generate-fstab=` is specified on the `systemd-repart` command line. `EncryptedVolume=` Specifies how the encrypted partition should be set up. Takes at least one and at most four fields separated with a colon (`:`). The first field specifies the encrypted volume name under `/dev/mapper/`. If not specified, `luks-UUID` will be used where `UUID` is the LUKS UUID. The second field specifies the keyfile to use following the same format as specified in crypttab. The third field specifies a comma-delimited list of crypttab options. These three fields correspond to the first, third and fourth column of the `crypttab(5)` format. The fourth field contains extra options, which are not directly reflected to crypttab options. Currently, the only supported extra option is `fixate-volume-key`. When specified, the volume key hash will be taken upon LUKS volume formatting and the result will be added to the list of crypttab options, i.e. `fixate-volume-key=expected-hash` will be added to the fourth column of the generated crypttab. Note that this setting is only taken into account when `--generate-crypttab=` is specified on the `systemd-repart` command line. As the crypttab with the expected hashes can only be generated after LUKS volumes are formatted, the crypttab itself cannot be put to the generated volume. `TPM2PCRs=` Configures the list of PCRs to use for LUKS2 volumes configured with the `Encrypt=tpm2` setting in partition files. This option take the same parameters as the similarly named options to `systemd-cryptenroll(1)` and have the same effect on partitions where TPM2 enrollment is requested. This option will be overridden by the global `--tpm2-pcrs=` option. `KeyFile=` Takes a file system path. This path must be absolute, otherwise the option is ignored. Configures the encryption key to use when setting up LUKS2 volumes configured with the `Encrypt=key-file` setting in partition files. Please refer to the documentation of `--key-file=` for more details. This option will be overridden by the global `--key-file=` option. `Integrity=` Enable integrity checking for the partition. Currently, the only supported option is `Integrity=inline` which enables authenticated disk encryption for LUKS2 devices. The option requires `Encrypt=` setting and can only be used in online image build. Defaults to `off`, i.e. integrity protection is disabled. Note: authenticated disk encryption is considered EXPERIMENTAL by cryptsetup. `IntegrityAlgorithm=` Specify the integrity algorithm to be used for integrity verification. For `Integrity=inline` the supported values are: `hmac-sha1`, `hmac-sha256`(default), and `hmac-sha512`. `Compression=` Specifies the compression algorithm to use for the filesystem configured with `Format=`. Takes a single argument specifying the compression algorithm. Note that this setting is only taken into account when the filesystem configured with `Format=` supports compression ( `btrfs(8)`, squashfs, `erofs(5)`). Here's an incomplete list of compression algorithms supported by the filesystems known to `systemd-repart`: | File System | Compression Algorithms | Documentation | |-------------|---------------------------------------------|-----------------| | `squashfs` | gzip, lzo, lz4, xz, zstd, lzma | `mksquashfs(1)` | | `erofs` | lz4, lz4hc, lzma, deflate, libdeflate, zstd | `mkfs.erofs(1)` | | `btrfs` | zlib, lzo, zstd | `mkfs.btrfs(8)` | File System Compression Algorithms `CompressionLevel=` Specifies the compression level to use for the filesystem configured with `Format=`. Takes a single argument specifying the compression level to use for the configured compression algorithm. The possible compression levels and their meaning are filesystem specific (refer to the filesystem's documentation for the exact meaning of a particular compression level). Note that this setting is only taken into account when the filesystem configured with `Format=` supports compression and the `Compression=` setting is configured explicitly. `SupplementFor=` Takes a partition definition name, such as `10-esp`. If specified, `systemd-repart` will avoid creating this partition and instead prefer to partially merge the two definitions. However, depending on the existing layout of partitions on disk, `systemd-repart` may be forced to fall back onto un-merging the definitions and using them as originally written, potentially creating this partition. Specifically, `systemd-repart` will fall back if this partition is found to already exist on disk, or if the target partition already exists on disk but is too small, or if it cannot allocate space for the merged partition for some other reason. The following fields are merged into the target definition in the specified ways: `Weight=` and `PaddingWeight=` are simply overwritten; `SizeMinBytes=` and `PaddingMinBytes=` use the larger of the two values; `SizeMaxBytes=` and `PaddingMaxBytes=` use the smaller value; and `CopyFiles=`, `ExcludeFiles=`, `ExcludeFilesTarget=`, `MakeDirectories=`, and `Subvolumes=` are concatenated. Usage of this option in combination with `CopyBlocks=`, `Encrypt=`, or `Verity=` is not supported. The target definition cannot set these settings either. A definition cannot simultaneously be a supplement and act as a target for some other supplement definition. A target cannot have more than one supplement partition associated with it. For example, distributions can use this to implement `$BOOT` as defined in the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/). Distributions may prefer to use the ESP as `$BOOT` whenever possible, but to adhere to the spec XBOOTLDR must sometimes be used instead. So, they should create two definitions: the first defining an ESP big enough to hold just the bootloader, and a second for the XBOOTLDR that's sufficiently large to hold kernels and configured as a supplement for the ESP. Whenever possible, `systemd-repart(8)` will try to merge the two definitions to create one large ESP, but if that's not allowable due to the existing conditions on disk a small ESP and a large XBOOTLDR will be created instead. As another example, distributions can also use this to seamlessly share a single `/home` partition in a multi-boot scenario, while preferring to keep `/home` on the root partition by default. Having a `/home` partition separated from the root partition entails some extra complexity: someone has to decide how to split the space between the two partitions. On the other hand, it allows a user to share their home area between multiple installed OSs (i.e. via `systemd-homed.service(8)`). Distributions should create two definitions: the first for a root partition that takes up some relatively small percentage of the disk, and the second as a supplement for the first to create a `/home` partition that takes up all the remaining free space. On first boot, if `systemd-repart` finds an existing `/home` partition on disk, it'll un-merge the definitions and create just a small root partition. Otherwise, the definitions will be merged and a single large root partition will be created. `AddValidateFS=` Takes a boolean argument. If enabled will set the `user.validatefs.gpt_label`, `user.validatefs.gpt_type_uuid` and `user.validatefs.mount_point` extended attributes on the root inode of the formatted file system to the partition labels, partition type UUIDs and the intended mount point for the file system. Defaults to on if `Format=` is used and the specified argument is neither `swap` nor `vfat`. These extended attributes are read by `systemd-validatefs@.service(8)` and may encode constraints on mounted file systems that must be fulfilled for the system to successfully boot. This is particular important in `systemd-gpt-auto-generator(8)` scenarios, which puts together the mount hierarchy from untrusted data from the GPT partition table. As these extended attributes are stored inside the file system, they are typically authenticated as part of the file system (assuming it is contained in protected volume; i.e. LUKS or dm-verity), and hence may be used to securely validate the matching partition table fields. The same constraints are also enforced when the partitions are mounted as part of a disk image, for example via `systemd-dissect(1)` or `systemd-nspawn(1)`. Note that this means that a file system generated with this option enabled cannot be used as bare file system image without partition table anymore, since its GPT constraints cannot be fulfilled then. `FileSystemSectorSize=` Controls the sector size for any file system, LUKS volume or Verity volume formatted on this partition. Expects a power of 2 as value, and must be equal or larger than 512. Typically it's recommended to set the file system sector size to 4096, even on 512 sector disks (and in particular for images that are only ever intended to be stored as file on disks), in order to optimize performance. However, for compatibility with foreign operating systems or firmware it might be advisable to use the native sector size of the backing disk. If unspecified and operating on a block device, defaults to the native sector size of the device. If unspecified and operating on a disk image file defaults to 4096. Regardless of what is configured here, or which default is picked, the file system sector size is always increased to be equal or larger than the disk sector size. # Specifiers Specifiers may be used in the `Label=`, `CopyBlocks=`, `CopyFiles=`, `MakeDirectories=`, `MakeSymlinks=`, `SplitName=` settings. The following expansions are understood: | Specifier | Meaning | Details | |-----------|---------|---------| Specifiers available {.specifiers} Additionally, for the `SplitName=` setting, the following specifiers are also understood: | Specifier | Meaning | Details | |----|----|----| | `%T` | Partition Type UUID | The partition type UUID, as configured with `Type=` | | `%t` | Partition Type Identifier | The partition type identifier corresponding to the partition type UUID | | `%U` | Partition UUID | The partition UUID, as configured with `UUID=` | | `%n` | Partition Number | The partition number assigned to the partition | Specifiers available {.specifiers} # Environment Extra filesystem formatting options can be provided using filesystem-specific environment variables: `$SYSTEMD_REPART_MKFS_OPTIONS_BTRFS`, `$SYSTEMD_REPART_MKFS_OPTIONS_XFS`, `$SYSTEMD_REPART_MKFS_OPTIONS_VFAT`, `$SYSTEMD_REPART_MKFS_OPTIONS_EROFS`, and `$SYSTEMD_REPART_MKFS_OPTIONS_SQUASHFS`. Each variable accepts valid `mkfs.filesystem` command-line arguments. The content of those variables is passed as-is to the command, without any verification. # Examples
Grow the root partition to the full disk size at first boot
With the following file the root partition is automatically grown to the full disk if possible during boot. # /usr/lib/repart.d/50-root.conf [Partition] Type=root
Create a swap and home partition automatically on boot, if missing
The home partition gets all available disk space while the swap partition gets 1G at most and 64M at least. We set a priority \> 0 on the swap partition to ensure the swap partition is not used if not enough space is available. For every three bytes assigned to the home partition the swap partition gets assigned one. # /usr/lib/repart.d/60-home.conf [Partition] Type=home # /usr/lib/repart.d/70-swap.conf [Partition] Type=swap SizeMinBytes=64M SizeMaxBytes=1G Priority=1 Weight=333
Create B partitions in an A/B Verity setup, if missing
Let's say the vendor intends to update OS images in an A/B setup, i.e. with two root partitions (and two matching Verity partitions) that shall be used alternatingly during upgrades. To minimize image sizes the original image is shipped only with one root and one Verity partition (the "A" set), and the second root and Verity partitions (the "B" set) shall be created on first boot on the free space on the medium. # /usr/lib/repart.d/50-root.conf [Partition] Type=root SizeMinBytes=512M SizeMaxBytes=512M # /usr/lib/repart.d/60-root-verity.conf [Partition] Type=root-verity SizeMinBytes=64M SizeMaxBytes=64M The definitions above cover the "A" set of root partition (of a fixed 512M size) and Verity partition for the root partition (of a fixed 64M size). Let's use symlinks to create the "B" set of partitions, since after all they shall have the same properties and sizes as the "A" set. # ln -s 50-root.conf /usr/lib/repart.d/70-root-b.conf # ln -s 60-root-verity.conf /usr/lib/repart.d/80-root-verity-b.conf
Create a data partition and corresponding verity partitions from a OS tree
Assuming we have an OS tree at `/var/tmp/os-tree` that we want to package in a root partition together with matching verity partitions, we can do so as follows: # 50-root.conf [Partition] Type=root CopyFiles=/var/tmp/os-tree Verity=data VerityMatchKey=root Minimize=guess # 60-root-verity.conf [Partition] Type=root-verity Verity=hash VerityMatchKey=root # Explicitly set the hash and data block size to 4K VerityDataBlockSizeBytes=4096 VerityHashBlockSizeBytes=4096 Minimize=best # 70-root-verity-sig.conf [Partition] Type=root-verity-sig Verity=signature VerityMatchKey=root
# See Also `systemd(1)`, `systemd-repart(8)`, `sfdisk(8)`, `systemd-cryptenroll(1)` # report-geoip.conf systemd report-geoip.conf 5 report-geoip.conf report-geoip.conf.d GeoIP report metrics configuration file `/etc/systemd/report-geoip.conf`, `/run/systemd/report-geoip.conf`, `/usr/local/lib/systemd/report-geoip.conf`, `/usr/lib/systemd/report-geoip.conf`, `/etc/systemd/report-geoip.conf.d/*.conf`, `/run/systemd/report-geoip.conf.d/*.conf`, `/usr/local/lib/systemd/report-geoip.conf.d/*.conf`, `/usr/lib/systemd/report-geoip.conf.d/*.conf` # Description This file configures the behavior of `systemd-report-geoip@.service(8)`, a metrics source for `systemd-report(1)` reporting the approximate geographic location of the system. # Options All options are configured in the \[GeoIP\] section: `Endpoint=` The HTTP or HTTPS URL of the geolocation web service to query. The service must answer a GET request with a JSON object in the format of the [reallyfreegeoip.org](https://reallyfreegeoip.org/) service, describing the location of the address the request originates from. The field names used by [ipinfo.io](https://ipinfo.io/) (i.e. `country`, `region`, `continent` in place of `country_name`, `region_name`, `continent_name`) are understood too. Fields the service does not provide are not reported. If assigned the empty string, the default is restored. The default is chosen at compile time. `RefreshSec=` Controls how often the geolocation data is refreshed from the endpoint, at most. Takes a time span, see `systemd.time(7)` for details. The acquired data is cached locally, and the endpoint is only contacted again once the cached data is older than the specified time. If set to zero, the endpoint is contacted on every request. If set to `infinity`, the endpoint is contacted only once, and the cached data is used from then on. Defaults to `30min`. Use systemd-analyze cat-config systemd/report-geoip.conf to display the full config. # See Also `systemd-report-geoip@.service(8)`, `systemd-report(1)` # resolvectl systemd resolvectl 1 resolvectl resolvconf Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services; introspect and reconfigure the DNS resolver resolvectl OPTIONS COMMAND NAME # Description `resolvectl` may be used to resolve domain names, IPv4 and IPv6 addresses, DNS resource records and services with the `systemd-resolved.service(8)` resolver service. By default, the specified list of parameters will be resolved as hostnames, retrieving their IPv4 and IPv6 addresses. If the parameters specified are formatted as IPv4 or IPv6 addresses the reverse operation is done, and a hostname is retrieved for the specified addresses. The program's output contains information about the protocol used for the look-up and on which network interface the data was discovered. It also contains information on whether the information could be authenticated. All data for which local DNSSEC validation succeeds is considered authenticated. Moreover, all data originating from local, trusted sources is also reported authenticated, including resolution of the local host name, the `localhost` hostname or all data from `/etc/hosts`. # Commands `query` \… Resolve domain names, as well as IPv4 and IPv6 addresses. When used in conjunction with `--type=` or `--class=` (see below), resolves low-level DNS resource records. If a single-label domain name is specified it is searched for according to the configured search domains — unless `--search=no` or `--type=`/`--class=` are specified, both of which turn this logic off. If an international domain name is specified, it is automatically translated according to IDNA rules when resolved via classic DNS — but not for look-ups via MulticastDNS or LLMNR. If `--type=`/`--class=` is used IDNA translation is turned off and domain names are processed as specified. If combined with `--json=` (only supported in combination with `--type=`) will output the resource record data in a JSON object. If `systemd-resolved` returns a resolution error while `--json=` is enabled, the error is output as a JSON object. It contains the queried `name`, the resolved varlink `error`, and any error fields supplied by `systemd-resolved`, such as `rcode`, `queryString`, `extendedDNSErrorCode`, `extendedDNSErrorMessage`, and `result`. Local invocation or connection errors are still reported as regular errors. `service` \[\[\\] \\] \ Resolve [RFC 6763 DNS-SD](https://tools.ietf.org/html/rfc6763) and [RFC 2782 SRV](https://tools.ietf.org/html/rfc2782) services, depending on the specified list of parameters. If three parameters are passed the first is assumed to be the DNS-SD service name, the second the `SRV` service type, and the third the domain to search in. In this case, a full DNS-SD style `SRV` and `TXT` lookup is executed. If only two parameters are specified, the first is assumed to be the `SRV` service type, and the second the domain to look in. In this case, no `TXT` resource record is requested. Finally, if only one parameter is specified, it is assumed to be a domain name, that is already prefixed with an `SRV` type, and an `SRV` lookup is done (no `TXT`). `openpgp` \… Query PGP keys stored as `OPENPGPKEY` resource records, see [RFC 7929](https://tools.ietf.org/html/rfc7929). Specified e-mail addresses are converted to the corresponding DNS domain name, and any `OPENPGPKEY` keys are printed. The resource record type is implied by this command. If `--type=` is specified, it must be `OPENPGPKEY`. If combined with `--json=`, outputs the resource record data in JSON format. Unauthenticated key data is refused in JSON format. `tlsa` \[\\] \\[:\\]… Query TLS public keys stored as `TLSA` resource records, see [RFC 6698](https://tools.ietf.org/html/rfc6698). A query will be performed for each of the specified names prefixed with the port and family (`_port._family.domain`). The port number may be specified after a colon (`:`), otherwise `443` will be used by default. The family may be specified as the first argument, otherwise `tcp` will be used. The resource record type is implied by this command. If `--type=` is specified, it must be `TLSA`. If combined with `--json=`, outputs the resource record data in JSON format. Unauthenticated key data is refused in JSON format. `status` \[\…\] Shows the global and per-link DNS settings currently in effect. If no command is specified, this is the implied default. `statistics` Shows general resolver statistics, including information whether DNSSEC is enabled and available, as well as resolution and validation statistics. `reset-statistics` Resets the statistics counters shown in `statistics` to zero. This operation requires root privileges. `flush-caches` Flushes all DNS resource record caches the service maintains locally. This is mostly equivalent to sending the `SIGUSR2` to the `systemd-resolved` service. `reset-server-features` Flushes all feature level information the resolver learnt about specific servers, and ensures that the server feature probing logic is started from the beginning with the next look-up request. This is mostly equivalent to sending the `SIGRTMIN+1` to the `systemd-resolved` service. `dns` \[\ \[\…\]\]; `domain` \[\ \[\…\]\]; `default-route` \[\ \[\…\]\]; `llmnr` \[\ \[\\]\]; `mdns` \[\ \[\\]\]; `dnssec` \[\ \[\\]\]; `dnsovertls` \[\ \[\\]\]; `nta` \[\ \[\…\]\] Get/set per-interface DNS configuration. These commands may be used to configure various DNS settings for network interfaces. These commands may be used to inform `systemd-resolved` or `systemd-networkd` about per-interface DNS configuration determined through external means. The `dns` command expects IPv4 or IPv6 address specifications of DNS servers to use. Each address can optionally take a port number separated with `:`, a network interface name or index separated with `%`, and a Server Name Indication (SNI) separated with `#`. When IPv6 address is specified with a port number, then the address must be in the square brackets. That is, the acceptable full formats are `111.222.333.444:9953%ifname#example.com` for IPv4 and `[1111:2222::3333]:9953%ifname#example.com` for IPv6. The `domain` command expects valid DNS domains, possibly prefixed with `~`, and configures a per-interface search or route-only domain. The `default-route` command expects a boolean parameter, and configures whether the link may be used as default route for DNS lookups, i.e. if it is suitable for lookups on domains no other link explicitly is configured for. The `llmnr`, `mdns`, `dnssec` and `dnsovertls` commands may be used to configure the per-interface LLMNR, MulticastDNS, DNSSEC and DNSOverTLS settings. Finally, `nta` command may be used to configure additional per-interface DNSSEC NTA domains. Commands `dns`, `domain` and `nta` can take a single empty string argument to clear their respective value lists. For details about these settings, their possible values and their effect, see the corresponding settings in `systemd.network(5)`. `revert LINK` Revert the per-interface DNS configuration. If the DNS configuration is reverted all per-interface DNS setting are reset to their defaults, undoing all effects of `dns`, `domain`, `default-route`, `llmnr`, `mdns`, `dnssec`, `dnsovertls`, `nta`. Note that when a network interface disappears all configuration is lost automatically, an explicit reverting is not necessary in that case. `monitor` Show a continuous stream of local client resolution queries and their responses. Whenever a local query is completed the query's DNS resource lookup key and resource records are shown. Note that this displays queries issued locally only, and does not immediately relate to DNS requests submitted to configured DNS servers or the LLMNR or MulticastDNS zones, as lookups may be answered from the local cache, or might result in multiple DNS transactions (for example to validate DNSSEC information). If CNAME/CNAME redirection chains are followed, a separate query will be displayed for each element of the chain. Use `--json=` to enable JSON output. `show-cache` Show current cache content, per scope. Use `--json=` to enable JSON output. `show-server-state` Show detailed server state information, per DNS Server. Use `--json=` to enable JSON output. # Options `-4`; `-6` By default, when resolving a hostname, both IPv4 and IPv6 addresses are acquired. By specifying `-4` only IPv4 addresses are requested, by specifying `-6` only IPv6 addresses are requested. `-i` \; `--interface=INTERFACE` Specifies the network interface to execute the query on. This may either be specified as numeric interface index or as network interface string (e.g. `en0`). Note that this option has no effect if system-wide DNS configuration (as configured in `/etc/resolv.conf` or `/etc/systemd/resolved.conf`) in place of per-link configuration is used. `-p` \; `--protocol=PROTOCOL` Specifies the network protocol for the query. May be one of `dns` (i.e. classic unicast DNS), `llmnr` ([Link-Local Multicast Name Resolution](https://tools.ietf.org/html/rfc4795)), `llmnr-ipv4`, `llmnr-ipv6` (LLMNR via the indicated underlying IP protocols), `mdns` ([Multicast DNS](https://www.ietf.org/rfc/rfc6762.txt)), `mdns-ipv4`, `mdns-ipv6` (MDNS via the indicated underlying IP protocols). By default, the lookup is done via all protocols suitable for the lookup. If used, limits the set of protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the same time. The setting `llmnr` is identical to specifying this switch once with `llmnr-ipv4` and once via `llmnr-ipv6`. Note that this option does not force the service to resolve the operation with the specified protocol, as that might require a suitable network interface and configuration. The special value `help` may be used to list known values. `-t` \; `--type=TYPE`; `-c` \; `--class=CLASS` When used in conjunction with the `query` command, specifies the DNS resource record type (e.g. `A`, `AAAA`, `MX`, …) and class (e.g. `IN`, `ANY`, …) to look up. If these options are used a DNS resource record set matching the specified class and type is requested. The class defaults to `IN` if only a type is specified. The special value `help` may be used to list known values. Without these options `resolvectl query` provides high-level domain name to address and address to domain name resolution. With these options it provides low-level DNS resource record resolution. The search domain logic is automatically turned off when these options are used, i.e. specified domain names need to be fully qualified domain names. Moreover, IDNA internal domain name translation is turned off as well, i.e. international domain names should be specified in `xn--…` notation, unless look-up in MulticastDNS/LLMNR is desired, in which case UTF-8 characters should be used. `--service-address=BOOL` Takes a boolean parameter. If true (the default), when doing a service lookup with `--service` the hostnames contained in the `SRV` resource records are resolved as well. `--service-txt=BOOL` Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with `--service` the `TXT` service metadata record is resolved as well. `--cname=BOOL` Takes a boolean parameter. If true (the default), DNS `CNAME` or `DNAME` redirections are followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is returned. `--validate=BOOL` Takes a boolean parameter; used in conjunction with `query`. If true (the default), DNSSEC validation is applied as usual — under the condition that it is enabled for the network and for `systemd-resolved.service` as a whole. If false, DNSSEC validation is disabled for the specific query, regardless of whether it is enabled for the network or in the service. Note that setting this option to true does not force DNSSEC validation on systems/networks where DNSSEC is turned off. This option is only suitable to turn off such validation where otherwise enabled, not enable validation where otherwise disabled. `--synthesize=BOOL` Takes a boolean parameter; used in conjunction with `query`. If true (the default), select domains are resolved on the local system, among them `localhost`, `_gateway`, `_outbound`, `_localdnsstub` and `_localdnsproxy` or entries from `/etc/hosts`. If false these domains are not resolved locally, and either fail (in case of `localhost`, `_gateway` or `_outbound` and suchlike) or go to the network via regular DNS/mDNS/LLMNR lookups (in case of `/etc/hosts` entries). `--cache=BOOL` Takes a boolean parameter; used in conjunction with `query`. If true (the default), lookups use the local DNS resource record cache. If false, lookups are routed to the network instead, regardless of whether already available in the local cache. `--zone=BOOL` Takes a boolean parameter; used in conjunction with `query`. If true (the default), lookups are answered from locally registered LLMNR or mDNS resource records, if defined. If false, locally registered LLMNR/mDNS records are not considered for the lookup request. `--trust-anchor=BOOL` Takes a boolean parameter; used in conjunction with `query`. If true (the default), lookups for DS and DNSKEY are answered from the local DNSSEC trust anchors if possible. If false, the local trust store is not considered for the lookup request. `--network=BOOL` Takes a boolean parameter; used in conjunction with `query`. If true (the default), lookups are answered via DNS, LLMNR or mDNS network requests if they cannot be synthesized locally, or be answered from the local cache, zone or trust anchors (see above). If false, the request is not answered from the network and will thus fail if none of the indicated sources can answer them. `--search=BOOL` Takes a boolean parameter. If true (the default), any specified single-label hostnames will be searched in the domains configured in the search domain list, if it is non-empty. Otherwise, the search domain logic is disabled. Note that this option has no effect if `--type=` is used (see above), in which case the search domain logic is unconditionally turned off. `--raw`\[=payload\|packet\] Dump the answer records as binary data. If there is no argument or if the argument is `payload`, the payload of the resource record data is exported, i.e. not the whole "RDATA", but just primary contents. If the argument is `packet`, the whole resource record is dumped in wire format, prefixed by length specified as a little-endian 64-bit integer. This format allows multiple record to be dumped and unambiguously parsed. Note that `payload` is only supported for a small subset of resource record types: SSHFP, TLSA, OPENPGPKEY where this dumps the key material only; and A, AAAA where this dumps the address data. This option may only be used with `--type=` or an RFC 4501 `dns:` URI, which both perform DNS resource record lookups. It may not be combined with regular hostname or address lookups. `--legend=BOOL` Takes a boolean parameter. If true (the default), column headers and meta information about the query response are shown. Otherwise, this output is suppressed. `--stale-data=BOOL` Takes a boolean parameter; used in conjunction with `query`. If true (the default), lookups are answered with stale data (expired resource records) if possible. If false, the stale data is not considered for the lookup request. `--relax-single-label=BOOL` Takes a boolean parameter; used in conjunction with `query`. If true, rules regarding routing of single-label names are relaxed. Defaults to false. By default, lookups of single-label names are assumed to refer to local hosts to be resolved via local resolution such as LLMNR or via search domain qualification and are not routed to upstream servers as is. If this option is enabled these rules are disabled and the queries are routed upstream anyway. Also see the `ResolveUnicastSingleLabel=` option in `resolved.conf(5)` which provides a system-wide option that controls this behaviour. # Compatibility with `resolvconf(8)` `resolvectl` is a multi-call binary. When invoked as `resolvconf` (generally achieved by means of a symbolic link of this name to the `resolvectl` binary) it is run in a limited `resolvconf(8)` compatibility mode. It accepts mostly the same arguments and pushes all data into `systemd-resolved.service(8)`, similar to how `dns` and `domain` commands operate. Note that `systemd-resolved.service` is the only supported backend, which is different from other implementations of this command. `/etc/resolv.conf` will only be updated with servers added with this command when `/etc/resolv.conf` is a symlink to `/run/systemd/resolve/resolv.conf`, and not a static file. See the discussion of `/etc/resolv.conf` handling in `systemd-resolved.service(8)`. Not all operations supported by other implementations are supported natively. Specifically: `-a` Registers per-interface DNS configuration data with `systemd-resolved`. Expects a network interface name as only command line argument. Reads `resolv.conf(5)`-compatible DNS configuration data from its standard input. Relevant fields are `nameserver` and `domain`/`search`. This command is mostly identical to invoking `resolvectl` with a combination of `dns` and `domain` commands. If a relevant input line has invalid syntax, the command fails and leaves the existing per-interface configuration unchanged. `-d` Unregisters per-interface DNS configuration data with `systemd-resolved`. This command is mostly identical to invoking `resolvectl revert`. `-f` When specified `-a` and `-d` will not complain about missing network interfaces and will silently execute no operation in that case. `-x` This switch for "exclusive" operation is supported only partially. It is mapped to an additional configured search domain of `~.` — i.e. ensures that DNS traffic is preferably routed to the DNS servers on this interface, unless there are other, more specific domains configured on other interfaces. `-p` When specified, the interface will not be used as the default route. See also `systemd-resolved.service(8)` about the default route. `-m` The switch is not supported and is silently ignored. `-u`; `-I`; `-i`; `-l`; `-R`; `-r`; `-v`; `-V`; `--enable-updates`; `--disable-updates`; `--are-updates-enabled` These switches are not supported and the command will fail if used. See `resolvconf(8)` for details on those command line options. # Examples
Retrieve the addresses of the `www.0pointer.net` domain (`A` and `AAAA` resource records)
$ resolvectl query www.0pointer.net www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 85.214.157.71 -- Information acquired via protocol DNS in 611.6ms. -- Data is authenticated: no
Retrieve the domain of the `85.214.157.71` IP address (`PTR` resource record)
$ resolvectl query 85.214.157.71 85.214.157.71: gardel.0pointer.net -- Information acquired via protocol DNS in 1.2997s. -- Data is authenticated: no
Retrieve the `MX` record of the `yahoo.com` domain
$ resolvectl --legend=no -t MX query yahoo.com yahoo.com. IN MX 1 mta7.am0.yahoodns.net yahoo.com. IN MX 1 mta6.am0.yahoodns.net yahoo.com. IN MX 1 mta5.am0.yahoodns.net
Resolve an `SRV` service
$ resolvectl service _xmpp-server._tcp gmail.com _xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0] 173.194.210.125 alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0] 173.194.65.125 …
Retrieve a PGP key (`OPENPGP` resource record)
$ resolvectl openpgp zbyszek@fedoraproject.org d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs …
Retrieve a TLS key (`TLSA` resource record)
$ resolvectl tlsa tcp fedoraproject.org:443 _443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0 -- Cert. usage: CA constraint -- Selector: Full Certificate -- Matching type: SHA-256 `tcp` and `:443` are optional and could be skipped.
# See Also `systemd(1)`, `systemd-resolved.service(8)`, `systemd.dnssd(5)`, `systemd-networkd.service(8)`, `resolvconf(8)` # run0 systemd run0 1 run0 Elevate privileges run0 OPTIONS COMMAND # Description `run0` may be used to temporarily and interactively acquire elevated or different privileges. It serves a similar purpose as `sudo(8)`, but operates differently in a couple of key areas: - No execution or security context credentials are inherited from the caller into the invoked commands, as they are invoked from a fresh, isolated service forked off by the service manager. - Authentication takes place via [polkit](https://www.freedesktop.org/wiki/Software/polkit), thus isolating the authentication prompt from the terminal (if possible). - An independent pseudo-tty is allocated for the invoked command, detaching its lifecycle and isolating it for security. - No SetUID/SetGID file access bit functionality is used for the implementation. Altogether this should provide a safer and more robust alternative to the `sudo` mechanism, in particular in OS environments where SetUID/SetGID support is not available (for example by setting the `NoNewPrivileges=` variable in `systemd-system.conf(5)`). Any session invoked via `run0` will run through the `systemd-run0` PAM stack, except for interactive shells started via `systemd-ptybrokerd.service(8)`, which run through the `systemd-ptybroker-shell` PAM stack instead. Note that `run0` is implemented as an alternative multi-call invocation of `systemd-run(1)`. That is, `run0` is a symbolic link to `systemd-run` executable file, and it behaves as `run0` if it is invoked through the symbolic link, otherwise behaves as `systemd-run`. Note that TTY isolation as provided by the default value of the `--pty` option is a core feature of `run0`. Redirecting terminals must therefore be done with care, avoiding giving such control to untrusted programs. When `run0` is invoked locally on a terminal to run an interactive shell (i.e. without an explicit command), and no options are specified that require the transient service unit to be set up in a specific way (such as `--unit=`, `--property=` or `--slice=`), the session is not created via the service manager APIs directly. Instead, the pseudo TTY and the shell running on it are requested from `systemd-ptybrokerd.service(8)`, which allocates the pseudo TTY, retains its frontend (i.e. `master`) side and invokes the shell as a transient service unit on its backend. In this mode privileges are authorized via the `io.systemd.PTYBroker.acquire-pty-with-shell` polkit action (rather than the `org.freedesktop.systemd1.manage-units` action used otherwise), the pseudo TTY of the session remains registered with the broker for the lifetime of the session (and may be listed, monitored or hung up via `ptyctl(1)`). # Options The following options are understood: `--unit=` Use this unit name instead of an automatically generated one. `--property=` Sets a property of the service unit that is created. This option takes an assignment in the same format as `systemctl(1)`'s `set-property` command. `--description=` Provide a description for the service unit that is invoked. If not specified, the command itself will be used as a description. See `Description=` in `systemd.unit(5)`. `--slice=` Make the new `.service` unit part of the specified slice, instead of `user.slice`. This option conflicts with `--lightweight=` and `--area=`, and implies `XDG_SESSION_CLASS=none`, to keep the new process within the specified slice instead of a new session scope. `--slice-inherit` Make the new `.service` unit part of the slice the `run0` itself has been invoked in. This option may be combined with `--slice=`, in which case the slice specified via `--slice=` is placed within the slice the `run0` command is invoked in. Also conflicts with `--lightweight=` and `--area=` and implies `XDG_SESSION_CLASS=none`, similar to `--slice=`. Example: consider `run0` being invoked in the slice `foo.slice`, and the `--slice=` argument is `bar`. The unit will then be placed under `foo-bar.slice`. `--user=`; `-u`; `--group=`; `-g` Switches to the specified user/group. If not specified defaults to `root`, unless `--area=` or `--empower` are used (see below), in which case this defaults to the invoking user. `--nice=` Runs the invoked session with the specified nice level. `--chdir=`; `-D` Runs the invoked session with the specified working directory. If not specified defaults to the client's current working directory if switching to the root user, or the target user's home directory otherwise. `-k`; `--reset-timestamp` Revokes temporary polkit authorization for this terminal, if present. `-K`; `--remove-timestamp` Revokes all temporary polkit authorizations for this user session. `-v`; `--validate` Request authorization from polkit. Can be used to create a temporary authorization without running a command. `--via-shell` Invokes the target user's login shell and runs the specified command (if any) via it. `-i` Shortcut for `--via-shell --chdir='~'`. `--setenv=NAME[=VALUE]` Runs the invoked session with the specified environment variable set. This parameter may be used more than once to set multiple variables. When `=` and \ are omitted, the value of the variable with the same name in the invoking environment will be used. `--background=COLOR` Change the terminal background color to the specified ANSI color as long as the session lasts. If not specified, the background will be tinted in a reddish tone when operating as root, and in a yellowish tone when operating under another UID, as reminder of the changed privileges. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as `40`, `41`, …, `47`, `48;2;…`, `48;5;…`. See [ANSI Escape Code (Wikipedia)](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters) for details. Set to an empty string to disable. Example: `--background=44` for a blue background. `--pty`; `--pty-late`; `--pipe` Request allocation of a pseudo TTY for the `run0` session (in case of `--pty` or `--pty-late`), or request passing the caller's STDIO file descriptors directly through (in case of `--pipe`). `--pty-late` is very similar to `--pty` but begins the TTY processing only once unit startup is complete, leaving input to any passwords/polkit agents until that time. If neither switch is specified, or if both `--pipe` and one of `--pty`/`--pty-late` are specified, the mode will be picked automatically: if standard input, standard output, and standard error output are all connected to a TTY then a pseudo TTY is allocated (in `--pty-late` mode unless `--no-ask-password` is specified in which case `--pty` is selected), otherwise the relevant file descriptors are passed through directly. As mentioned above, TTY isolation as implemented by the default value of this option is crucial for security, so care must be taken when overriding it. `--pty` and `--pipe` were added in v257. `--pty-late` was added in v258. `--shell-prompt-prefix=STRING` Set a shell prompt prefix string. This ultimately controls the `$SHELL_PROMPT_PREFIX` environment variable for the invoked program, which is typically imported into the shell prompt. By default – if emojis are supported –, a superhero emoji is shown (🦸). This default may also be changed (or turned off) by passing the `$SYSTEMD_RUN_SHELL_PROMPT_PREFIX` environment variable to `run0`, see below. Set to an empty string to disable shell prompt prefixing. `--lightweight=BOOLEAN` Controls whether to activate the per-user service manager for the target user. By default (unset or set to `auto`), if the target user is `root` or a system user the per-user service manager is not activated as effect of the `run0` invocation, otherwise it is. This ultimately controls the `$XDG_SESSION_CLASS` environment variable `pam_systemd(8)` respects. `--area=AREA` Controls the "area" of the target account to log into. Areas are secondary home directories within the primary home directory of the target user, i.e. logging into area `foobar` of an account translates to `$HOME` being set to `~/Areas/foobar` on login. If this option is used, the default user to transition to changes from root to the calling user's (but `--user=` takes precedence, see above). Or in other words, just specifying an area without a user is a mechanism to create a new session of the calling user, just with a different area. This ultimately controls the `$XDG_AREA` environment variable `pam_systemd(8)` respects. For details on the area concept see `pam_systemd_home(8)`. `--empower` If specified, run0 will elevate the privileges of the selected user (using `--user=`) or the current user if no user is explicitly selected. Currently this means we give the invoked process all available capabilities and add the `empower` group as a supplemental group (for which all polkit actions are allowed by default), but other privileges may be granted in the future as well when using this option. Note that other (unprivileged) processes of the selected user will have privileges over the invoked process. Consider not using this option in an environment where there might be malicious processes running as the selected user. `--same-root-dir` Execute the `run0` session in the same root directory that the `run0` command is executed in. `--machine=` Execute operation in a local container. Specify a container name to connect to. `-n`; `--non-interactive` Equivalent to `--no-ask-password`. `--no-pager` Do not pipe output into a pager. This currently only applies to `--help`. (The pager is not started during normal operation.) All command line arguments after the first non-option argument become part of the command line of the launched process. If no command line is specified an interactive shell is invoked. The shell to invoke may be controlled through `--via-shell` - when specified the target user's shell is used - or `--setenv=SHELL=…`. By default, the *originating user's* shell is executed if operating locally, or `/bin/sh` when operating with `--machine=`. Note that unlike `sudo`, `run0` always spawns shells with login shell semantics, regardless of `-i`. # Exit status On success, 0 is returned. If `run0` failed to start the session or the specified command fails, a non-zero return value will be returned. # Environment Variables As with `systemd-run`, the session will inherit the system environment from the service manager. In addition, the following environment variables will be set: `$TERM` Copied from the `$TERM` of the caller. Can be overridden with `--setenv=` `$SUDO_USER` Set to the username of the originating user. `$SUDO_UID` Set to the numeric UNIX user id of the originating user. `$SUDO_GID` Set to the primary numeric UNIX group id of the originating session. `$SHELL_PROMPT_PREFIX` By default, set to the superhero emoji (if supported), but may be overridden with the `$SYSTEMD_RUN_SHELL_PROMPT_PREFIX` environment variable (see below), or the `--shell-prompt-prefix=` switch (see above). The following variables may be passed to `run0`: `$SYSTEMD_RUN_SHELL_PROMPT_PREFIX` If set, overrides the default shell prompt prefix that `run0` sets for the invoked shell (the superhero emoji). Set to an empty string to disable shell prompt prefixing. # See Also `systemd(1)`, `systemd-run(1)`, `sudo(8)`, `machinectl(1)`, `pam_systemd(8)` # sd-bus-errors systemd sd-bus-errors 3 sd-bus-errors SD_BUS_ERROR_FAILED SD_BUS_ERROR_NO_MEMORY SD_BUS_ERROR_SERVICE_UNKNOWN SD_BUS_ERROR_NAME_HAS_NO_OWNER SD_BUS_ERROR_NO_REPLY SD_BUS_ERROR_IO_ERROR SD_BUS_ERROR_BAD_ADDRESS SD_BUS_ERROR_NOT_SUPPORTED SD_BUS_ERROR_LIMITS_EXCEEDED SD_BUS_ERROR_ACCESS_DENIED SD_BUS_ERROR_AUTH_FAILED SD_BUS_ERROR_NO_SERVER SD_BUS_ERROR_TIMEOUT SD_BUS_ERROR_NO_NETWORK SD_BUS_ERROR_ADDRESS_IN_USE SD_BUS_ERROR_DISCONNECTED SD_BUS_ERROR_INVALID_ARGS SD_BUS_ERROR_FILE_NOT_FOUND SD_BUS_ERROR_FILE_EXISTS SD_BUS_ERROR_UNKNOWN_METHOD SD_BUS_ERROR_UNKNOWN_OBJECT SD_BUS_ERROR_UNKNOWN_INTERFACE SD_BUS_ERROR_UNKNOWN_PROPERTY SD_BUS_ERROR_PROPERTY_READ_ONLY SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN SD_BUS_ERROR_INVALID_SIGNATURE SD_BUS_ERROR_INCONSISTENT_MESSAGE SD_BUS_ERROR_TIMED_OUT SD_BUS_ERROR_MATCH_RULE_NOT_FOUND SD_BUS_ERROR_MATCH_RULE_INVALID SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED SD_BUS_ERROR_INVALID_FILE_CONTENT SD_BUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN SD_BUS_ERROR_OBJECT_PATH_IN_USE Standard D-Bus error names \#include \ \#define SD_BUS_ERROR_FAILED "org.freedesktop.DBus.Error.Failed" \#define SD_BUS_ERROR_NO_MEMORY "org.freedesktop.DBus.Error.NoMemory" \#define SD_BUS_ERROR_SERVICE_UNKNOWN "org.freedesktop.DBus.Error.ServiceUnknown" \#define SD_BUS_ERROR_NAME_HAS_NO_OWNER "org.freedesktop.DBus.Error.NameHasNoOwner" \#define SD_BUS_ERROR_NO_REPLY "org.freedesktop.DBus.Error.NoReply" \#define SD_BUS_ERROR_IO_ERROR "org.freedesktop.DBus.Error.IOError" \#define SD_BUS_ERROR_BAD_ADDRESS "org.freedesktop.DBus.Error.BadAddress" \#define SD_BUS_ERROR_NOT_SUPPORTED "org.freedesktop.DBus.Error.NotSupported" \#define SD_BUS_ERROR_LIMITS_EXCEEDED "org.freedesktop.DBus.Error.LimitsExceeded" \#define SD_BUS_ERROR_ACCESS_DENIED "org.freedesktop.DBus.Error.AccessDenied" \#define SD_BUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed" \#define SD_BUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer" \#define SD_BUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout" \#define SD_BUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork" \#define SD_BUS_ERROR_ADDRESS_IN_USE "org.freedesktop.DBus.Error.AddressInUse" \#define SD_BUS_ERROR_DISCONNECTED "org.freedesktop.DBus.Error.Disconnected" \#define SD_BUS_ERROR_INVALID_ARGS "org.freedesktop.DBus.Error.InvalidArgs" \#define SD_BUS_ERROR_FILE_NOT_FOUND "org.freedesktop.DBus.Error.FileNotFound" \#define SD_BUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists" \#define SD_BUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod" \#define SD_BUS_ERROR_UNKNOWN_OBJECT "org.freedesktop.DBus.Error.UnknownObject" \#define SD_BUS_ERROR_UNKNOWN_INTERFACE "org.freedesktop.DBus.Error.UnknownInterface" \#define SD_BUS_ERROR_UNKNOWN_PROPERTY "org.freedesktop.DBus.Error.UnknownProperty" \#define SD_BUS_ERROR_PROPERTY_READ_ONLY "org.freedesktop.DBus.Error.PropertyReadOnly" \#define SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN "org.freedesktop.DBus.Error.UnixProcessIdUnknown" \#define SD_BUS_ERROR_INVALID_SIGNATURE "org.freedesktop.DBus.Error.InvalidSignature" \#define SD_BUS_ERROR_INCONSISTENT_MESSAGE "org.freedesktop.DBus.Error.InconsistentMessage" \#define SD_BUS_ERROR_TIMED_OUT "org.freedesktop.DBus.Error.TimedOut" \#define SD_BUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound" \#define SD_BUS_ERROR_MATCH_RULE_INVALID "org.freedesktop.DBus.Error.MatchRuleInvalid" \#define SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED \\ "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired" \#define SD_BUS_ERROR_INVALID_FILE_CONTENT "org.freedesktop.DBus.Error.InvalidFileContent" \#define SD_BUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN \\ "org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown" \#define SD_BUS_ERROR_OBJECT_PATH_IN_USE "org.freedesktop.DBus.Error.ObjectPathInUse" # Description In addition to the error names user programs define, D-Bus knows a number of generic, standardized error names that are listed below. In addition to this list, in sd-bus, the special error namespace `System.Error.` is used to map arbitrary Linux system errors (as defined by `errno(3)`) to D-Bus errors and back. For example, the error `EUCLEAN` is mapped to `System.Error.EUCLEAN` and back. `SD_BUS_ERROR_FAILED` A generic error indication. See the error message for further details. This error name should be avoided, in favor of a more expressive error name. `SD_BUS_ERROR_NO_MEMORY` A memory allocation failed, and the requested operation could not be completed. `SD_BUS_ERROR_SERVICE_UNKNOWN` The contacted bus service is unknown and cannot be activated. `SD_BUS_ERROR_NAME_HAS_NO_OWNER` The specified bus service name currently has no owner. `SD_BUS_ERROR_NO_REPLY` A message did not receive a reply. This error is usually generated after a timeout. `SD_BUS_ERROR_IO_ERROR` Generic input/output error, for example when accessing a socket or other I/O context. `SD_BUS_ERROR_BAD_ADDRESS` The specified D-Bus bus address string is malformed. `SD_BUS_ERROR_NOT_SUPPORTED` The requested operation is not supported on the local system. `SD_BUS_ERROR_LIMITS_EXCEEDED` Some limited resource has been exhausted. `SD_BUS_ERROR_ACCESS_DENIED` Access to a resource has been denied due to security restrictions. `SD_BUS_ERROR_AUTH_FAILED` Authentication did not complete successfully. `SD_BUS_ERROR_NO_SERVER` Unable to connect to the specified server. `SD_BUS_ERROR_TIMEOUT` An operation timed out. Note that method calls which timeout generate a `SD_BUS_ERROR_NO_REPLY`. `SD_BUS_ERROR_NO_NETWORK` No network available to execute requested network operation on. `SD_BUS_ERROR_ADDRESS_IN_USE` The specified network address is already being listened on. `SD_BUS_ERROR_DISCONNECTED` The connection has been terminated. `SD_BUS_ERROR_INVALID_ARGS` One or more invalid arguments have been passed. `SD_BUS_ERROR_FILE_NOT_FOUND` The requested file could not be found. `SD_BUS_ERROR_FILE_EXISTS` The requested file already exists. `SD_BUS_ERROR_UNKNOWN_METHOD` The requested method does not exist in the selected interface. `SD_BUS_ERROR_UNKNOWN_OBJECT` The requested object does not exist in the selected service. `SD_BUS_ERROR_UNKNOWN_INTERFACE` The requested interface does not exist on the selected object. `SD_BUS_ERROR_UNKNOWN_PROPERTY` The requested property does not exist in the selected interface. `SD_BUS_ERROR_PROPERTY_READ_ONLY` A write operation was requested on a read-only property. `SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN` The requested PID is not known. `SD_BUS_ERROR_INVALID_SIGNATURE` The specified message signature is not valid. `SD_BUS_ERROR_INCONSISTENT_MESSAGE` The passed message does not validate correctly. `SD_BUS_ERROR_MATCH_RULE_NOT_FOUND` The specified match rule does not exist. `SD_BUS_ERROR_MATCH_RULE_INVALID` The specified match rule is invalid. `SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED` Access to the requested operation is not permitted. However, it might be available after interactive authentication. This is usually returned by method calls supporting a framework for additional interactive authorization, when interactive authorization was not enabled with the `sd_bus_message_set_allow_interactive_authorization(3)` for the method call message. # See Also `systemd(1)`, `libsystemd(3)`, `sd-bus(3)`, `sd_bus_error(3)`, `sd_bus_message_set_allow_interactive_authorization(3)`, `errno(3)`, `strerror_r(3)` # sd-bus systemd sd-bus 3 sd-bus A lightweight D-Bus IPC client library \#include \ pkg-config --cflags --libs libsystemd # Description `sd-bus.h` is part of `libsystemd(3)` and provides an implementation of a D-Bus IPC client. See [](https://www.freedesktop.org/software/dbus/) for more information about D-Bus IPC. See `sd_bus_add_match(3)`,, `sd_bus_add_object(3)`,, `sd_bus_add_object_manager(3)`,, `sd_bus_add_object_vtable(3)`,, `sd_bus_add_fallback(3)`,, `sd_bus_add_fallback_vtable(3)`,, `sd_bus_add_filter(3)`,, `sd_bus_add_node_enumerator(3)`,, `sd_bus_attach_event(3)`,, `sd_bus_call(3)`,, `sd_bus_call_async(3)`,, `sd_bus_call_method(3)`,, `sd_bus_call_method_async(3)`,, `sd_bus_can_send(3)`,, `sd_bus_close(3)`,, `sd_bus_creds_get_pid(3)`,, `sd_bus_creds_new_from_pid(3)`,, `sd_bus_default(3)`,, `sd_bus_emit_interfaces_added(3)`,, `sd_bus_emit_interfaces_added_strv(3)`,, `sd_bus_emit_interfaces_removed(3)`,, `sd_bus_emit_interfaces_removed_strv(3)`,, `sd_bus_emit_object_added(3)`,, `sd_bus_emit_object_removed(3)`,, `sd_bus_emit_properties_changed(3)`,, `sd_bus_emit_properties_changed_strv(3)`,, `sd_bus_emit_signal(3)`,, `sd_bus_emit_signalv(3)`,, `sd_bus_emit_signal_to(3)`,, `sd_bus_emit_signal_tov(3)`,, `sd_bus_enqueue_for_read(3)`,, `sd-bus-errors(3)`,, `sd_bus_error(3)`,, `sd_bus_error_add_map(3)`,, `sd_bus_get_address(3)`,, `sd_bus_get_allow_interactive_authorization(3)`,, `sd_bus_get_bus_id(3)`,, `sd_bus_get_creds_mask(3)`,, `sd_bus_get_current_handler(3)`,, `sd_bus_get_current_message(3)`,, `sd_bus_get_current_slot(3)`,, `sd_bus_get_current_userdata(3)`,, `sd_bus_get_exit_on_disconnect(3)`,, `sd_bus_get_fd(3)`,, `sd_bus_get_method_call_timeout(3)`,, `sd_bus_get_n_queued_read(3)`,, `sd_bus_get_name_creds(3)`,, `sd_bus_get_name_machine_id(3)`,, `sd_bus_get_owner_creds(3)`,, `sd_bus_get_property(3)`,, `sd_bus_get_property_string(3)`,, `sd_bus_get_property_strv(3)`,, `sd_bus_get_property_trivial(3)`,, `sd_bus_get_scope(3)`,, `sd_bus_get_tid(3)`,, `sd_bus_get_unique_name(3)`,, `sd_bus_interface_name_is_valid(3)`,, `sd_bus_is_bus_client(3)`,, `sd_bus_is_monitor(3)`,, `sd_bus_is_open(3)`,, `sd_bus_is_server(3)`,, `sd_bus_list_names(3)`,, `sd_bus_message_append(3)`,, `sd_bus_message_append_array(3)`,, `sd_bus_message_append_basic(3)`,, `sd_bus_message_append_string_memfd(3)`,, `sd_bus_message_append_strv(3)`,, `sd_bus_message_at_end(3)`,, `sd_bus_message_close_container(3)`,, `sd_bus_message_copy(3)`,, `sd_bus_message_dump(3)`,, `sd_bus_message_enter_container(3)`,, `sd_bus_message_exit_container(3)`,, `sd_bus_message_get_allow_interactive_authorization(3)`,, `sd_bus_message_get_cookie(3)`,, `sd_bus_message_get_creds(3)`,, `sd_bus_message_get_errno(3)`,, `sd_bus_message_get_error(3)`,, `sd_bus_message_get_monotonic_usec(3)`,, `sd_bus_message_get_sender(3)`,, `sd_bus_message_get_signature(3)`,, `sd_bus_message_get_type(3)`,, `sd_bus_message_new(3)`,, `sd_bus_message_new_method_call(3)`,, `sd_bus_message_new_method_error(3)`,, `sd_bus_message_new_signal(3)`,, `sd_bus_message_new_signal_to(3)`,, `sd_bus_message_open_container(3)`,, `sd_bus_message_peek_type(3)`,, `sd_bus_message_read(3)`,, `sd_bus_message_read_array(3)`,, `sd_bus_message_read_basic(3)`,, `sd_bus_message_read_strv(3)`,, `sd_bus_message_rewind(3)`,, `sd_bus_message_seal(3)`,, `sd_bus_message_send(3)`,, `sd_bus_message_sensitive(3)`,, `sd_bus_message_set_allow_interactive_authorization(3)`,, `sd_bus_message_set_destination(3)`,, `sd_bus_message_set_expect_reply(3)`,, `sd_bus_message_set_sender(3)`,, `sd_bus_message_skip(3)`,, `sd_bus_message_verify_type(3)`,, `sd_bus_negotiate_fds(3)`,, `sd_bus_new(3)`,, `sd_bus_path_encode(3)`,, `sd_bus_pending_method_calls(3)`,, `sd_bus_process(3)`,, `sd_bus_query_sender_creds(3)`,, `sd_bus_query_sender_privilege(3)`,, `sd_bus_reply_method_error(3)`,, `sd_bus_reply_method_return(3)`,, `sd_bus_request_name(3)`,, `sd_bus_send(3)`,, `sd_bus_send_to(3)`,, `sd_bus_set_address(3)`,, `sd_bus_set_allow_interactive_authorization(3)`,, `sd_bus_set_bus_client(3)`,, `sd_bus_set_close_on_exit(3)`,, `sd_bus_set_connected_signal(3)`,, `sd_bus_set_description(3)`,, `sd_bus_set_exit_on_disconnect(3)`,, `sd_bus_set_fd(3)`,, `sd_bus_set_method_call_timeout(3)`,, `sd_bus_set_monitor(3)`,, `sd_bus_set_property(3)`,, `sd_bus_set_propertyv(3)`,, `sd_bus_set_sender(3)`,, `sd_bus_set_server(3)`,, `sd_bus_set_watch_bind(3)`, `sd_bus_slot_get_current_handler(3)`,, `sd_bus_slot_get_current_message(3)`,, `sd_bus_slot_get_current_userdata(3)`,, `sd_bus_slot_set_description(3)`,, `sd_bus_slot_set_destroy_callback(3)`,, `sd_bus_slot_set_floating(3)`,, `sd_bus_slot_set_userdata(3)`,, `sd_bus_start(3)`,, `sd_bus_track_add_name(3)`,, `sd_bus_track_new(3)`,, `sd_bus_wait(3)` for more information about the functions available. The `busctl(1)` tool makes the functionality implemented by sd-bus available from the command line. # See Also `systemd(1)`, `sd-event(3)`, `busctl(1)`, `sd-varlink(3)`, `dbus-daemon(1)`, `dbus-send(1)`, `pkg-config(1)` # sd-daemon systemd sd-daemon 3 sd-daemon SD_EMERG SD_ALERT SD_CRIT SD_ERR SD_WARNING SD_NOTICE SD_INFO SD_DEBUG APIs for new-style daemons \#include \ pkg-config --cflags --libs libsystemd # Description `sd-daemon.h` is part of `libsystemd(3)` and provides APIs for new-style daemons, as implemented by the `systemd(1)` service manager. See `sd_listen_fds(3)`, `sd_notify(3)`, `sd_booted(3)`, `sd_is_fifo(3)`, `sd_watchdog_enabled(3)`, and `sd_pidfd_get_inode_id(3)` for more information about the functions implemented. In addition to these functions, a couple of logging prefixes are defined as macros: #define SD_EMERG "<0>" /* system is unusable */ #define SD_ALERT "<1>" /* action must be taken immediately */ #define SD_CRIT "<2>" /* critical conditions */ #define SD_ERR "<3>" /* error conditions */ #define SD_WARNING "<4>" /* warning conditions */ #define SD_NOTICE "<5>" /* normal but significant condition */ #define SD_INFO "<6>" /* informational */ #define SD_DEBUG "<7>" /* debug-level messages */ These prefixes are intended to be used in conjunction with stderr-based logging (or stdout-based logging) as implemented by systemd. If a systemd service definition file is configured with `StandardError=journal` or `StandardError=kmsg` (and similar with `StandardOutput=`), these prefixes can be used to encode a log level in lines printed. This is similar to the kernel `printk()`-style logging. See `klogctl(2)` for more information. The log levels are identical to `syslog(3)`'s log level system. To use these prefixes simply prefix every line with one of these strings. A line that is not prefixed will be logged at the default log level SD_INFO.
Hello World
A daemon may log with the log level NOTICE by issuing this call: fprintf(stderr, SD_NOTICE "Hello World!\n");
# See Also `systemd(1)`, `sd_listen_fds(3)`, `sd_notify(3)`, `sd_booted(3)`, `sd_is_fifo(3)`, `sd_watchdog_enabled(3)`, `sd_pidfd_get_inode_id(3)`, `daemon(7)`, `systemd.service(5)`, `systemd.socket(5)`, `fprintf(3)`, `pkg-config(1)` # sd-device systemd sd-device 3 sd-device API for enumerating and introspecting local devices \#include \ pkg-config --cflags --libs libsystemd # Description `sd-device.h` is part of `libsystemd(3)` and provides an API to introspect and enumerate devices on the local system. It provides a programmatic interface to the database of devices and their properties managed by `systemd-udevd.service(8)`. This API is a replacement for `libudev(3)` and `libudev.h`. See `sd_device_get_syspath(3)`,, `sd_device_ref(3)` for more information about the functions available. # See Also `systemd(1)`, `sd-event(3)`, `udevadm(8)` # sd-dlopen systemd sd-dlopen 3 sd-dlopen ELF dlopen metadata annotation macros \#include \ pkg-config --cflags libsystemd # Description `sd-dlopen.h` provides macros for embedding `.note.dlopen` metadata in ELF binaries, implementing the [ELF dlopen metadata](https://uapi-group.org/specifications/specs/elf_dlopen_metadata/) specification for declaring optional shared library dependencies that are loaded via `dlopen(3)` at runtime. The header is self-contained and does not require runtime linkage against `libsystemd(3)`. Projects only need the installed header to use the macros. Package managers and build systems can read the embedded ELF notes to discover runtime dependencies that are not visible in ELF `DT_NEEDED` entries. See `SD_ELF_NOTE_DLOPEN(3)` for details on the available macros and constants. # Notes The macros described here are header-only and do not require runtime linkage against `libsystemd(3)`. Only the installed header and include path (as provided by `pkg-config --cflags libsystemd`) are needed. # History `SD_ELF_NOTE_DLOPEN()` and associated macros and constants were added in version 261. # See Also `systemd(1)`, `SD_ELF_NOTE_DLOPEN(3)`, `dlopen(3)` # sd-event systemd sd-event 3 sd-event A generic event loop implementation \#include \ pkg-config --cflags --libs libsystemd # Description `sd-event.h` is part of `libsystemd(3)` and provides a generic event loop implementation, based on Linux `epoll(7)`. See `sd_event_new(3)`, `sd_event_run(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_add_memory_pressure(3)`, `sd_event_source_unref(3)`, `sd_event_source_set_priority(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_userdata(3)`, `sd_event_source_get_event(3)`, `sd_event_source_get_pending(3)`, `sd_event_source_set_description(3)`, `sd_event_source_set_prepare(3)`, `sd_event_source_set_ratelimit(3)`, `sd_event_wait(3)`, `sd_event_get_fd(3)`, `sd_event_set_watchdog(3)`, `sd_event_exit(3)`, `sd_event_now(3)` for more information about the functions available. The event loop design is targeted on running a separate instance of the event loop in each thread; it has no concept of distributing events from a single event loop instance onto multiple worker threads. Dispatching events is strictly ordered and subject to configurable priorities. In each event loop iteration a single event source is dispatched. Each time an event source is dispatched the kernel is polled for new events, before the next event source is dispatched. The event loop is designed to honor priorities and provide fairness within each priority. It is not designed to provide optimal throughput, as this contradicts these goals due the limitations of the underlying `epoll(7)` primitives. The event loop implementation provides the following features: 1. I/O event sources, based on `epoll(7)`'s file descriptor watching, including edge triggered events (`EPOLLET`). See `sd_event_add_io(3)`. 2. Timer event sources, based on `timerfd_create(2)`, supporting the `CLOCK_MONOTONIC`, `CLOCK_REALTIME`, `CLOCK_BOOTTIME` clocks, as well as the `CLOCK_REALTIME_ALARM` and `CLOCK_BOOTTIME_ALARM` clocks that can resume the system from suspend. When creating timer events a required accuracy parameter may be specified which allows coalescing of timer events to minimize power consumption. See `sd_event_add_time(3)`. 3. UNIX process signal events, based on `signalfd(2)`, including full support for real-time signals, and queued parameters. See `sd_event_add_signal(3)`. 4. Child process state change events, based on `waitid(2)`. See `sd_event_add_child(3)`. 5. Static event sources, of three types: defer, post and exit, for invoking calls in each event loop, after other event sources or at event loop termination. See `sd_event_add_defer(3)`. 6. Event sources may be assigned a 64-bit priority value, that controls the order in which event sources are dispatched if multiple are pending simultaneously. See `sd_event_source_set_priority(3)`. 7. The event loop may automatically send watchdog notification messages to the service manager. See `sd_event_set_watchdog(3)`. 8. The event loop may be integrated into foreign event loops, such as the GLib one. See `sd_event_get_fd(3)` for an example. # See Also `systemd(1)`, `sd_event_new(3)`, `sd_event_run(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_add_memory_pressure(3)`, `sd_event_source_unref(3)`, `sd_event_source_set_priority(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_userdata(3)`, `sd_event_source_get_event(3)`, `sd_event_source_get_pending(3)`, `sd_event_source_set_description(3)`, `sd_event_source_set_prepare(3)`, `sd_event_source_set_ratelimit(3)`, `sd_event_wait(3)`, `sd_event_get_fd(3)`, `sd_event_set_watchdog(3)`, `sd_event_exit(3)`, `sd_event_now(3)`, `epoll(7)`, `timerfd_create(2)`, `signalfd(2)`, `waitid(2)` # sd-hwdb systemd sd-hwdb 3 sd-hwdb Read-only access to the hardware description database \#include \ pkg-config --cflags --libs libsystemd # Description `sd-hwdb.h` is part of `libsystemd(3)` and allows read-only access the systemd database of hardware properties. See `hwdb(7)` and `systemd-hwdb(8)` for more information about the database. See `sd_hwdb_new(3)` and `sd_hwdb_get(3)` for information about the functions available. # See Also `systemd(1)`, `systemd-udevd.service(8)` # sd-id128 systemd sd-id128 3 sd-id128 SD_ID128_ALLF SD_ID128_CONST_STR SD_ID128_FORMAT_STR SD_ID128_FORMAT_VAL SD_ID128_MAKE SD_ID128_MAKE_STR SD_ID128_MAKE_UUID_STR SD_ID128_NULL SD_ID128_UUID_FORMAT_STR sd_id128_equal sd_id128_string_equal sd_id128_in_set sd_id128_in_set_sentinel sd_id128_in_setv sd_id128_is_allf sd_id128_is_null sd_id128_t APIs for processing 128-bit IDs \#include \ `SD_ID128_ALLF` `SD_ID128_NULL` `SD_ID128_CONST_STR(id)` `SD_ID128_FORMAT_STR` `SD_ID128_FORMAT_VAL(id)` `SD_ID128_MAKE(v0, v1, v2, v3, v4, v5, v6, v7, v8, v9, vA, vB, vC, vD, vE, vF)` `SD_ID128_MAKE_STR(v0, v1, v2, v3, v4, v5, v6, v7, v8, v9, vA, vB, vC, vD, vE, vF)` `SD_ID128_MAKE_UUID_STR(v0, v1, v2, v3, v4, v5, v6, v7, v8, v9, vA, vB, vC, vD, vE, vF)` `SD_ID128_UUID_FORMAT_STR` int sd_id128_equal sd_id128_t a sd_id128_t b int sd_id128_string_equal const char \* a sd_id128_t b int sd_id128_is_null sd_id128_t id int sd_id128_is_allf sd_id128_t id int sd_id128_in_setv sd_id128_t id va_list ap int sd_id128_in_set_sentinel sd_id128_t id … SD_ID128_NULL int sd_id128_in_set sd_id128_t id … pkg-config --cflags --libs libsystemd # Description `sd-id128.h` is part of `libsystemd(3)` and provides APIs to generate, convert, and compare 128-bit ID values. The 128-bit ID values processed and generated by these APIs are a generalization of OSF UUIDs as defined by [RFC 4122](https://tools.ietf.org/html/rfc4122) but use a simpler string format. These functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly compatible with those types of IDs. A 128-bit ID is implemented as the following union type: typedef union sd_id128 { uint8_t bytes[16]; uint64_t qwords[2]; } sd_id128_t; This union type allows accessing the 128-bit ID as 16 separate bytes or two 64-bit words. It is generally safer to access the ID components by their 8-bit array to avoid endianness issues. This union is intended to be passed by value (as opposed to pass-by-reference) and may be directly manipulated by clients. A couple of macros are defined to denote and decode 128-bit IDs: `SD_ID128_MAKE()` is used to write a constant ID in source code. A commonly used idiom is to assign a name to an ID using this macro: #define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1) `SD_ID128_NULL` defines an ID consisting of only `NUL` bytes (i.e. all bits off). `SD_ID128_ALLF` defines an ID consisting of only `0xFF` bytes (i.e. all bits on). `SD_ID128_MAKE_STR()` is similar to `SD_ID128_MAKE()`, but creates a `const char*` expression that can be conveniently used in message formats and such: #include #define SD_MESSAGE_COREDUMP_STR SD_ID128_MAKE_STR(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1) int main(int argc, char **argv) { puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR); } `SD_ID128_CONST_STR()` converts constant IDs into constant strings for output. The following example code will output the string "fc2e22bc6ee647b6b90729ab34a250b1": int main(int argc, char *argv[]) { puts("Match for coredumps: %s", SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); } `SD_ID128_FORMAT_STR` and `SD_ID128_FORMAT_VAL()` is used to format an ID in a `printf(3)` format string, as shown in the following example: int main(int argc, char *argv[]) { sd_id128_t id; id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id)); return 0; } `SD_ID128_UUID_FORMAT_STR` and `SD_ID128_MAKE_UUID_STR()` are similar to `SD_ID128_FORMAT_STR` and `SD_ID128_MAKE_STR()`, but include separating hyphens to conform to the "[UUID canonical representation](https://en.wikipedia.org/wiki/Universally_unique_identifier#Format)". They format the string based on [RFC4122](https://tools.ietf.org/html/rfc4122) Variant 1 rules, i.e. converting from Big Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably best to avoid UUIDs of other variants, in order to avoid unnecessary ambiguities. All 128-bit IDs generated by the sd-id128 APIs strictly conform to Variant 1 Version 4 UUIDs, as per RFC 4122. `sd_id128_equal()` compares two 128-bit IDs: int main(int argc, char *argv[]) { sd_id128_t a, b, c; a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e); c = a; assert(sd_id128_equal(a, c)); assert(!sd_id128_equal(a, b)); return 0; } `sd_id128_string_equal()` is similar to `sd_id128_equal()`, but the first ID is formatted as `const char*`. The same restrictions apply as to the first argument of `sd_id128_from_string()`. `sd_id128_is_null()` checks if an ID consists of only `NUL` bytes: assert(sd_id128_is_null(SD_ID128_NULL)); Similarly, `sd_id128_is_allf()` checks if an ID consists of only `0xFF` bytes (all bits on): assert(sd_id128_is_allf(SD_ID128_ALLF)); `sd_id128_in_set_sentinel()` takes a list of IDs and returns true if the first argument is equal to any of the subsequent arguments. The argument list is terminated by an `SD_ID128_NULL` sentinel, which must be present. `sd_id128_in_set()` is a convenience function that takes a list of IDs and returns true if the first argument is equal to any of the subsequent arguments: int main(int argc, char *argv[]) { sd_id12_t a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); assert(sd_id128_in_set(a, a)); assert(sd_id128_in_set(a, a, a)); assert(!sd_id128_in_set(a)); assert(!sd_id128_in_set(a, SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e) SD_ID128_MAKE(2f,88,28,5f,9c,44,09,9d,d7,15,77,04,bc,85,7e,e3) SD_ID128_ALLF)); return 0; } `sd_id128_in_set()` is defined as a macro over `sd_id128_in_set_sentinel()`, adding the `SD_ID128_NULL` sentinel automatically. Since `sd_id128_in_set_sentinel()` uses `SD_ID128_NULL` as the sentinel, `SD_ID128_NULL` cannot be otherwise placed in the argument list. `sd_id128_in_setv()` is similar to `sd_id128_in_set_sentinel()`, but takes a struct varargs argument. New randomized IDs may be generated with `systemd-id128(1)`'s `new` command. See `sd_id128_to_string(3)`, `sd_id128_randomize(3)` and `sd_id128_get_machine(3)` for information about other implemented functions. # History `sd_id128_equal()`, `sd_id128_string_equal()`, `sd_id128_is_null()`, `sd_id128_is_allf()`, `sd_id128_in_setv()`, `sd_id128_in_set_sentinel()`, and `sd_id128_in_set()` were added in version 252. # See Also `systemd(1)`, `sd_id128_to_string(3)`, `sd_id128_randomize(3)`, `sd_id128_get_machine(3)`, `printf(3)`, `journalctl(1)`, `sd-journal(3)`, `pkg-config(1)`, `machine-id(5)` # sd-journal systemd sd-journal 3 sd-journal APIs for submitting and querying log entries to and from the journal \#include \ pkg-config --cflags --libs libsystemd # Description `sd-journal.h` is part of `libsystemd(3)` and provides APIs to submit and query log entries. The APIs exposed act both as client for the `systemd-journald.service(8)` journal service and as parser for the journal files on disk. See `sd_journal_print(3)`, `sd_journal_stream_fd(3)`, `sd_journal_open(3)`, `sd_journal_next(3)`, `sd_journal_get_realtime_usec(3)`, `sd_journal_add_match(3)`, `sd_journal_seek_head(3)`, `sd_journal_enumerate_fields(3)`, `sd_journal_get_cursor(3)`, `sd_journal_get_cutoff_realtime_usec(3)`, `sd_journal_get_cutoff_monotonic_usec(3)`, `sd_journal_get_usage(3)`, `sd_journal_get_catalog(3)`, `sd_journal_get_fd(3)`, `sd_journal_has_runtime_files(3)` and `sd_journal_has_persistent_files(3)` for more information about the functions implemented. Command line access for submitting entries to the journal is available with the `systemd-cat(1)` tool. Command line access for querying entries from the journal is available with the `journalctl(1)` tool. # Thread safety Functions that operate on sd_journal objects are thread agnostic — a given sd_journal pointer may only be used from one thread at a time, but multiple independent threads may use multiple objects concurrently. Some functions — those that are used to send entries to the journal, like `sd_journal_print(3)` and similar, or those that are used to retrieve global information like `sd_journal_stream_fd(3)` and `sd_journal_get_catalog_for_message_id(3)` — are fully thread-safe and may be called from multiple threads in parallel. # Optional dependencies Depending on which build-time options are enabled, functions that operate on sd_journal objects might cause optional shared libraries to be dynamically loaded via `dlopen(3)`, such as decompression libraries (xz, lz4, zstd). # See Also `systemd(1)`, `sd_journal_print(3)`, `sd_journal_stream_fd(3)`, `sd_journal_open(3)`, `sd_journal_next(3)`, `sd_journal_get_data(3)`, `sd_journal_get_realtime_usec(3)`, `sd_journal_add_match(3)`, `sd_journal_seek_head(3)`, `sd_journal_enumerate_fields(3)`, `sd_journal_get_cursor(3)`, `sd_journal_get_cutoff_realtime_usec(3)`, `sd_journal_get_cutoff_monotonic_usec(3)`, `sd_journal_get_usage(3)`, `sd_journal_get_fd(3)`, `sd_journal_query_unique(3)`, `sd_journal_get_catalog(3)`, `sd_journal_has_runtime_files(3)`, `sd_journal_has_persistent_files(3)`, `journalctl(1)`, `sd-id128(3)`, `pkg-config(1)` # sd-json systemd sd-json 3 sd-json APIs for Dealing with JSON Objects \#include \ pkg-config --cflags --libs libsystemd # Description `sd-json.h` is part of `libsystemd(3)` and provides APIs to parse, generate, format and otherwise operate with JSON objects. The API's central data structure is `JsonVariant` which encapsulates a JSON object, array, string, boolean, number or null value. These data structures are mostly considered immutable after construction (i.e. their contents will not change, but some meta-data might, such as reference counters). The APIs broadly fall into five categories: - APIs to directly operate with `JsonVariant` objects, in the `sd_json_variant*` namespace. - APIs to construct complex JSON objects, in the `sd_json_build*` namespace. - APIs to map `JsonVariant` objects and their fields to matching fields in C structures, in the `sd_json_dispatch*` namespace. - APIs to convert a string representation of a JSON object into a `JsonVariant` object, in the `sd_json_parse*` namespace. - APIs to convert an `JsonVariant` object into its string representation, in the `sd_json_format*` namespace. This JSON library will internally encode JSON integer numbers in the range `INT64_MIN`…`UINT64_MAX` into native 64bit signed or unsigned integers, and will reproduce them without loss of precision. Non-integer numbers are stored in 64bit IEEE floating point numbers. If the functions return string arrays, these are generally `NULL` terminated and need to be freed by the caller with the libc `free(3)` call after use, including the strings referenced therein. Similarly, individual strings returned need to be freed, as well. As a special exception, instead of an empty string array `NULL` may be returned, which should be treated equivalent to an empty string array. # See Also `systemd(1)`, `sd-varlink(3)`, `pkg-config(1)` # sd-login systemd sd-login 3 sd-login APIs for tracking logins \#include \ pkg-config --cflags --libs libsystemd # Description `sd-login.h` is part of `libsystemd(3)` and provides APIs to introspect and monitor seat, login session, and user status information on the local system. Note that these APIs only allow purely passive access and monitoring of seats, sessions, and users. To actively make changes to the seat configuration, terminate login sessions, or switch session on a seat you need to utilize the D-Bus API of systemd-logind instead. These functions synchronously access data in `/proc/`, `/sys/fs/cgroup/` and `/run/`. All of these are virtual file systems, hence the runtime cost of the accesses is relatively cheap. It is possible (and often a very good choice) to mix calls to the synchronous interface of `sd-login.h` with the asynchronous D-Bus interface of systemd-logind. However, if this is done you need to think a bit about possible races since the stream of events from D-Bus and from `sd-login.h` interfaces such as the login monitor are asynchronous and not ordered against each other. If the functions return string arrays, these are generally `NULL`-terminated and need to be freed by the caller with the libc `free(3)` call after use, including the strings referenced therein. Similarly, individual strings returned need to be freed, as well. As a special exception, instead of an empty string array `NULL` may be returned, which should be treated equivalent to an empty string array. See `sd_pid_get_session(3)`, `sd_uid_get_state(3)`, `sd_session_is_active(3)`, `sd_seat_get_active(3)`, `sd_get_seats(3)`, `sd_login_monitor_new(3)` for more information about the functions implemented. # Definition of Terms seat A seat consists of all hardware devices assigned to a specific workplace. It consists of at least one graphics device, and usually also includes keyboard, mouse. It can also include video cameras, sound cards and more. Seats are identified by seat names, which are strings (\<= 255 characters), that start with the four characters `seat` followed by at least one character from the range \[a-zA-Z0-9\], `_` and `-`. They are suitable for use as file names. Seat names may or may not be stable and may be reused if a seat becomes available again. session A session is defined by the time a user is logged in until they log out. A session is bound to one or no seats (the latter for 'virtual' ssh logins). Multiple sessions can be attached to the same seat, but only one of them can be active, the others are in the background. A session is identified by a short string. `systemd(1)` ensures that audit sessions are identical to systemd sessions, and uses the audit session ID as session ID in systemd (if auditing is enabled). In general the session identifier is a short string consisting only of \[a-zA-Z0-9\], `_` and `-`, suitable for use as a file name. Session IDs are unique on the local machine and are never reused as long as the machine is online. A user (the way we know it on UNIX) corresponds to the person using a computer. A single user can have multiple sessions open at the same time. A user is identified by a numeric user id (UID) or a user name (a string). A multi-session system allows multiple user sessions on the same seat at the same time. A multi-seat system allows multiple independent seats that can be individually and simultaneously used by different users. All hardware devices that are eligible to being assigned to a seat, are assigned to one. A device can be assigned to only one seat at a time. If a device is not assigned to any particular other seat it is implicitly assigned to the special default seat called `seat0`. Note that hardware like printers, hard disks or network cards is generally not assigned to a specific seat. They are available to all seats equally. (Well, with one exception: USB sticks can be assigned to a seat.) `seat0` always exists. # udev Rules Assignment of hardware devices to seats is managed inside the udev database, via settings on the devices: Tag `seat` When set, a device is eligible to be assigned to a seat. This tag is set for graphics devices, mice, keyboards, video cards, sound cards and more. Note that some devices like sound cards consist of multiple subdevices (i.e. a PCM for input and another one for output). This tag will be set only for the originating device, not for the individual subdevices. A UI for configuring assignment of devices to seats should enumerate and subscribe to all devices with this tag set and show them in the UI. Note that USB hubs can be assigned to a seat as well, in which case all (current and future) devices plugged into it will also be assigned to the same seat (unless they are explicitly assigned to another seat). Tag `master-of-seat` When set, this device is enough for a seat to be considered existent. This tag is usually set for the framebuffer device of graphics cards. A seat hence consists of an arbitrary number of devices marked with the `seat` tag, but (at least) one of these devices needs to be tagged with `master-of-seat` before the seat is actually considered to be around. Tag `uaccess` When set, access to this device is tied to an active seat. As the session on the seat becomes active or inactive, access to the device is updated accordingly. Tag `xaccess-*` When `xaccess-ID` is set, access to this device is granted to sessions created with `ID` listed in `ExtraDeviceAccess`. As the sessions with some `ExtraDeviceAccess` open and close, access to the device is updated accordingly. Property `ID_SEAT` This property specifies the name of the seat a specific device is assigned to. If not set the device is assigned to `seat0`. Also, to speed up enumeration of hardware belonging to a specific seat, the seat is also set as tag on the device. I.e. if the property `ID_SEAT=seat-waldo` is set for a device, the tag `seat-waldo` will be set as well. Note that if a device is assigned to `seat0`, it will usually not carry such a tag and you need to enumerate all devices and check the `ID_SEAT` property manually. Again, if a device is assigned to seat0 this is visible on the device in two ways: with a property `ID_SEAT=seat0` and with no property `ID_SEAT` set for it at all. Property `ID_AUTOSEAT` When set to `1`, this device automatically generates a new and independent seat, which is named after the path of the device. This is set for specialized USB hubs like the Pluggable devices, which when plugged in should create a hotplug seat without further configuration. Property `ID_FOR_SEAT` When creating additional (manual) seats starting from a graphics device this is a good choice to name the seat after. It is created from the path of the device. This is useful in UIs for configuring seats: as soon as you create a new seat from a graphics device, read this property and prefix it with `seat-` and use it as name for the seat. A seat exists only and exclusively because a properly tagged device with the right `ID_SEAT` property exists. Besides udev rules there is no persistent data about seats stored on disk. Note that `systemd-logind(8)` manages ACLs on a number of device classes, to allow user code to access the device nodes attached to a seat as long as the user has an active session on it. This is mostly transparent to applications. As mentioned above, for certain user software it might be a good idea to watch whether they can access device nodes instead of thinking about seats. # See Also `systemd(1)`, `sd_pid_get_session(3)`, `sd_uid_get_state(3)`, `sd_session_is_active(3)`, `sd_seat_get_active(3)`, `sd_get_seats(3)`, `sd_login_monitor_new(3)`, `sd-daemon(3)`, `pkg-config(1)` [Multi-Seat on Linux](https://www.freedesktop.org/wiki/Software/systemd/multiseat) may also be of historical interest. # sd-path systemd sd-path 3 sd-path APIs to query file system paths \#include \ pkg-config --cflags --libs libsystemd # Description `sd-path.h` is part of `libsystemd(3)` and provides APIs to query file system paths. This functionality is similar to the command-line functionality provided by `systemd-path(1)`. See `sd_path_lookup(3)` for information about the functions available. # See Also `systemd(1)`, `systemd-path(1)`, `pkg-config(1)` # sd-varlink systemd sd-varlink 3 sd-varlink APIs for Varlink IPC \#include \ pkg-config --cflags --libs libsystemd # Description `sd-varlink.h` is part of `libsystemd(3)` and provides APIs for implementing Varlink IPC clients and services. See [Varlink IPC](https://varlink.org/) for more information about Varlink IPC, as well as the [UAPI.20 Varlink IPC](https://uapi-group.org/specifications/specs/varlink/) specification. Varlink IPC uses [JSON](https://json.org/) as marshalling format. The sd-varlink API relies on the `sd-json(3)` API for JSON serialization, deserialization and manipulation. Canonical encoding rules: sd-varlink omits the `"parameters"` member on the wire in replies, errors, and notifications when there are no parameters to transmit. This reduces message size and avoids ambiguity. Receivers must be tolerant and accept any of the following encodings for the absence of parameters: an omitted `"parameters"` key (preferred), a JSON `null` value, or an empty object `{}`. When decoding, sd-varlink treats JSON `null` as if the member was omitted. The `varlinkctl(1)` tool makes the functionality implemented by sd-varlink available from the command line. # Recognizing Varlink Socket Inodes On kernels that support extended attributes on socket inodes (available since Linux 7.0), sd-varlink automatically tags the `AF_UNIX` socket inodes it creates and manages with the `user.varlink` extended attribute. The attribute records the role the socket plays in the Varlink communication, allowing other processes to discover and classify Varlink sockets, for example via `varlinkctl list-sockets` (see `varlinkctl(1)`). Four distinct roles are defined: | Attribute value | Meaning | |----|----| | `client` | Set on the connecting end of a connection, i.e. a socket created via `socket()` + `connect()`. Only for inodes on the anonymous socket file system (`sockfs`). | | `server` | Set on the serving end of a connection, i.e. a socket obtained via `accept()` on a listening socket. Only for inodes on the anonymous socket file system (`sockfs`). | | `listen` | Set on a listening socket, i.e. a socket created via `socket()` + `listen()`. Only for inodes on the anonymous socket file system (`sockfs`). | | `entrypoint` | Set on the entrypoint socket inode, i.e. the socket node bound into the regular file system that clients connect to. Unlike the other three, this attribute lives on a real file-system inode (not on `sockfs`) and is hence visible to any process that can resolve the socket path. | `user.varlink` extended attribute roles Note that for socket activated Varlink services it is recommended to set these extended attributes via `XAttrEntryPoint=`, `XAttrListen=` and `XAttrAccept=` settings on the socket units, see `systemd.socket(5)` for details. Specifically, for socket units for which `Accept=no` is set: … [Socket] SocketMode=0644 XAttrEntryPoint=user.varlink=entrypoint XAttrListen=user.varlink=listen … For socket units which have `Accept=yes`: … [Socket] Accept=yes SocketMode=0644 XAttrEntryPoint=user.varlink=entrypoint XAttrListen=user.varlink=listen XAttrAccept=user.varlink=server … Note that for Varlink sockets that shall not be world-accessible it is recommended to unset the relevant "w" bits in the socket access mode, but to keep the relevant "r" bits set. As the access check done by `connect()` looks for the "w" bits, this does not make the service unnecessarily accessible, however it has the benefit that the extended attributes that identify the socket as Varlink-related may still be read by other users (as that's restricted by the "r" bit). Or in other words, it's recommended to set `SocketMode=0644` for services that shall not be accessible to arbitrary users, rather than `SocketMode=0600`. # Directories `/usr/lib/systemd/varlink-bridges/` When `sd_varlink_connect_url()` encounters a URL with a scheme that is not natively supported, it looks for a bridge helper binary named after the URL scheme in this directory. The binary is invoked the same way as `exec:` binaries but with the full URL passed as the first command line argument. For example, if `varlinkctl introspect https://example.com/ws/sockets/io.systemd.Hostname` is called, `varlinkctl` will look for an executable `/usr/lib/systemd/varlink-bridges/https` and invoke it with `https://example.com/ws/sockets/io.systemd.Hostname` as its only argument. # See Also `systemd(1)`, `sd-event(3)`, `sd-json(3)`, `varlinkctl(1)`, `systemd.socket(5)`, `sd-bus(3)`, `pkg-config(1)` # sd_booted systemd sd_booted 3 sd_booted Test whether the system is running the systemd init system \#include \ int sd_booted void # Description `sd_booted()` checks whether the system was booted up using the systemd init system. # Return Value On failure, this call returns a negative errno-style error code. If the system was booted up with systemd as init system, this call returns a positive return value, zero otherwise. # Notes Internally, this function checks whether the directory `/run/systemd/system/` exists. A simple check like this can also be implemented trivially in shell or any other language. # See Also `systemd(1)`, `sd-daemon(3)` # sd_bus_add_match systemd sd_bus_add_match 3 sd_bus_add_match sd_bus_add_match_async sd_bus_match_signal sd_bus_match_signal_async Add a match rule for incoming message dispatching \#include \ typedef int (\* sd_bus_message_handler_t ) sd_bus_message \* m void \* userdata sd_bus_error \* ret_error int sd_bus_add_match sd_bus \* bus sd_bus_slot \*\* slot const char \* match sd_bus_message_handler_t callback void \* userdata int sd_bus_add_match_async sd_bus \* bus sd_bus_slot \*\* slot const char \* match sd_bus_message_handler_t callback sd_bus_message_handler_t install_callback void \* userdata int sd_bus_match_signal sd_bus \* bus sd_bus_slot \*\* slot const char \* sender const char \* path const char \* interface const char \* member sd_bus_message_handler_t callback void \* userdata int sd_bus_match_signal_async sd_bus \* bus sd_bus_slot \*\* slot const char \* sender const char \* path const char \* interface const char \* member sd_bus_message_handler_t callback sd_bus_message_handler_t install_callback void \* userdata # Description `sd_bus_add_match()` installs a match rule for messages received on the specified bus connection object `bus`. The syntax of the match rule expression passed in `match` is described in the [D-Bus Specification](https://dbus.freedesktop.org/doc/dbus-specification.html). The specified handler function `callback` is called for each incoming message matching the specified expression, the `userdata` parameter is passed as-is to the callback function. The match is installed synchronously when connected to a bus broker, i.e. the call sends a control message requested the match to be added to the broker and waits until the broker confirms the match has been installed successfully. `sd_bus_add_match_async()` operates very similarly to `sd_bus_add_match()`, however it installs the match asynchronously, in a non-blocking fashion: a request is sent to the broker, but the call does not wait for a response. The `install_callback` function is called when the response is later received, with the response message from the broker as parameter. If this function is specified as `NULL` a default implementation is used that terminates the bus connection should installing the match fail. `sd_bus_match_signal()` is very similar to `sd_bus_add_match()`, but only matches signals, and instead of a match expression accepts four parameters: `sender` (the service name of the sender), `path` (the object path of the emitting object), `interface` (the interface the signal belongs to), `member` (the signal name), from which the match string is internally generated. Optionally, these parameters may be specified as `NULL` in which case the relevant field of incoming signals is not tested. `sd_bus_match_signal_async()` combines the signal matching logic of `sd_bus_match_signal()` with the asynchronous behaviour of `sd_bus_add_match_async()`. On success, and if non-`NULL`, the `slot` return parameter will be set to a slot object that may be used as a reference to the installed match, and may be utilized to remove it again at a later time with `sd_bus_slot_unref(3)`. If specified as `NULL` the lifetime of the match is bound to the lifetime of the bus object itself, and the match is generally not removed independently. See `sd_bus_slot_set_floating(3)` for details. The message `m` passed to the callback is only borrowed, that is, the callback should not call `sd_bus_message_unref(3)` on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call `sd_bus_message_ref(3)` to create a new reference. If an error occurs during the callback invocation, the callback should return a negative error number (optionally, a more precise error may be returned in `ret_error`, as well). If it wants other callbacks that match the same rule to be called, it should return 0. Otherwise, it should return a positive integer. If the `bus` refers to a direct connection (i.e. not a bus connection, as set with `sd_bus_set_bus_client(3)`) the match is only installed on the client side, and the synchronous and asynchronous functions operate the same. # Return Value On success, `sd_bus_add_match()` and the other calls return 0 or a positive integer. On failure, they return a negative errno-style error code. # History `sd_bus_add_match()` and `sd_bus_message_handler_t()` were added in version 221. `sd_bus_add_match_async()`, `sd_bus_match_signal()`, and `sd_bus_match_signal_async()` were added in version 237. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_slot_unref(3)`, `sd_bus_message_ref(3)`, `sd_bus_set_bus_client(3)`, `sd_bus_slot_set_floating(3)` # sd_bus_add_node_enumerator systemd sd_bus_add_node_enumerator 3 sd_bus_add_node_enumerator Add a node enumerator for a D-Bus object path prefix \#include \ typedef int (\* sd_bus_node_enumerator_t ) sd_bus \* bus const char \* prefix void \* userdata char \*\*\* ret_nodes sd_bus_error \* ret_error int sd_bus_add_node_enumerator sd_bus \* bus sd_bus_slot \*\* slot const char \* path sd_bus_node_enumerator_t callback void \* userdata # Description `sd_bus_add_node_enumerator()` adds a D-Bus node enumerator for the given path prefix. The given callback is called to enumerate all the available objects with the given path prefix when required (e.g. when `org.freedesktop.DBus.Introspectable.Introspect` or `org.freedesktop.DBus.ObjectManager.GetManagedObjects` are called on a D-Bus service managed by sd-bus). `callback` is called with the path and userdata pointer registered with `sd_bus_add_node_enumerator()`. When called, it should store all the child object paths of the given path prefix in `ret_nodes` with a NULL terminator item. The callback should return a non-negative value on success. If an error occurs, it can either return a negative integer, set `ret_error` to a non-empty error or do both. Any errors returned by the callback are encoded as D-Bus errors and sent back to the caller. Errors in `ret_error` take priority over negative return values. Note that a node enumerator callback will only ever be called for a single path prefix and hence, for normal operation, `prefix` can be ignored. Also, a node enumerator is only used to enumerate the available child objects under a given prefix. To install a handler for a set of dynamic child objects, use `sd_bus_add_fallback_vtable(3)`. When `sd_bus_add_node_enumerator()` succeeds, a slot is created internally. If the output parameter \ is `NULL`, a "floating" slot object is created, see `sd_bus_slot_set_floating(3)`. Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot object should be dropped when the node enumerator is not needed anymore, see `sd_bus_slot_unref(3)`. # Return Value On success, `sd_bus_add_node_enumerator()` returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` One of the required parameters is `NULL` or `path` is not a valid object path. `-ENOPKG` The bus cannot be resolved. `-ECHILD` The bus was created in a different process, library or module instance. `-ENOMEM` Memory allocation failed. # History `sd_bus_node_enumerator_t()` and `sd_bus_add_node_enumerator()` were added in version 221. # See Also `sd-bus(3)`, `busctl(1)`, `sd_bus_add_fallback_vtable(3)`, `sd_bus_slot_unref(3)` # sd_bus_add_object systemd sd_bus_add_object 3 sd_bus_add_object sd_bus_add_fallback sd_bus_add_object_vtable sd_bus_add_fallback_vtable sd_bus_add_filter SD_BUS_VTABLE_CAPABILITY SD_BUS_VTABLE_START SD_BUS_VTABLE_END SD_BUS_METHOD_WITH_NAMES_OFFSET SD_BUS_METHOD_WITH_NAMES SD_BUS_METHOD_WITH_OFFSET SD_BUS_METHOD SD_BUS_SIGNAL_WITH_NAMES SD_BUS_SIGNAL SD_BUS_WRITABLE_PROPERTY SD_BUS_PROPERTY SD_BUS_PARAM Declare properties and methods for a D-Bus path \#include \ typedef int (\* sd_bus_property_get_t ) sd_bus \* bus const char \* path const char \* interface const char \* property sd_bus_message \* reply void \* userdata sd_bus_error \* ret_error typedef int (\* sd_bus_property_set_t ) sd_bus \* bus const char \* path const char \* interface const char \* property sd_bus_message \* value void \* userdata sd_bus_error \* ret_error typedef int (\* sd_bus_object_find_t ) const char \* path const char \* interface void \* userdata void \*\* ret_found sd_bus_error \* ret_error int sd_bus_add_object sd_bus \* bus sd_bus_slot \*\* slot const char \* path sd_bus_message_handler_t callback void \* userdata int sd_bus_add_fallback sd_bus \* bus sd_bus_slot \*\* slot const char \* path sd_bus_message_handler_t callback void \* userdata int sd_bus_add_object_vtable sd_bus \* bus sd_bus_slot \*\* slot const char \* path const char \* interface const sd_bus_vtable \* vtable void \* userdata int sd_bus_add_fallback_vtable sd_bus \* bus sd_bus_slot \*\* slot const char \* prefix const char \* interface const sd_bus_vtable \* vtable sd_bus_object_find_t find void \* userdata int sd_bus_add_filter sd_bus \* bus sd_bus_slot \*\* slot sd_bus_message_handler_t callback void \* userdata `SD_BUS_VTABLE_CAPABILITY(capability)` `SD_BUS_VTABLE_START(flags)` `SD_BUS_VTABLE_END` `SD_BUS_METHOD_WITH_ARGS_OFFSET(member, args, result, handler, offset, flags)` `SD_BUS_METHOD_WITH_ARGS(member, args, result, handler, flags)` `SD_BUS_METHOD_WITH_NAMES_OFFSET(member, signature, in_names, result, out_names, handler, offset, flags)` `SD_BUS_METHOD_WITH_NAMES(member, signature, in_names, result, out_names, handler, flags)` `SD_BUS_METHOD_WITH_OFFSET(member, signature, result, handler, offset, flags)` `SD_BUS_METHOD(member, signature, result, handler, flags)` `SD_BUS_SIGNAL_WITH_ARGS(member, args, flags)` `SD_BUS_SIGNAL_WITH_NAMES(member, signature, names, flags)` `SD_BUS_SIGNAL(member, signature, flags)` `SD_BUS_WRITABLE_PROPERTY(member, signature, get, set, offset, flags)` `SD_BUS_PROPERTY(member, signature, get, offset, flags)` `SD_BUS_PARAM(name)` `SD_BUS_ARGS(...)` `SD_BUS_RESULT(...)` `SD_BUS_NO_ARGS` `SD_BUS_NO_RESULT` # Description `sd_bus_add_object_vtable()` is used to declare attributes for the object path `path` connected to the bus connection `bus` under the interface `interface`. The table `vtable` may contain property declarations using `SD_BUS_PROPERTY()` or `SD_BUS_WRITABLE_PROPERTY()`, method declarations using `SD_BUS_METHOD()`, `SD_BUS_METHOD_WITH_NAMES()`, `SD_BUS_METHOD_WITH_OFFSET()`, or `SD_BUS_METHOD_WITH_NAMES_OFFSET()`, and signal declarations using `SD_BUS_SIGNAL_WITH_NAMES()` or `SD_BUS_SIGNAL()`, see below. The \ parameter contains a pointer that will be passed to various callback functions. It may be specified as `NULL` if no value is necessary. An interface can have any number of vtables attached to it. `sd_bus_add_fallback_vtable()` is similar to `sd_bus_add_object_vtable()`, but is used to register "fallback" attributes. When looking for an attribute declaration, bus object paths registered with `sd_bus_add_object_vtable()` are checked first. If no match is found, the fallback vtables are checked for each prefix of the bus object path, i.e. with the last slash-separated components successively removed. This allows the vtable to be used for an arbitrary number of dynamically created objects. Parameter \ is a function which is used to locate the target object based on the bus object path \. It must return `1` and set the `ret_found` output parameter if the object is found, return `0` if the object was not found, and return a negative errno-style error code or initialize the error structure \ on error. The pointer passed in `ret_found` will be used as the `userdata` parameter for the callback functions (offset by the `offset` offsets as specified in the vtable entries). `sd_bus_add_object()` attaches a callback directly to the object path `path`. An object path can have any number of callbacks attached to it. Each callback is prepended to the list of callbacks which are always called in order. `sd_bus_add_fallback()` is similar to `sd_bus_add_object()` but applies to fallback paths instead. `sd_bus_add_filter()` installs a callback that is invoked for each incoming D-Bus message. Filters can be used to handle logic common to all messages received by a service (e.g. authentication or authorization). When a request is received, any associated callbacks are called sequentially until a callback returns a non-zero integer. Return zero from a callback to give other callbacks the chance to process the request. Callbacks are called in the following order: first, global callbacks installed with `sd_bus_add_filter()` are called. Second, callbacks attached directly to the request object path are called, followed by any D-Bus method callbacks attached to the request object path, interface and member. Finally, the property callbacks attached to the request object path, interface and member are called. If the final callback returns zero, an error reply is sent back to the caller indicating no matching object for the request was found. Note that you can return a positive integer from a `method` callback without immediately sending a reply. This informs sd-bus this callback will take responsibility for replying to the request without forcing the callback to produce a reply immediately. This allows a callback to perform any number of asynchronous operations required to construct a reply. However, if producing a reply takes too long, the method call will time out at the caller. This is only available to methods and not properties. If a callback was invoked to handle a request that expects a reply and the callback returns a negative value, the value is interpreted as a negative errno-style error code and sent back to the caller as a D-Bus error as if `sd_bus_reply_method_errno(3)` was called. Additionally, all callbacks take a sd_bus_error output parameter that can be used to provide more detailed error information. If `ret_error` is set when the callback finishes, the corresponding D-Bus error is sent back to the caller as if `sd_bus_reply_method_error(3)` was called. Any error stored in `ret_error` takes priority over any negative values returned by the same callback when determining which error to send back to the caller. Use `sd_bus_error_set(3)` or one of its variants to set `ret_error` and return a negative integer from a callback with a single function call. To send an error reply after a callback has already finished, use `sd_bus_reply_method_errno(3)` or one of its variants. For all functions, a match slot is created internally. If the output parameter \ is `NULL`, a "floating" slot object is created, see `sd_bus_slot_set_floating(3)`. Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot object should be dropped when the vtable is not needed anymore, see `sd_bus_slot_unref(3)`. ## The sd_bus_vtable array The array consists of the structures of type sd_bus_vtable, but it should never be filled in manually, but through one of the following macros: `SD_BUS_VTABLE_START(flags)`; `SD_BUS_VTABLE_END` Those must always be the first and last element. The \ parameter can be used to set attributes that apply to the whole array; see the "Flags" section below. `SD_BUS_METHOD_WITH_ARGS_OFFSET()`; `SD_BUS_METHOD_WITH_ARGS()` Declare a D-Bus method with the name \, arguments \ and result \. \ expects a sequence of argument type/name pairs wrapped in the `SD_BUS_ARGS()` macro. The elements at even indices in this list describe the types of the method's arguments. The method's parameter signature is the concatenation of all the string literals at even indices in \. If a method has no parameters, pass `SD_BUS_NO_ARGS` to \. The elements at uneven indices describe the names of the method's arguments. \ expects a sequence of type/name pairs wrapped in the `SD_BUS_RESULT()` macro in the same format as `SD_BUS_ARGS()`. The method's result signature is the concatenation of all the string literals at even indices in \. If a method has no result, pass `SD_BUS_NO_RESULT` to \. Note that argument types are expected to be quoted string literals and argument names are expected to be unquoted string literals. See below for a complete example. The handler function \ must be of type `sd_bus_message_handler_t`. It will be called to handle the incoming messages that call this method. It receives a pointer that is the \ parameter passed to the registration function offset by \ bytes. This may be used to pass pointers to different fields in the same data structure to different methods in the same vtable. To send a reply from `handler`, call `sd_bus_reply_method_return(3)` with the message the callback was invoked with. Parameter \ is a combination of flags, see below. `SD_BUS_METHOD_WITH_ARGS()` is a shorthand for calling `SD_BUS_METHOD_WITH_ARGS_OFFSET()` with an offset of zero. `SD_BUS_METHOD_WITH_NAMES_OFFSET()`; `SD_BUS_METHOD_WITH_NAMES()`; `SD_BUS_METHOD_WITH_OFFSET()`; `SD_BUS_METHOD()` Declare a D-Bus method with the name \, parameter signature \, result signature \. Parameters \ and \ specify the argument names of the input and output arguments in the function signature. \ and \ should be created using the `SD_BUS_PARAM()` macro, see below. In all other regards, this macro behaves exactly the same as `SD_BUS_METHOD_WITH_ARGS_OFFSET()`. `SD_BUS_METHOD_WITH_NAMES()`, `SD_BUS_METHOD_WITH_OFFSET()`, and `SD_BUS_METHOD()` are variants which specify zero offset (\ parameter is passed with no change), leave the names unset (i.e. no parameter names), or both. Prefer using `SD_BUS_METHOD_WITH_ARGS_OFFSET()` and `SD_BUS_METHOD_WITH_ARGS()` over these macros as they allow specifying argument types and names next to each other which is less error-prone than first specifying all argument types followed by specifying all argument names. `SD_BUS_SIGNAL_WITH_ARGS()` Declare a D-Bus signal with the name \ and arguments \. \ expects a sequence of argument type/name pairs wrapped in the `SD_BUS_ARGS()` macro. The elements at even indices in this list describe the types of the signal's arguments. The signal's parameter signature is the concatenation of all the string literals at even indices in \. If a signal has no parameters, pass `SD_BUS_NO_ARGS` to \. The elements at uneven indices describe the names of the signal's arguments. Parameter \ is a combination of flags. See below for a complete example. `SD_BUS_SIGNAL_WITH_NAMES()`; `SD_BUS_SIGNAL()` Declare a D-Bus signal with the name \, parameter signature \, and argument names \. \ should be created using the `SD_BUS_PARAM()` macro, see below. Parameter \ is a combination of flags, see below. `SD_BUS_SIGNAL()` is equivalent to `SD_BUS_SIGNAL_WITH_NAMES()` with the \ parameter unset (i.e. no parameter names). Prefer using `SD_BUS_SIGNAL_WITH_ARGS()` over these macros as it allows specifying argument types and names next to each other which is less error-prone than first specifying all argument types followed by specifying all argument names. `SD_BUS_WRITABLE_PROPERTY()`; `SD_BUS_PROPERTY()` Declare a D-Bus property with the name \ and value signature \. Parameters \ and \ are the getter and setter methods. They are called with a pointer that is the \ parameter passed to the registration function offset by \ bytes. This may be used pass pointers to different fields in the same data structure to different setters and getters in the same vtable. Parameter \ is a combination of flags, see below. The setter and getter methods may be omitted (specified as `NULL`), if the property is one of the basic types or `as` in case of read-only properties. In those cases, the \ and \ parameters must together point to a valid variable of the corresponding type. A default setter and getter will be provided, which simply copy the argument between this variable and the message. `SD_BUS_PROPERTY()` is used to define a read-only property. `SD_BUS_PARAM()` Parameter names should be wrapped in this macro, see the example below. ## Flags The \ parameter is used to specify a combination of [D-Bus annotations](https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format). `SD_BUS_VTABLE_DEPRECATED` Mark this vtable entry as deprecated using the `org.freedesktop.DBus.Deprecated` annotation in introspection data. If specified for `SD_BUS_VTABLE_START()`, the annotation is applied to the enclosing interface. `SD_BUS_VTABLE_HIDDEN` Make this vtable entry hidden. It will not be shown in introspection data. If specified for `SD_BUS_VTABLE_START()`, all entries in the array are hidden. `SD_BUS_VTABLE_METHOD_NO_REPLY` Mark this vtable entry as a method that will not return a reply using the `org.freedesktop.DBus.Method.NoReply` annotation in introspection data. `SD_BUS_VTABLE_PROPERTY_CONST`; `SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE`; `SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION` Those three flags correspond to different values of the `org.freedesktop.DBus.Property.EmitsChangedSignal` annotation, which specifies whether the `org.freedesktop.DBus.Properties.PropertiesChanged` signal is emitted whenever the property changes. `SD_BUS_VTABLE_PROPERTY_CONST` corresponds to `const` and means that the property never changes during the lifetime of the object it belongs to, so no signal needs to be emitted. `SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE` corresponds to `true` and means that the signal is emitted. `SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION` corresponds to `invalidates` and means that the signal is emitted, but the value is not included in the signal. `SD_BUS_VTABLE_PROPERTY_EXPLICIT` Mark this vtable property entry as requiring explicit request to for the value to be shown (generally because the value is large or slow to calculate). This entry cannot be combined with `SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE`, and will not be shown in property listings by default (e.g. `busctl introspect`). This corresponds to the `org.freedesktop.systemd1.Explicit` annotation in introspection data. `SD_BUS_VTABLE_SENSITIVE` Mark this vtable method entry as processing sensitive data. When set, incoming method call messages and their outgoing reply messages are marked as sensitive using `sd_bus_message_sensitive(3)`, so that they are erased from memory when freed. `SD_BUS_VTABLE_ABSOLUTE_OFFSET` Mark this vtable method or property entry so that the user data pointer passed to its associated handler functions is determined slightly differently: instead of adding the offset parameter of the entry to the user data pointer specified during vtable registration, the offset is passed directly, converted to a pointer, without taking the user data pointer specified during vtable registration into account. `SD_BUS_VTABLE_CAPABILITY(capability)` Access to this vtable entry will be allowed if the calling process has the capability \, as described in `sd_bus_query_sender_privilege(3)`. If used for `SD_BUS_VTABLE_START()`, provides a default for all entries in the array. If not specified, either for an individual entry or the whole array, `CAP_SYS_ADMIN` is checked by default. See `capabilities(7)` for information about capabilities. Note that vtable entries may be marked as unprivileged and the whole bus may be marked as trusted, see the discussion of `SD_BUS_VTABLE_UNPRIVILEGED` below. `SD_BUS_VTABLE_UNPRIVILEGED` Mark this vtable entry as unprivileged. Access to privileged entries is limited to users with appropriate capabilities as described above. In practice many vtable entries are marked as unprivileged, and either are open to everyone, or the decision whether to allow access is taken later, e.g. by delegating to [polkit](https://www.freedesktop.org/software/polkit/docs/latest/). The whole bus may be marked as trusted, in which case annotations at the entry level are ignored, see `sd_bus_set_trusted(3)`. When *not* specified, the `org.freedesktop.systemd1.Privileged` annotation with value `true` will be shown in introspection data. `SD_BUS_VTABLE_UNPRIVILEGED` may not be applied to read-only properties, but read access (to both read-only and writable properties) is always unrestricted. Note that this page describes checks implemented in the D-Bus client. The D-Bus server has an additional policy that may permit or deny connections, see "CONFIGURATION FILE" in `dbus-daemon(1)`. # Examples
Create a simple listener on the bus
This creates a simple client on the bus (the user bus, when run as normal user). We may use the D-Bus `org.freedesktop.DBus.Introspectable.Introspect` call to acquire the XML description of the interface:
# Return Value On success, `sd_bus_add_object_vtable()` and `sd_bus_add_fallback_vtable()` return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` One of the required parameters is `NULL` or invalid. A reserved D-Bus interface was passed as the \ parameter. `-ENOPKG` The bus cannot be resolved. `-ECHILD` The bus was created in a different process, library or module instance. `-ENOMEM` Memory allocation failed. `-EPROTOTYPE` `sd_bus_add_object_vtable()` and `sd_bus_add_fallback_vtable()` have been both called for the same bus object path, which is not allowed. `-EEXIST` This vtable has already been registered for this \ and \. # History `sd_bus_property_get_t()`, `sd_bus_property_set_t()`, `sd_bus_object_find_t()`, `sd_bus_add_object()`, `sd_bus_add_fallback()`, `sd_bus_add_object_vtable()`, `sd_bus_add_fallback_vtable()`, and `sd_bus_add_filter()` were added in version 221. # See Also `sd-bus(3)`, `busctl(1)`, `sd_bus_emit_properties_changed(3)`, `sd_bus_emit_object_added(3)` # sd_bus_add_object_manager systemd sd_bus_add_object_manager 3 sd_bus_add_object_manager Add a D-Bus object manager for a D-Bus object sub-tree \#include \ int sd_bus_add_object_manager sd_bus \* bus sd_bus_slot \*\* slot const char \* path # Description `sd_bus_add_object_manager()` installs a handler for the given path that implements the `GetManagedObjects()` method of the `org.freedesktop.DBus.ObjectManager` interface. See [ org.freedesktop.DBus.ObjectManager](https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) for more information. To implement the `InterfacesAdded` and `InterfacesRemoved` signals of the `org.freedesktop.DBus.ObjectManager` interface, call `sd_bus_emit_interfaces_added(3)` and `sd_bus_emit_interfaces_removed(3)` whenever interfaces are added or removed from the sub-tree, respectively. When `sd_bus_add_object_manager()` succeeds, a slot is created internally. If the output parameter \ is `NULL`, a "floating" slot object is created, see `sd_bus_slot_set_floating(3)`. Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot object should be dropped when the object manager is not needed anymore, see `sd_bus_slot_unref(3)`. # Return Value On success, `sd_bus_add_object_manager()` returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` One of the required parameters is `NULL` or `path` is not a valid object path. `-ENOPKG` The bus cannot be resolved. `-ECHILD` The bus was created in a different process, library or module instance. `-ENOMEM` Memory allocation failed. # History `sd_bus_add_object_manager()` was added in version 221. # See Also `sd-bus(3)`, `busctl(1)`, `sd_bus_add_object_vtable(3)`, `sd_bus_emit_interfaces_added(3)`, `sd_bus_slot_unref(3)` # sd_bus_attach_event systemd sd_bus_attach_event 3 sd_bus_attach_event sd_bus_detach_event sd_bus_get_event Attach a bus connection object to an event loop \#include \ int sd_bus_attach_event sd_bus \* bus sd_event \* e int priority int sd_bus_detach_event sd_bus \* bus sd_event \* sd_bus_get_event sd_bus \* bus # Description `sd_bus_attach_event()` attaches the specified bus connection object to an `sd-event(3)` event loop object at the specified priority (see `sd_event_source_set_priority(3)` for details on event loop priorities). When a bus connection object is attached to an event loop incoming messages will be automatically read and processed, and outgoing messages written, whenever the event loop is run. When the event loop is about to terminate, the bus connection is automatically flushed and closed (see `sd_bus_set_close_on_exit(3)` for details on this). By default, bus connection objects are not attached to any event loop. When a bus connection object is attached to one it is not necessary to invoke `sd_bus_wait(3)` or `sd_bus_process(3)` as this functionality is handled automatically by the event loop. `sd_bus_detach_event()` detaches a bus object from its event loop. The `sd_bus_get_event()` returns the event loop object the specified bus object is currently attached to, or `NULL` if it is currently not attached to any. Note that `sd_bus_attach_event()` is only one of three supported ways to implement I/O event handling for bus connections. Alternatively use `sd_bus_get_fd(3)` for hooking up a bus connection object with external or manual event loops. Or use `sd_bus_wait(3)` as a simple synchronous, blocking I/O waiting call. # Return Value On success, `sd_bus_attach_event()` and `sd_bus_detach_event()` return 0 or a positive integer. On failure, they return a negative errno-style error code. `sd_bus_get_event()` returns an event loop object or `NULL`. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection has been created in a different process, library or module instance. # History `sd_bus_attach_event()`, `sd_bus_detach_event()`, and `sd_bus_get_event()` were added in version 221. # See Also `systemd(1)`, `sd-bus(3)`, `sd-event(3)`, `sd_event_source_set_priority(3)`, `sd_bus_set_close_on_exit(3)`, `sd_bus_wait(3)`, `sd_bus_get_fd(3)` # sd_bus_call systemd sd_bus_call 3 sd_bus_call sd_bus_call_async Invoke a D-Bus method call \#include \ int sd_bus_call sd_bus \* bus sd_bus_message \* m uint64_t usec sd_bus_error \* ret_error sd_bus_message \*\* reply int sd_bus_call_async sd_bus \* bus sd_bus_slot \*\* slot sd_bus_message \* m sd_bus_message_handler_t callback void \* userdata uint64_t usec # Description `sd_bus_call()` takes a complete bus message object and calls the corresponding D-Bus method. On success, the response is stored in `reply`. `usec` indicates the timeout in microseconds. If `ret_error` is not `NULL` and `sd_bus_call()` fails (either because of an internal error or because it received a D-Bus error reply), `ret_error` is initialized to an instance of sd_bus_error describing the error. `sd_bus_call_async()` is like `sd_bus_call()` but works asynchronously. The `callback` indicates the function to call when the response arrives. The `userdata` pointer will be passed to the callback function, and may be chosen freely by the caller. If `slot` is not `NULL` and `sd_bus_call_async()` succeeds, `slot` is set to a slot object which can be used to cancel the method call at a later time using `sd_bus_slot_unref(3)`. If `slot` is `NULL`, the lifetime of the method call is bound to the lifetime of the bus object itself, and it cannot be cancelled independently. See `sd_bus_slot_set_floating(3)` for details. `callback` is called when a reply arrives with the reply, `userdata` and an sd_bus_error output parameter as its arguments. Unlike `sd_bus_call()`, the sd_bus_error output parameter passed to the callback will be empty. To determine whether the method call succeeded, use `sd_bus_message_is_method_error(3)` on the reply message passed to the callback instead. If the callback returns zero and the sd_bus_error output parameter is still empty when the callback finishes, other handlers registered with functions such as `sd_bus_add_filter(3)` or `sd_bus_add_match(3)` are given a chance to process the message. If the callback returns a non-zero value or the sd_bus_error output parameter is not empty when the callback finishes, no further processing of the message is done. Generally, you want to return zero from the callback to give other registered handlers a chance to process the reply as well. (Note that the sd_bus_error parameter is an output parameter of the callback function, not an input parameter; it can be used to propagate errors from the callback handler, it will not receive any error that was received as method reply.) The message `m` passed to the callback is only borrowed, that is, the callback should not call `sd_bus_message_unref(3)` on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call `sd_bus_message_ref(3)` to create a new reference. If `usec` is zero, the default D-Bus method call timeout is used. See `sd_bus_get_method_call_timeout(3)`. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors When `sd_bus_call()` internally receives a D-Bus error reply, it will set `ret_error` if it is not `NULL`, and will return a negative value mapped from the error reply, see `sd_bus_error_get_errno(3)`. Returned errors may indicate the following problems: `-EINVAL` The input parameter `m` is `NULL`. The input parameter `m` is not a D-Bus method call. To create a new D-Bus method call, use `sd_bus_message_new_method_call(3)`. The input parameter `m` has the `BUS_MESSAGE_NO_REPLY_EXPECTED` flag set. The input parameter `error` is non-`NULL` but was not set to `SD_BUS_ERROR_NULL`. `-ECHILD` The bus connection was allocated in a parent process and is being reused in a child process after `fork()`. `-ENOTCONN` The input parameter `bus` is `NULL` or the bus is not connected. `-ECONNRESET` The bus connection was closed while waiting for the response. `-ETIMEDOUT` A response was not received within the given timeout. `-ELOOP` The message `m` is addressed to its own client. `-ENOMEM` Memory allocation failed. # History `sd_bus_call()` and `sd_bus_call_async()` were added in version 221. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_call_method(3)`, `sd_bus_call_method_async(3)`, `sd_bus_message_new_method_call(3)`, `sd_bus_message_append(3)`, `sd_bus_error(3)` # sd_bus_call_method systemd sd_bus_call_method 3 sd_bus_call_method sd_bus_call_methodv sd_bus_call_method_async sd_bus_call_method_asyncv Initialize a bus message object and invoke the corresponding D-Bus method call \#include \ int sd_bus_call_method sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member sd_bus_error \* ret_error sd_bus_message \*\* reply const char \* types ... int sd_bus_call_methodv sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member sd_bus_error \* ret_error sd_bus_message \*\* reply const char \* types va_list ap int sd_bus_call_method_async sd_bus \* bus sd_bus_slot \*\* slot const char \* destination const char \* path const char \* interface const char \* member sd_bus_message_handler_t callback void \* userdata const char \* types ... int sd_bus_call_method_asyncv sd_bus \* bus sd_bus_slot \*\* slot const char \* destination const char \* path const char \* interface const char \* member sd_bus_message_handler_t callback void \* userdata const char \* types va_list ap # Description `sd_bus_call_method()` is a convenience function for initializing a bus message object and calling the corresponding D-Bus method. It combines the `sd_bus_message_new_method_call(3)`, `sd_bus_message_append(3)` and `sd_bus_call(3)` functions into a single function call. `sd_bus_call_method_async()` is a convenience function for initializing a bus message object and calling the corresponding D-Bus method asynchronously. It combines the `sd_bus_message_new_method_call(3)`, `sd_bus_message_append(3)` and `sd_bus_call_async(3)` functions into a single function call. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors See the man pages of `sd_bus_message_new_method_call(3)`, `sd_bus_message_append(3)`, `sd_bus_call(3)` and `sd_bus_call_async(3)` for a list of possible errors. # Examples
Make a call to a D-Bus method that takes a single parameter
This defines a minimally useful program that will open a connection to the bus, call a method, wait for the reply, and finally extract and print the answer. It does error handling and proper memory management.
# History `sd_bus_call_method()`, and `sd_bus_call_method_async()` were added in version 221. `sd_bus_call_methodv()`, `sd_bus_call_method_asyncv()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_new_method_call(3)`, `sd_bus_message_append(3)`, `sd_bus_call(3)`, `sd_bus_set_property(3)`, `sd_bus_emit_signal(3)` # sd_bus_can_send systemd sd_bus_can_send 3 sd_bus_can_send Check which types can be sent over a bus object \#include \ int sd_bus_can_send sd_bus \* bus char type # Description `sd_bus_can_send()` is mostly used for checking if file descriptor passing is available on the given bus. `type` can be any of the `SD_BUS_TYPE` constants. # Return Value On failure, `sd_bus_can_send()` returns a negative errno-style error code. If values of the given type can be sent over the given bus, it returns a positive integer. Otherwise, it returns zero. ## Errors Returned errors may indicate the following problems: `-ENOPKG` The bus object `bus` could not be resolved. `-ENOTCONN` The input parameter `bus` is `NULL` or the bus is not connected. `-ECHILD` The bus object `bus` was created in a different process. # History `sd_bus_can_send()` was added in version 221. # See Also `systemd(1)`, `sd-bus(3)` # sd_bus_close systemd sd_bus_close 3 sd_bus_close sd_bus_flush sd_bus_default_flush_close Close and flush a bus connection \#include \ void sd_bus_close sd_bus \* bus int sd_bus_flush sd_bus \* bus void sd_bus_default_flush_close void # Description `sd_bus_close()` disconnects the specified bus connection. When this call is invoked and the specified bus object refers to an active connection it is immediately terminated. No further messages may be sent or received on it. Any messages queued in the bus object (both incoming and outgoing) are released. If invoked on `NULL` bus object or when the bus connection is already closed this function executes no operation. This call does not free or unreference the bus object itself. Use `sd_bus_unref(3)` for that. `sd_bus_flush()` synchronously writes out all outgoing queued message on a bus connection if there are any. This function call may block if the peer is not processing bus messages quickly. Before a program exits it is usually a good idea to flush any pending messages with `sd_bus_flush()` and then close connections with `sd_bus_close()` to ensure that no unwritten messages are lost, no further messages may be queued and all incoming but unprocessed messages are released. After both operations have been done, it is a good idea to also drop any remaining references to the bus object so that it may be freed. Since these three operations are frequently done together a helper call `sd_bus_flush_close_unref(3)` is provided that combines them into one. `sd_bus_default_flush_close()` is similar to `sd_bus_flush_close_unref()`, but does not take a bus pointer argument and instead iterates over any of the "default" buses opened by `sd_bus_default(3)`, `sd_bus_default_user(3)`, `sd_bus_default_system(3)`, and similar calls. `sd_bus_default_flush_close()` is particularly useful to clean up any buses opened using those calls before the program exits. # Return Value On success, `sd_bus_flush()` returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection has been created in a different process, library or module instance. # History `sd_bus_close()` and `sd_bus_flush()` were added in version 221. `sd_bus_default_flush_close()` was added in version 227. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_unref(3)`, `sd_bus_set_close_on_exit(3)` # sd_bus_creds_get_pid systemd sd_bus_creds_get_pid 3 sd_bus_creds_get_pid sd_bus_creds_get_pidfd_dup sd_bus_creds_get_ppid sd_bus_creds_get_tid sd_bus_creds_get_uid sd_bus_creds_get_euid sd_bus_creds_get_suid sd_bus_creds_get_fsuid sd_bus_creds_get_gid sd_bus_creds_get_egid sd_bus_creds_get_sgid sd_bus_creds_get_fsgid sd_bus_creds_get_supplementary_gids sd_bus_creds_get_comm sd_bus_creds_get_tid_comm sd_bus_creds_get_exe sd_bus_creds_get_cmdline sd_bus_creds_get_cgroup sd_bus_creds_get_unit sd_bus_creds_get_slice sd_bus_creds_get_user_unit sd_bus_creds_get_user_slice sd_bus_creds_get_session sd_bus_creds_get_owner_uid sd_bus_creds_has_effective_cap sd_bus_creds_has_permitted_cap sd_bus_creds_has_inheritable_cap sd_bus_creds_has_bounding_cap sd_bus_creds_get_selinux_context sd_bus_creds_get_audit_session_id sd_bus_creds_get_audit_login_uid sd_bus_creds_get_tty sd_bus_creds_get_unique_name sd_bus_creds_get_well_known_names sd_bus_creds_get_description Retrieve fields from a credentials object \#include \ int sd_bus_creds_get_pid sd_bus_creds \* c pid_t \* pid int sd_bus_creds_get_pidfd_dup sd_bus_creds \* c int \* ret_fd int sd_bus_creds_get_ppid sd_bus_creds \* c pid_t \* ppid int sd_bus_creds_get_tid sd_bus_creds \* c pid_t \* tid int sd_bus_creds_get_uid sd_bus_creds \* c uid_t \* uid int sd_bus_creds_get_euid sd_bus_creds \* c uid_t \* uid int sd_bus_creds_get_suid sd_bus_creds \* c uid_t \* uid int sd_bus_creds_get_fsuid sd_bus_creds \* c uid_t \* uid int sd_bus_creds_get_gid sd_bus_creds \* c gid_t \* gid int sd_bus_creds_get_egid sd_bus_creds \* c gid_t \* gid int sd_bus_creds_get_sgid sd_bus_creds \* c gid_t \* gid int sd_bus_creds_get_fsgid sd_bus_creds \* c gid_t \* gid int sd_bus_creds_get_supplementary_gids sd_bus_creds \* c const gid_t \*\* gids int sd_bus_creds_get_comm sd_bus_creds \* c const char \*\* comm int sd_bus_creds_get_tid_comm sd_bus_creds \* c const char \*\* comm int sd_bus_creds_get_exe sd_bus_creds \* c const char \*\* exe int sd_bus_creds_get_cmdline sd_bus_creds \* c char \*\*\* cmdline int sd_bus_creds_get_cgroup sd_bus_creds \* c const char \*\* cgroup int sd_bus_creds_get_unit sd_bus_creds \* c const char \*\* unit int sd_bus_creds_get_slice sd_bus_creds \* c const char \*\* slice int sd_bus_creds_get_user_unit sd_bus_creds \* c const char \*\* unit int sd_bus_creds_get_user_slice sd_bus_creds \* c const char \*\* slice int sd_bus_creds_get_session sd_bus_creds \* c const char \*\* slice int sd_bus_creds_get_owner_uid sd_bus_creds \* c uid_t \* uid int sd_bus_creds_has_effective_cap sd_bus_creds \* c int capability int sd_bus_creds_has_permitted_cap sd_bus_creds \* c int capability int sd_bus_creds_has_inheritable_cap sd_bus_creds \* c int capability int sd_bus_creds_has_bounding_cap sd_bus_creds \* c int capability int sd_bus_creds_get_selinux_context sd_bus_creds \* c const char \*\* context int sd_bus_creds_get_audit_session_id sd_bus_creds \* c uint32_t \* sessionid int sd_bus_creds_get_audit_login_uid sd_bus_creds \* c uid_t \* loginuid int sd_bus_creds_get_tty sd_bus_creds \* c const char \*\* tty int sd_bus_creds_get_unique_name sd_bus_creds \* c const char \*\* name int sd_bus_creds_get_well_known_names sd_bus_creds \* c char \*\*\* name int sd_bus_creds_get_description sd_bus_creds \* c const char \*\* name # Description These functions return credential information from an `sd_bus_creds` object. Credential objects may be created with `sd_bus_creds_new_from_pid(3)`, in which case they describe the credentials of the process identified by the specified PID, with `sd_bus_get_name_creds(3)`, in which case they describe the credentials of a bus peer identified by the specified bus name, with `sd_bus_get_owner_creds(3)`, in which case they describe the credentials of the creator of a bus, or with `sd_bus_message_get_creds(3)`, in which case they describe the credentials of the sender of the message. Not all credential fields are part of every `sd_bus_creds` object. Use `sd_bus_creds_get_mask(3)` to determine the mask of fields available. `sd_bus_creds_get_pid()` will retrieve the PID (process identifier). Similarly, `sd_bus_creds_get_ppid()` will retrieve the parent PID. Note that PID 1 has no parent process, in which case -ENXIO is returned. `sd_bus_creds_get_pidfd_dup()` will retrieve the PID file descriptor (pidfd), see `pidfd_open(2)` for details. The file descriptor is duplicated and thus must be closed by the caller. `sd_bus_creds_get_tid()` will retrieve the TID (thread identifier). `sd_bus_creds_get_uid()` will retrieve the numeric UID (user identifier). Similarly, `sd_bus_creds_get_euid()` returns the effective UID, `sd_bus_creds_get_suid()` the saved UID and `sd_bus_creds_get_fsuid()` the file system UID. `sd_bus_creds_get_gid()` will retrieve the numeric GID (group identifier). Similarly, `sd_bus_creds_get_egid()` returns the effective GID, `sd_bus_creds_get_sgid()` the saved GID and `sd_bus_creds_get_fsgid()` the file system GID. `sd_bus_creds_get_supplementary_gids()` will retrieve the supplementary GIDs list. `sd_bus_creds_get_comm()` will retrieve the comm field (truncated name of the executable, as stored in `/proc/pid/comm`). `sd_bus_creds_get_tid_comm()` will retrieve the comm field of the thread (as stored in `/proc/pid/task/tid/comm`). `sd_bus_creds_get_exe()` will retrieve the path to the program executable (as stored in the `/proc/pid/exe` link, but with the `(deleted)` suffix removed). Note that kernel threads do not have an executable path, in which case -ENXIO is returned. Note that this property should not be used for more than explanatory information, in particular it should not be used for security-relevant decisions. That's because the executable might have been replaced or removed by the time the value can be processed. Moreover, the kernel exports this information in an ambiguous way (i.e. a deleted executable cannot be safely distinguished from one whose name suffix is `(deleted)`). `sd_bus_creds_get_cmdline()` will retrieve an array of command line arguments (as stored in `/proc/pid/cmdline`). Note that kernel threads do not have a command line, in which case -ENXIO is returned. `sd_bus_creds_get_cgroup()` will retrieve the control group path. See [Control Groups v2](https://docs.kernel.org/admin-guide/cgroup-v2.html). `sd_bus_creds_get_unit()` will retrieve the systemd unit name (in the system instance of systemd) that the process is a part of. See `systemd.unit(5)`. For processes that are not part of a unit, returns -ENXIO. `sd_bus_creds_get_user_unit()` will retrieve the systemd unit name (in the user instance of systemd) that the process is a part of. See `systemd.unit(5)`. For processes that are not part of a user unit, returns -ENXIO. `sd_bus_creds_get_slice()` will retrieve the systemd slice (a unit in the system instance of systemd) that the process is a part of. See `systemd.slice(5)`. Similarly, `sd_bus_creds_get_user_slice()` retrieves the systemd slice of the process, in the user instance of systemd. `sd_bus_creds_get_session()` will retrieve the identifier of the login session that the process is a part of. Please note the login session may be limited to a stub process or two. User processes may instead be started from their systemd user manager, e.g. GUI applications started using DBus activation, as well as service processes which are shared between multiple logins of the same user. For processes that are not part of a session, returns -ENXIO. `sd_bus_creds_get_owner_uid()` will retrieve the numeric UID (user identifier) of the user who owns the user unit or login session that the process is a part of. See `systemd-logind.service(8)`. For processes that are not part of a user unit or session, returns -ENXIO. `sd_bus_creds_has_effective_cap()` will check whether the capability specified by `capability` was set in the effective capabilities mask. A positive return value means that it was set, zero means that it was not set, and a negative return value indicates an error. See `capabilities(7)` and the `AmbientCapabilities=` and `CapabilityBoundingSet=` settings in `systemd.exec(5)`. `sd_bus_creds_has_permitted_cap()` is similar to `sd_bus_creds_has_effective_cap()`, but will check the permitted capabilities mask. `sd_bus_creds_has_inheritable_cap()` is similar to `sd_bus_creds_has_effective_cap()`, but will check the inheritable capabilities mask. `sd_bus_creds_has_bounding_cap()` is similar to `sd_bus_creds_has_effective_cap()`, but will check the bounding capabilities mask. `sd_bus_creds_get_selinux_context()` will retrieve the SELinux security context (label) of the process. `sd_bus_creds_get_audit_session_id()` will retrieve the audit session identifier of the process. Returns -ENXIO for processes that are not part of an audit session. `sd_bus_creds_get_audit_login_uid()` will retrieve the audit user login identifier (the identifier of the user who is "responsible" for the session). Returns -ENXIO for processes that are not part of an audit session. `sd_bus_creds_get_tty()` will retrieve the controlling TTY, without the prefixing "/dev/". Returns -ENXIO for processes that have no controlling TTY. `sd_bus_creds_get_unique_name()` will retrieve the D-Bus unique name. See [The D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). `sd_bus_creds_get_well_known_names()` will retrieve the set of D-Bus well-known names. See [The D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). `sd_bus_creds_get_description()` will retrieve a descriptive name of the bus connection of the peer. This name is useful to discern multiple bus connections by the same peer, and may be altered by the peer with the `sd_bus_set_description(3)` call. All functions that take a `const char**` parameter will store the answer there as an address of a `NUL`-terminated string. It will be valid as long as `c` remains valid, and should not be freed or modified by the caller. All functions that take a `char***` parameter will store the answer there as an address of an array of strings. Each individual string is `NUL`-terminated, and the array is `NULL`-terminated as a whole. It will be valid as long as `c` remains valid, and should not be freed or modified by the caller. # Return Value On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENODATA` The given field is not available in the credentials object `c`. `-ENXIO` The given field is not specified for the described process or peer. This will be returned by `sd_bus_creds_get_unit()`, `sd_bus_creds_get_slice()`, `sd_bus_creds_get_user_unit()`, `sd_bus_creds_get_user_slice()`, and `sd_bus_creds_get_session()` if the process is not part of a systemd system unit, systemd user unit, systemd slice, or logind session. It will be returned by `sd_bus_creds_get_owner_uid()` if the process is not part of a systemd user unit or logind session. It will also be returned by `sd_bus_creds_get_exe()` and `sd_bus_creds_get_cmdline()` for kernel threads (since these are not started from an executable binary, nor have a command line), and by `sd_bus_creds_get_audit_session_id()` and `sd_bus_creds_get_audit_login_uid()` when the process is not part of an audit session, and `sd_bus_creds_get_tty()` if the process has no controlling TTY. `-EINVAL` Specified pointer parameter is `NULL`. `-ENOMEM` Memory allocation failed. # History `sd_bus_creds_get_pid()`, `sd_bus_creds_get_tid()`, `sd_bus_creds_get_gid()`, `sd_bus_creds_get_comm()`, `sd_bus_creds_get_tid_comm()`, `sd_bus_creds_get_exe()`, `sd_bus_creds_get_cmdline()`, `sd_bus_creds_get_cgroup()`, `sd_bus_creds_get_unit()`, `sd_bus_creds_get_user_unit()`, `sd_bus_creds_get_slice()`, `sd_bus_creds_get_session()`, `sd_bus_creds_get_owner_uid()`, `sd_bus_creds_has_effective_cap()`, `sd_bus_creds_has_permitted_cap()`, `sd_bus_creds_has_inheritable_cap()`, `sd_bus_creds_has_bounding_cap()`, `sd_bus_creds_get_selinux_context()`, `sd_bus_creds_get_audit_session_id()`, `sd_bus_creds_get_audit_login_uid()`, `sd_bus_creds_get_unique_name()`, `sd_bus_creds_get_well_known_names()`, `sd_bus_creds_get_ppid()`, `sd_bus_creds_get_uid()`, `sd_bus_creds_get_euid()`, `sd_bus_creds_get_suid()`, `sd_bus_creds_get_fsuid()`, `sd_bus_creds_get_egid()`, `sd_bus_creds_get_sgid()`, `sd_bus_creds_get_fsgid()`, `sd_bus_creds_get_supplementary_gids()`, `sd_bus_creds_get_tty()`, `sd_bus_creds_get_description()`, and `sd_bus_creds_get_user_slice()` were added in version 221. `sd_bus_creds_get_pidfd_dup()` was added in version 256. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_creds_new_from_pid(3)`, `fork(2)`, `execve(2)`, `credentials(7)`, `free(3)`, `proc(5)`, `systemd.journal-fields(7)` # sd_bus_creds_new_from_pid systemd sd_bus_creds_new_from_pid 3 sd_bus_creds_new_from_pid sd_bus_creds_new_from_pidfd sd_bus_creds_get_mask sd_bus_creds_get_augmented_mask sd_bus_creds_ref sd_bus_creds_unref sd_bus_creds_unrefp Retrieve credentials object for the specified PID \#include \ int sd_bus_creds_new_from_pid pid_t pid uint64_t creds_mask sd_bus_creds \*\* ret int sd_bus_creds_new_from_pidfd int pidfd uint64_t creds_mask sd_bus_creds \*\* ret uint64_t sd_bus_creds_get_mask sd_bus_creds \* c uint64_t sd_bus_creds_get_augmented_mask sd_bus_creds \* c sd_bus_creds \* sd_bus_creds_ref sd_bus_creds \* c sd_bus_creds \* sd_bus_creds_unref sd_bus_creds \* c void sd_bus_creds_unrefp sd_bus_creds \*\* c `SD_BUS_CREDS_PID`, `SD_BUS_CREDS_PPID`, `SD_BUS_CREDS_TID`, `SD_BUS_CREDS_UID`, `SD_BUS_CREDS_EUID`, `SD_BUS_CREDS_SUID`, `SD_BUS_CREDS_FSUID`, `SD_BUS_CREDS_GID`, `SD_BUS_CREDS_EGID`, `SD_BUS_CREDS_SGID`, `SD_BUS_CREDS_FSGID`, `SD_BUS_CREDS_SUPPLEMENTARY_GIDS`, `SD_BUS_CREDS_COMM`, `SD_BUS_CREDS_TID_COMM`, `SD_BUS_CREDS_EXE`, `SD_BUS_CREDS_CMDLINE`, `SD_BUS_CREDS_CGROUP`, `SD_BUS_CREDS_UNIT`, `SD_BUS_CREDS_SLICE`, `SD_BUS_CREDS_USER_UNIT`, `SD_BUS_CREDS_USER_SLICE`, `SD_BUS_CREDS_SESSION`, `SD_BUS_CREDS_OWNER_UID`, `SD_BUS_CREDS_EFFECTIVE_CAPS`, `SD_BUS_CREDS_PERMITTED_CAPS`, `SD_BUS_CREDS_INHERITABLE_CAPS`, `SD_BUS_CREDS_BOUNDING_CAPS`, `SD_BUS_CREDS_SELINUX_CONTEXT`, `SD_BUS_CREDS_AUDIT_SESSION_ID`, `SD_BUS_CREDS_AUDIT_LOGIN_UID`, `SD_BUS_CREDS_TTY`, `SD_BUS_CREDS_UNIQUE_NAME`, `SD_BUS_CREDS_WELL_KNOWN_NAMES`, `SD_BUS_CREDS_DESCRIPTION`, `SD_BUS_CREDS_PIDFD`, `SD_BUS_CREDS_AUGMENT`, `_SD_BUS_CREDS_ALL` # Description `sd_bus_creds_new_from_pid()` creates a new credentials object and fills it with information about the process `pid`. The pointer to this object will be stored in the `ret` pointer. Note that credential objects may also be created and retrieved via `sd_bus_get_name_creds(3)`, `sd_bus_get_owner_creds(3)` and `sd_bus_message_get_creds(3)`. `sd_bus_creds_new_from_pidfd()` is identical to `sd_bus_creds_new_from_pid()`, but takes a PID file descriptor rather than a numeric PID as reference to the process. See `pidfd_open(2)`. The information that will be stored is determined by `creds_mask`. It may contain a subset of ORed constants `SD_BUS_CREDS_PID`, `SD_BUS_CREDS_PPID`, `SD_BUS_CREDS_TID`, `SD_BUS_CREDS_UID`, `SD_BUS_CREDS_EUID`, `SD_BUS_CREDS_SUID`, `SD_BUS_CREDS_FSUID`, `SD_BUS_CREDS_GID`, `SD_BUS_CREDS_EGID`, `SD_BUS_CREDS_SGID`, `SD_BUS_CREDS_FSGID`, `SD_BUS_CREDS_SUPPLEMENTARY_GIDS`, `SD_BUS_CREDS_COMM`, `SD_BUS_CREDS_TID_COMM`, `SD_BUS_CREDS_EXE`, `SD_BUS_CREDS_CMDLINE`, `SD_BUS_CREDS_CGROUP`, `SD_BUS_CREDS_UNIT`, `SD_BUS_CREDS_SLICE`, `SD_BUS_CREDS_USER_UNIT`, `SD_BUS_CREDS_USER_SLICE`, `SD_BUS_CREDS_SESSION`, `SD_BUS_CREDS_OWNER_UID`, `SD_BUS_CREDS_EFFECTIVE_CAPS`, `SD_BUS_CREDS_PERMITTED_CAPS`, `SD_BUS_CREDS_INHERITABLE_CAPS`, `SD_BUS_CREDS_BOUNDING_CAPS`, `SD_BUS_CREDS_SELINUX_CONTEXT`, `SD_BUS_CREDS_AUDIT_SESSION_ID`, `SD_BUS_CREDS_AUDIT_LOGIN_UID`, `SD_BUS_CREDS_TTY`, `SD_BUS_CREDS_UNIQUE_NAME`, `SD_BUS_CREDS_WELL_KNOWN_NAMES`, `SD_BUS_CREDS_DESCRIPTION`, and `SD_BUS_CREDS_PIDFD`. Use the special value `_SD_BUS_CREDS_ALL` to request all supported fields. The `SD_BUS_CREDS_AUGMENT` constant may not be ORed into the mask for invocations of `sd_bus_creds_new_from_pid()` or `sd_bus_creds_new_from_pidfd()`. Fields can be retrieved from the credentials object using `sd_bus_creds_get_pid(3)` and other functions which correspond directly to the constants listed above. A mask of fields which were actually successfully retrieved can be retrieved with `sd_bus_creds_get_mask()`. If the credentials object was created with `sd_bus_creds_new_from_pid()` or `sd_bus_creds_new_from_pidfd()`, this will be a subset of fields requested in `creds_mask`. Similar to `sd_bus_creds_get_mask()`, the function `sd_bus_creds_get_augmented_mask()` returns a bitmask of field constants. The mask indicates which credential fields have been retrieved in a non-atomic fashion. For credential objects created via `sd_bus_creds_new_from_pid()` or `sd_bus_creds_new_from_pidfd()`, this mask will be identical to the mask returned by `sd_bus_creds_get_mask()`. However, for credential objects retrieved via `sd_bus_get_name_creds()`, this mask will be set for the credential fields that could not be determined atomically at peer connection time, and which were later added by reading augmenting credential data from `/proc/`. Similarly, for credential objects retrieved via `sd_bus_get_owner_creds()`, the mask is set for the fields that could not be determined atomically at bus creation time, but have been augmented. Similarly, for credential objects retrieved via `sd_bus_message_get_creds()`, the mask is set for the fields that could not be determined atomically at message sending time, but have been augmented. The mask returned by `sd_bus_creds_get_augmented_mask()` is always a subset of (or identical to) the mask returned by `sd_bus_creds_get_mask()` for the same object. The latter call hence returns all credential fields available in the credential object, the former then marks the subset of those that have been augmented. Note that augmented fields are unsuitable for authorization decisions, as they may be retrieved at different times, thus being subject to races. Hence, augmented fields should be used exclusively for informational purposes. `sd_bus_creds_ref()` creates a new reference to the credentials object `c`. This object will not be destroyed until `sd_bus_creds_unref()` has been called as many times plus once more. Once the reference count has dropped to zero, `c` cannot be used anymore, so further calls to `sd_bus_creds_ref(c)` or `sd_bus_creds_unref(c)` are illegal. `sd_bus_creds_unref()` destroys a reference to `c`. `sd_bus_creds_unrefp()` is similar to `sd_bus_creds_unref()` but takes a pointer to a pointer to an `sd_bus_creds` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). Note that this function is defined as inline function. `sd_bus_creds_ref()`, `sd_bus_creds_unref()` and `sd_bus_creds_unrefp()` execute no operation if the passed in bus credentials object is `NULL`. # Return Value On success, `sd_bus_creds_new_from_pid()` and `sd_bus_creds_new_from_pidfd()` return 0 or a positive integer. On failure, they return a negative errno-style error code. `sd_bus_creds_get_mask()` returns the mask of successfully acquired fields. `sd_bus_creds_get_augmented_mask()` returns the mask of fields that have been augmented from data in `/proc/`, and are thus not suitable for authorization decisions. `sd_bus_creds_ref()` always returns the argument. `sd_bus_creds_unref()` always returns `NULL`. # Reference ownership The functions `sd_bus_creds_new_from_pid()` and `sd_bus_creds_new_from_pidfd()` create a new object and the caller owns the sole reference. When not needed anymore, this reference should be destroyed with `sd_bus_creds_unref(3)`. ## Errors Returned errors may indicate the following problems: `-ESRCH` Specified `pid` could not be found. `-EINVAL` Specified parameter is invalid (`NULL` in case of output parameters). `-ENOMEM` Memory allocation failed. `-EOPNOTSUPP` One of the requested fields is unknown to the local system. # History `sd_bus_creds_new_from_pid()`, `sd_bus_creds_get_mask()`, `sd_bus_creds_ref()`, `sd_bus_creds_unref()`, and `sd_bus_creds_get_augmented_mask()` were added in version 221. `sd_bus_creds_unrefp()` was added in version 229. `sd_bus_creds_new_from_pidfd()` was added in version 256. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_creds_get_pid(3)`, `sd_bus_get_name_creds(3)`, `sd_bus_get_owner_creds(3)`, `sd_bus_message_get_creds(3)` # sd_bus_default systemd sd_bus_default 3 sd_bus_default sd_bus_default_user sd_bus_default_system sd_bus_open sd_bus_open_with_description sd_bus_open_user sd_bus_open_user_with_description sd_bus_open_user_machine sd_bus_open_system sd_bus_open_system_with_description sd_bus_open_system_remote sd_bus_open_system_machine Acquire a connection to a system or user bus \#include \ int sd_bus_default sd_bus \*\* bus int sd_bus_default_user sd_bus \*\* bus int sd_bus_default_system sd_bus \*\* bus int sd_bus_open sd_bus \*\* bus int sd_bus_open_with_description sd_bus \*\* bus const char \* description int sd_bus_open_user sd_bus \*\* bus int sd_bus_open_user_with_description sd_bus \*\* bus const char \* description int sd_bus_open_user_machine sd_bus \*\* bus const char \* machine int sd_bus_open_system sd_bus \*\* bus int sd_bus_open_system_with_description sd_bus \*\* bus const char \* description int sd_bus_open_system_remote sd_bus \*\* bus const char \* host int sd_bus_open_system_machine sd_bus \*\* bus const char \* machine # Description `sd_bus_default()` acquires a bus connection object to the user bus when invoked from within a user slice (any session under `user-*.slice`, e.g.: `user@1000.service`), or to the system bus otherwise. The connection object is associated with the calling thread. Each time the function is invoked from the same thread, the same object is returned, but its reference count is increased by one, as long as at least one reference is kept. When the last reference to the connection is dropped (using the `sd_bus_unref(3)` call), the connection is terminated. Note that the connection is not automatically terminated when the associated thread ends. It is important to drop the last reference to the bus connection explicitly before the thread ends, as otherwise, the connection will leak. Also, queued but unread or unwritten messages keep the bus referenced, see below. `sd_bus_default_user()` returns a user bus connection object associated with the calling thread. `sd_bus_default_system()` is similar, but connects to the system bus. Note that `sd_bus_default()` is identical to these two calls, depending on the execution context. `sd_bus_open()` creates a new, independent bus connection to the user bus when invoked in user context, or the system bus otherwise. `sd_bus_open_user()` is similar, but connects only to the user bus. `sd_bus_open_system()` does the same, but connects to the system bus. In contrast to `sd_bus_default()`, `sd_bus_default_user()`, and `sd_bus_default_system()`, these calls return new, independent connection objects that are not associated with the invoking thread and are not shared between multiple invocations. It is recommended to share connections per thread to efficiently make use the available resources. Thus, it is recommended to use `sd_bus_default()`, `sd_bus_default_user()` and `sd_bus_default_system()` to connect to the user or system buses. `sd_bus_open_with_description()`, `sd_bus_open_user_with_description()`, and `sd_bus_open_system_with_description()` are similar to `sd_bus_open()`, `sd_bus_open_user()`, and `sd_bus_open_system()`, but allow a description string to be set, see `sd_bus_set_description(3)`. `description` may be `NULL`, in which case this function is equivalent to `sd_bus_open()`. This description string is used in log messages about the bus object, and including a "name" for the bus makes them easier to understand. Some messages are emitted during bus initialization, hence using this function is preferable to setting the description later with `sd_bus_open_with_description()`. The argument is copied internally and will not be referenced after the function returns. If the `$DBUS_SESSION_BUS_ADDRESS` environment variable is set (cf. `environ(7)`), it will be used as the address of the user bus. This variable can contain multiple addresses separated by `;`. If this variable is not set, a suitable default for the default user D-Bus instance will be used. If the `$DBUS_SYSTEM_BUS_ADDRESS` environment variable is set, it will be used as the address of the system bus. This variable uses the same syntax as `$DBUS_SESSION_BUS_ADDRESS`. If this variable is not set, a suitable default for the default system D-Bus instance will be used. `sd_bus_open_system_remote()` connects to the system bus on the specified host using `ssh(1)`. `host` consists of an optional user name followed by the `@` symbol, and the hostname, optionally followed by a `:` and a port, optionally followed by a `/` and a machine name. If the machine name is given, a connection is created to the system bus in the specified container on the remote machine, and otherwise a connection to the system bus on the specified host is created. Note that entering a container is a privileged operation, and will likely only work for the root user on the remote machine. `sd_bus_open_system_machine()` connects to the system bus in the specified `machine`, where `machine` is the name of a local container, possibly prefixed by a user name and a separating `@`. If the container name is specified as the special string `.host` the connection is made to the local system. This is useful to connect to the local system bus as specific user, e.g. `foobar@.host` to connect to the local system bus as local user `foobar`. If the `@` syntax is used either the left-hand side or the right-hand side may be omitted (but not both) in which case the local user name or `.host` is implied. If the `@` syntax is not used the connection is always made as root user. See `sd_bus_set_address(3)` for a description of the address syntax, and `machinectl(1)` for more information about the "machine" concept. Note that connections into local containers are only available to privileged processes at this time. `sd_bus_open_user_machine()` is similar to `sd_bus_open_system_machine()`, but connects to the user bus of the root user, or if the `@` syntax is used, of the specified user. These calls allocate a bus connection object and initiate the connection to a well-known bus of some form. An alternative to using these high-level calls is to create an unconnected bus object with `sd_bus_new(3)` and to connect it with `sd_bus_start(3)`. # Reference ownership The functions `sd_bus_open()`, `sd_bus_open_user()`, `sd_bus_open_user_machine()`, `sd_bus_open_system()`, `sd_bus_open_system_remote()`, and `sd_bus_open_system_machine()` return a new connection object and the caller owns the sole reference. When not needed anymore, this reference should be destroyed with `sd_bus_unref(3)`. The functions `sd_bus_default()`, `sd_bus_default_user()` and `sd_bus_default_system()` do not necessarily create a new object, but increase the connection reference of an existing connection object by one. Use `sd_bus_unref(3)` to drop the reference. Queued but unwritten/unread messages keep a reference to their bus connection object. For this reason, even if an application dropped all references to a bus connection, it might not get destroyed right away. Until all incoming queued messages are read, and until all outgoing unwritten messages are written, the bus object will stay alive. `sd_bus_flush()` may be used to write all outgoing queued messages so they drop their references. To flush the unread incoming messages, use `sd_bus_close()`, which will also close the bus connection. When using the default bus logic, it is a good idea to first invoke `sd_bus_flush()` followed by `sd_bus_close()` when a thread or process terminates, and thus its bus connection object should be freed. Normally, slot objects (as created by `sd_bus_add_match(3)` and similar calls) keep a reference to their bus connection object, too. Thus, as long as a bus slot object remains referenced its bus object will remain allocated too. Optionally, bus slot objects may be placed in "floating" mode. When in floating mode the life cycle of the bus slot object is bound to the bus object, i.e. when the bus object is freed the bus slot object is automatically unreferenced too. The floating state of a slot object may be controlled explicitly with `sd_bus_slot_set_floating(3)`, though usually floating bus slot objects are created by passing `NULL` as the `slot` parameter of `sd_bus_add_match()` and related calls, thus indicating that the caller is not directly interested in referencing and managing the bus slot object. The life cycle of the default bus connection should be the responsibility of the code that creates/owns the thread the default bus connection object is associated with. Library code should neither call `sd_bus_flush()` nor `sd_bus_close()` on default bus objects unless it does so in its own private, self-allocated thread. Library code should not use the default bus object in other threads unless it is clear that the program using it will life cycle the bus connection object and flush and close it before exiting from the thread. In libraries where it is not clear that the calling program will life cycle the bus connection object, it is hence recommended to use `sd_bus_open_system()` instead of `sd_bus_default_system()` and related calls. # Return Value On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The specified parameters are invalid. `-ENOMEDIUM` The requested bus type is not available because of invalid environment (for example the user session bus is not available because `$XDG_RUNTIME_DIR` is not set). `-ENOMEM` Memory allocation failed. `-ESOCKTNOSUPPORT` The protocol version required to connect to the selected bus is not supported. In addition, other connection-related errors may be returned. See `sd_bus_send(3)`. # History `sd_bus_default()`, `sd_bus_default_user()`, `sd_bus_default_system()`, `sd_bus_open()`, `sd_bus_open_user()`, `sd_bus_open_system()`, `sd_bus_open_system_remote()`, and `sd_bus_open_system_machine()` were added in version 221. `sd_bus_open_with_description()`, `sd_bus_open_user_with_description()`, and `sd_bus_open_system_with_description()` were added in version 239. `sd_bus_open_user_machine()` was added in version 248. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_new(3)`, `sd_bus_ref(3)`, `sd_bus_unref(3)`, `sd_bus_close(3)`, `ssh(1)`, `systemd-machined.service(8)`, `machinectl(1)` # sd_bus_emit_signal systemd sd_bus_emit_signal 3 sd_bus_emit_signal sd_bus_emit_signalv sd_bus_emit_signal_to sd_bus_emit_signal_tov sd_bus_emit_interfaces_added sd_bus_emit_interfaces_added_strv sd_bus_emit_interfaces_removed sd_bus_emit_interfaces_removed_strv sd_bus_emit_properties_changed sd_bus_emit_properties_changed_strv sd_bus_emit_object_added sd_bus_emit_object_removed Convenience functions for emitting (standard) D-Bus signals \#include \ int sd_bus_emit_signal sd_bus \* bus const char \* path const char \* interface const char \* member const char \* types ... int sd_bus_emit_signalv sd_bus \* bus const char \* path const char \* interface const char \* member const char \* types va_list ap int sd_bus_emit_signal_to sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member const char \* types ... int sd_bus_emit_signal_tov sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member const char \* types va_list ap int sd_bus_emit_interfaces_added sd_bus \* bus const char \* path const char \* interface ... int sd_bus_emit_interfaces_added_strv sd_bus \* bus const char \* path char \*\* interfaces int sd_bus_emit_interfaces_removed sd_bus \* bus const char \* path const char \* interface ... int sd_bus_emit_interfaces_removed_strv sd_bus \* bus const char \* path char \*\* interfaces int sd_bus_emit_properties_changed sd_bus \* bus const char \* path const char \* interface const char \* name ... int sd_bus_emit_properties_changed_strv sd_bus \* bus const char \* path const char \* interface char \*\* names int sd_bus_emit_object_added sd_bus \* bus const char \* path int sd_bus_emit_object_removed sd_bus \* bus const char \* path # Description `sd_bus_emit_signal()` is a convenience function for initializing a bus message object and emitting the corresponding D-Bus signal. It combines the `sd_bus_message_new_signal(3)`, `sd_bus_message_append(3)` and `sd_bus_send(3)` functions into a single function call. `sd_bus_emit_signalv()` is equivalent to `sd_bus_message_append()`, except that it is called with a `va_list` instead of a variable number of arguments. `sd_bus_emit_signal_to()` and `sd_bus_emit_signal_tov()` are identical to `sd_bus_emit_signal()` and `sd_bus_emit_signalv()`, except that they can emit the signal to a single destination. Give `destination` as `NULL` to broadcast the signal. `sd_bus_emit_interfaces_added()` and `sd_bus_emit_interfaces_removed()` are used to implement the `InterfacesAdded` and `InterfacesRemoved` signals of the `org.freedesktop.DBus.ObjectManager` interface. They take a path whose interfaces have been modified as an argument and a variable list of interfaces that have been added or removed, respectively. The final argument passed to `sd_bus_emit_interfaces_added()` and `sd_bus_emit_interfaces_removed()` *must* be `NULL`. This allows both functions to safely determine the number of passed interface arguments. `sd_bus_emit_interfaces_added_strv()` and `sd_bus_emit_interfaces_removed_strv()` are identical to their respective counterparts but both take the list of interfaces as a single argument instead of a variable number of arguments. `sd_bus_emit_properties_changed()` is used to implement the `PropertiesChanged` signal of the `org.freedesktop.DBus.Properties` interface. It takes an object path, interface and a variable list of property names as its arguments. The final argument passed to `sd_bus_emit_properties_changed()` *must* be `NULL`. This allows it to safely determine the number of passed property names. `sd_bus_emit_properties_changed_strv()` is identical to `sd_bus_emit_properties_changed()` but takes the list of property names as a single argument instead of a variable number of arguments. `sd_bus_emit_object_added()` and `sd_bus_emit_object_removed()` are convenience functions for emitting the `InterfacesAdded` or `InterfacesRemoved` signals for all interfaces registered on a specific object path, respectively. This includes any parent fallback vtables if they are not overridden by a more applicable child vtable. It also includes all the standard D-Bus interfaces implemented by sd-bus itself on any registered object. Note that `sd_bus_emit_interfaces_added()`, `sd_bus_emit_interfaces_removed()`, `sd_bus_emit_object_added()` and `sd_bus_emit_object_removed()` require an object manager to have been registered on the given object path or one of its parent object paths using `sd_bus_add_object_manager(3)`. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` One of the required parameters is `NULL` or invalid. A reserved D-Bus interface was passed as the \ parameter. `-ENOPKG` The bus cannot be resolved. `-ECHILD` The bus was created in a different process, library or module instance. `-ENOMEM` Memory allocation failed. `-ESRCH` One of `sd_bus_emit_interfaces_added()`, `sd_bus_emit_interfaces_removed()`, `sd_bus_emit_object_added()` or `sd_bus_emit_object_removed()` was called on an object without an object manager registered on its own object path or one of its parent object paths. See the man pages of `sd_bus_message_new_signal(3)`, `sd_bus_message_append(3)` and `sd_bus_send(3)` for more possible errors. # History `sd_bus_emit_signal()`, `sd_bus_emit_interfaces_added()`, `sd_bus_emit_interfaces_added_strv()`, `sd_bus_emit_interfaces_removed()`, `sd_bus_emit_interfaces_removed_strv()`, `sd_bus_emit_properties_changed()`, `sd_bus_emit_properties_changed_strv()`, were added in version 221. `sd_bus_emit_object_added()`, and `sd_bus_emit_object_removed()` were added in version 222. `sd_bus_emit_signalv()` was added in version 246. `sd_bus_emit_signal_to()` and `sd_bus_emit_signal_tov()` were added in version 253. # See Also `sd-bus(3)`, `busctl(1)`, `sd_bus_message_new_signal(3)`, `sd_bus_message_append(3)`, `sd_bus_send(3)`, `sd_bus_call_method(3)` # sd_bus_enqueue_for_read systemd sd_bus_enqueue_for_read 3 sd_bus_enqueue_for_read Re-enqueue a bus message on a bus connection, for reading \#include \ int sd_bus_enqueue_for_read sd_bus \* bus sd_bus_message \* message # Description `sd_bus_enqueue_for_read()` may be used to re-enqueue an incoming bus message on the local read queue, so that it is processed and dispatched locally again, similarly to how an incoming message from the peer is processed. Takes a bus connection object and the message to enqueue. A reference is taken of the message and the caller's reference thus remains in possession of the caller. The message is enqueued at the end of the queue, thus will be dispatched after all other already queued messages are dispatched. This call is primarily useful for dealing with incoming method calls that may be processed only after an additional asynchronous operation completes. One example are PolicyKit authorization requests that are determined to be necessary to authorize a newly incoming method call: when the PolicyKit response is received the original method call may be re-enqueued to process it again, this time with the authorization result known. # Return Value On success, this function return 0 or a positive integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection has been created in a different process, library or module instance. # History `sd_bus_enqueue_for_read()` was added in version 245. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_send(3)` # sd_bus_error systemd sd_bus_error 3 sd_bus_error SD_BUS_ERROR_MAKE_CONST SD_BUS_ERROR_NULL sd_bus_error_free sd_bus_error_set sd_bus_error_setf sd_bus_error_setfv sd_bus_error_set_const sd_bus_error_set_errno sd_bus_error_set_errnof sd_bus_error_set_errnofv sd_bus_error_get_errno sd_bus_error_copy sd_bus_error_move sd_bus_error_is_set sd_bus_error_has_name sd_bus_error_has_names_sentinel sd_bus_error_has_names sd-bus error handling \#include \ typedef struct { const char \*name; const char \*message; … } sd_bus_error; `SD_BUS_ERROR_MAKE_CONST(name, message)` `SD_BUS_ERROR_NULL` void sd_bus_error_free sd_bus_error \* e int sd_bus_error_set sd_bus_error \* e const char \* name const char \* message int sd_bus_error_setf sd_bus_error \* e const char \* name const char \* format … int sd_bus_error_setfv sd_bus_error \* e const char \* name const char \* format va_list ap int sd_bus_error_set_const sd_bus_error \* e const char \* name const char \* message int sd_bus_error_set_errno sd_bus_error \* e int error int sd_bus_error_set_errnof sd_bus_error \* e int error const char \* format … int sd_bus_error_set_errnofv sd_bus_error \* e int error const char \* format va_list ap int sd_bus_error_get_errno const sd_bus_error \* e int sd_bus_error_copy sd_bus_error \* dst const sd_bus_error \* e int sd_bus_error_move sd_bus_error \* dst sd_bus_error \* e int sd_bus_error_is_set const sd_bus_error \* e int sd_bus_error_has_name const sd_bus_error \* e const char \* name int sd_bus_error_has_names_sentinel const sd_bus_error \* e ... \#define sd_bus_error_has_names(e, ...) sd_bus_error_has_names_sentinel(e, ..., NULL) # Description The sd_bus_error structure carries information about a D-Bus error condition, or lack thereof. The functions described below may be used to set and query fields in this structure. - The name field contains a short identifier of an error. It should follow the rules for error names described in the D-Bus specification, subsection [Valid D-Bus Names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names). A number of common, standardized error names are described in `sd-bus-errors(3)`, but additional domain-specific errors may be defined by applications. - The message field usually contains a human-readable string describing the details, but might be `NULL`. An unset sd_bus_error structure should have both fields initialized to `NULL`, and signifies lack of an error, i.e. success. Assign `SD_BUS_ERROR_NULL` to the structure in order to initialize both fields to `NULL`. When no longer necessary, resources held by the sd_bus_error structure should be destroyed with `sd_bus_error_free()`. `sd_bus_error_set()` sets an error structure to the specified name and message strings. The strings will be copied into internal, newly allocated memory. It is essential to free the contents again when they are not required anymore (see above). Do not use this call on error structures that have already been set. If you intend to reuse an error structure, free the old data stored in it with `sd_bus_error_free()` first. `sd_bus_error_set()` will return an `errno`-like value (see `errno(3)`) determined from the specified error name `name`. If `name` is `NULL`, it is assumed that no error occurred, and `0` is returned. If `name` is nonnull, a negative value is always returned. If `e` is `NULL`, no error structure is initialized, but `name` is still converted into an `errno`-style value. Various well-known D-Bus errors are converted to well-known `errno` counterparts, and the other ones to `-EIO`. See `sd-bus-errors(3)` for a list of well-known error names. Additional error mappings may be defined with `sd_bus_error_add_map(3)`. `sd_bus_error_set()` is designed to be conveniently used in a `return` statement. If `message` is `NULL`, no message is set. This call can fail if no memory may be allocated for the name and message strings, in which case an `SD_BUS_ERROR_NO_MEMORY` error will be set instead and `-ENOMEM` returned. `sd_bus_error_setf()` and `sd_bus_error_setfv()` are similar to `sd_bus_error_set()`, but take a `printf(3)` format string and corresponding arguments to generate the message field. `sd_bus_error_setf()` uses variadic arguments, and `sd_bus_error_setfv()` accepts the arguments as a `va_arg(3)` parameter list. `sd_bus_error_set_const()` is similar to `sd_bus_error_set()`, but the string parameters are not copied internally, and must hence remain constant and valid for the lifetime of `e`. Use this call to avoid memory allocations when setting error structures. Since this call does not allocate memory, it will not fail with an out-of-memory condition as `sd_bus_error_set()` may, as described above. Alternatively, the `SD_BUS_ERROR_MAKE_CONST()` macro may be used to generate a literal, constant bus error structure on-the-fly. `sd_bus_error_set_errno()` will immediately return `0` if the specified error parameter `error` is `0`. Otherwise, it will set name from an `errno`-like value that is converted to a D-Bus error. `strerror_r(3)` will be used to set message. Well-known D-Bus error names will be used for name if applicable, otherwise a name in the `System.Error.` namespace will be generated. The sign of the specified error number is ignored and the absolute value is used implicitly. If the specified error `error` is non-zero, the call always returns a negative value, for convenient usage in `return` statements. This call might fail due to lack of memory, in which case an `SD_BUS_ERROR_NO_MEMORY` error is set instead, and `-ENOMEM` is returned. `sd_bus_error_set_errnof()` and `sd_bus_error_set_errnofv()` are similar to `sd_bus_error_set_errno()`, but in addition to `error`, take a `printf(3)` format string and corresponding arguments. The message field will be generated from `format` and the arguments. `sd_bus_error_set_errnof()` uses variadic arguments, and `sd_bus_error_set_errnofv()` accepts the arguments as a `va_arg(3)` parameter list. `sd_bus_error_get_errno()` converts the name field of an error structure to an `errno`-like (positive) value using the same rules as `sd_bus_error_set()`. If `e` is `NULL`, `0` will be returned. `sd_bus_error_copy()` will initialize `dst` using the values in `e`, if `e` has been set with an error value before. Otherwise, it will return immediately. If the strings in `e` were set using `sd_bus_error_set_const()`, they will be shared. Otherwise, they will be copied. Before this call, `dst` must be unset, i.e. either freshly initialized with `NULL` or reset using `sd_bus_error_free()`. `sd_bus_error_copy()` generally returns `0` or a negative `errno`-like value based on the input parameter `e`: `0` if it was unset and a negative integer if it was set to some error, similarly to `sd_bus_error_set()`. It may however also return an error generated internally, for example `-ENOMEM` if a memory allocation fails. `sd_bus_error_move()` is similar to `sd_bus_error_copy()`, but will move any error information from `e` into `dst`, resetting the former. This function cannot fail, as no new memory is allocated. Note that if `e` is not set, `dst` is initialized to `SD_BUS_ERROR_NULL`. Moreover, if `dst` is `NULL` no operation is executed on it and resources held by `e` are freed and reset. Returns a converted `errno`-like, non-positive error value. `sd_bus_error_is_set()` will return a non-zero value if `e` is non-`NULL` and an error has been set, `false` otherwise. `sd_bus_error_has_name()` will return a non-zero value if `e` is non-`NULL` and an error with the same `name` has been set, `false` otherwise. `sd_bus_error_has_names_sentinel()` is similar to `sd_bus_error_has_name()`, but takes multiple names to check against. The list must be terminated with `NULL`. `sd_bus_error_has_names()` is a macro wrapper around `sd_bus_error_has_names_sentinel()` that adds the `NULL` sentinel automatically. `sd_bus_error_free()` will destroy resources held by `e`. The parameter itself will not be deallocated, and must be `free(3)`d by the caller if necessary. The function may also be called safely on unset errors (error structures with both fields set to `NULL`), in which case it performs no operation. This call will reset the error structure after freeing the data, so that all fields are set to `NULL`. The structure may be reused afterwards. # Reference ownership sd_bus_error is not reference-counted. Users should destroy resources held by it by calling `sd_bus_error_free()`. Usually, error structures are allocated on the stack or passed in as function parameters, but they may also be allocated dynamically, in which case it is the duty of the caller to `free(3)` the memory held by the structure itself after freeing its contents with `sd_bus_error_free()`. # Return Value The functions `sd_bus_error_set()`, `sd_bus_error_setf()`, and `sd_bus_error_set_const()` always return `0` when the specified error value is `NULL`, and a negative errno-like value corresponding to the `name` parameter otherwise. The functions `sd_bus_error_set_errno()`, `sd_bus_error_set_errnof()` and `sd_bus_error_set_errnofv()`, return `0` when the specified error value is `0`, and a negative errno-like value corresponding to the `error` parameter otherwise. If an error occurs internally, one of the negative error values listed below will be returned. This allows those functions to be conveniently used in a `return` statement, see the example below. `sd_bus_error_get_errno()` returns `false` when `e` is `NULL`, and a positive errno value mapped from `e->name` otherwise. `sd_bus_error_copy()` and `sd_bus_error_move()` return a negative error value converted from the source error, and zero if the error has not been set. This allows those functions to be conveniently used in a `return` statement, see the example below. `sd_bus_error_is_set()` returns a non-zero value when `e` and the name field are non-`NULL`, zero otherwise. `sd_bus_error_has_name()`, `sd_bus_error_has_names()`, and `sd_bus_error_has_names_sentinel()` return a non-zero value when `e` is non-`NULL` and the name field is equal to one of the given names, zero otherwise. ## Errors Return value may indicate the following problems in the invocation of the function itself: `-EINVAL` Error was already set in the sd_bus_error structure when one the error-setting functions was called. `-ENOMEM` Memory allocation failed. On success, `sd_bus_error_set()`, `sd_bus_error_setf()`, `sd_bus_error_set_const()`, `sd_bus_error_set_errno()`, `sd_bus_error_set_errnof()`, `sd_bus_error_set_errnofv()`, `sd_bus_error_copy()`, and `sd_bus_error_move()` will return a negative converted `errno`-style value, or `0` if the error parameter is `NULL` or unset. D-Bus errors are converted to the integral `errno`-style value, and the mapping mechanism is extensible, see the discussion above. This effectively means that almost any negative `errno`-style value can be returned. # Examples
Using the negative return value to propagate an error
# History `sd_bus_error_free()`, `sd_bus_error_set()`, `sd_bus_error_setf()`, `sd_bus_error_set_const()`, `sd_bus_error_set_errno()`, `sd_bus_error_set_errnof()`, `sd_bus_error_set_errnofv()`, `sd_bus_error_get_errno()`, `sd_bus_error_copy()`, `sd_bus_error_is_set()`, and `sd_bus_error_has_name()` were added in version 221. `sd_bus_error_move()` was added in version 240. `sd_bus_error_has_names_sentinel()` was added in version 247. `sd_bus_error_setfv()` was added in version 252. # See Also `systemd(1)`, `sd-bus(3)`, `sd-bus-errors(3)`, `sd_bus_error_add_map(3)`, `errno(3)`, `strerror_r(3)` # sd_bus_error_add_map systemd sd_bus_error_add_map 3 sd_bus_error_add_map sd_bus_error_map SD_BUS_ERROR_MAP SD_BUS_ERROR_END Additional sd-dbus error mappings \#include \ typedef struct { const char \*name; int code; … } sd_bus_error_map; SD_BUS_ERROR_MAP( name , code ) SD_BUS_ERROR_MAP_END int sd_bus_error_add_map const sd_bus_error_map \* map # Description The `sd_bus_error_add_map()` call may be used to register additional mappings for converting D-Bus errors to Linux `errno`-style errors. The mappings defined with this call are consulted by calls such as `sd_bus_error_set(3)` or `sd_bus_error_get_errno(3)`. By default, a number of generic, standardized mappings are known, as documented in `sd-bus-errors(3)`. Use this call to add further, application-specific mappings. The function takes a pointer to an array of sd_bus_error_map structures. A reference to the specified array is added to the lookup tables for error mappings. Note that the structure is not copied, and that it is hence essential that the array stays available and constant during the entire remaining runtime of the process. The mapping array should be put together with a series of `SD_BUS_ERROR_MAP()` macro invocations that take a literal name string and a (positive) `errno`-style error number. The last entry of the array should be an invocation of the `SD_BUS_ERROR_MAP_END` macro. The array should not be put together without use of these two macros. Note that the call is idempotent: it is safe to invoke it multiple times with the parameter, which will only add the passed mapping array once. Note that the memory allocated by this call is not intended to be freed during the lifetime of the process. It should not be freed explicitly. # Return Value `sd_bus_error_add_map()` returns a positive value when the new array was added to the lookup tables. It returns zero when the same array was already added before. On error, a negative `errno`-style error code is returned. See below for known error codes. ## Errors Returned errors may indicate the following problems: `-EINVAL` The specified mapping array is invalid. `-ENOMEM` Memory allocation failed. # History `sd_bus_error_add_map()` was added in version 221. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_error(3)`, `sd-bus-errors(3)`, `errno(3)`, `strerror_r(3)` # sd_bus_get_current_handler systemd sd_bus_get_current_handler 3 sd_bus_get_current_handler sd_bus_get_current_message sd_bus_get_current_slot sd_bus_get_current_userdata Query information of the callback a bus object is currently running \#include \ sd_bus_message_handler_t sd_bus_get_current_handler sd_bus \* bus sd_bus_message\* sd_bus_get_current_message sd_bus \* bus sd_bus_slot\* sd_bus_get_current_slot sd_bus \* bus void\* sd_bus_get_current_userdata sd_bus \* bus # Description Whenever sd-bus is about to invoke a user-supplied callback function, it stores the current callback, D-Bus message, slot and userdata pointer and allows these to be queried via `sd_bus_get_current_handler()`, `sd_bus_get_current_message()`, `sd_bus_get_current_slot()` and `sd_bus_get_current_userdata()`, respectively. If `bus` cannot be resolved or if execution does not reside in a user-supplied callback of `bus`, these functions return `NULL`. # Return Value On success, these functions return the requested object. On failure, they return `NULL`. # History `sd_bus_get_current_handler()`, `sd_bus_get_current_message()`, `sd_bus_get_current_slot()`, and `sd_bus_get_current_userdata()` were added in version 221. # See Also `systemd(1)`, `sd-bus(3)` # sd_bus_get_fd systemd sd_bus_get_fd 3 sd_bus_get_fd sd_bus_get_events sd_bus_get_timeout Get the file descriptor, I/O events and timeout to wait for from a message bus object \#include \ int sd_bus_get_fd sd_bus \* bus int sd_bus_get_events sd_bus \* bus int sd_bus_get_timeout sd_bus \* bus uint64_t \* timeout_usec # Description `sd_bus_get_fd()` returns the file descriptor used to communicate from a message bus object. This descriptor can be used with `poll(3)` or a similar function to wait for I/O events on the specified bus connection object. If the bus object was configured with the `sd_bus_set_fd()` function, then the `input_fd` file descriptor used in that call is returned. `sd_bus_get_events()` returns the I/O events to wait for, suitable for passing to `poll()` or a similar call. Returns a combination of `POLLIN`, `POLLOUT`, … events, or negative on error. `sd_bus_get_timeout()` returns the *absolute* timeout in μs, from which the relative timeout to pass to `poll()` (or a similar call) can be derived, when waiting for events on the specified bus connection. The returned timeout may be zero, in which case a subsequent I/O polling call should be invoked in non-blocking mode. The returned timeout may be `UINT64_MAX` in which case the I/O polling call may block indefinitely, without any applied timeout. Note that the returned timeout should be considered only a maximum sleeping time. It is permissible (and even expected) that shorter timeouts are used by the calling program, in case other event sources are polled in the same event loop. Note that the returned time-value is absolute, based of `CLOCK_MONOTONIC` and specified in microseconds. When converting this value in order to pass it as third argument to `poll()` (which expects relative milliseconds), care should be taken to convert to a relative time and use a division that rounds up to ensure the I/O polling operation does not sleep for shorter than necessary, which might result in unintended busy looping (alternatively, use `ppoll(2)` instead of plain `poll()`, which understands timeouts with nano-second granularity). These three functions are useful to hook up a bus connection object with an external or manual event loop involving `poll()` or a similar I/O polling call. Before each invocation of the I/O polling call, all three functions should be invoked: the file descriptor returned by `sd_bus_get_fd()` should be polled for the events indicated by `sd_bus_get_events()`, and the I/O call should block for that up to the timeout returned by `sd_bus_get_timeout()`. After each I/O polling call the bus connection needs to process incoming or outgoing data, by invoking `sd_bus_process(3)`. Note that these functions are only one of three supported ways to implement I/O event handling for bus connections. Alternatively use `sd_bus_attach_event(3)` to attach a bus connection to an `sd-event(3)` event loop. Or use `sd_bus_wait(3)` as a simple synchronous, blocking I/O waiting call. # Return Value On success, `sd_bus_get_fd()` returns the file descriptor used for communication. On failure, it returns a negative errno-style error code. On success, `sd_bus_get_events()` returns the I/O event mask to use for I/O event watching. On failure, it returns a negative errno-style error code. On success, `sd_bus_get_timeout()` returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An invalid bus object was passed. `-ECHILD` The bus connection was allocated in a parent process and is being reused in a child process after `fork()`. `-ENOTCONN` The bus connection has been terminated. `-EPERM` Two distinct file descriptors were passed for input and output using `sd_bus_set_fd()`, which `sd_bus_get_fd()` cannot return. `-ENOPKG` The bus cannot be resolved. # History `sd_bus_get_fd()`, `sd_bus_get_events()`, and `sd_bus_get_timeout()` were added in version 221. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_process(3)`, `sd_bus_attach_event(3)`, `sd_bus_wait(3)`, `sd_bus_set_fd(3)`, `poll(3)` # sd_bus_get_n_queued_read systemd sd_bus_get_n_queued_read 3 sd_bus_get_n_queued_read sd_bus_get_n_queued_write Get the number of pending bus messages in the read and write queues of a bus connection object \#include \ int sd_bus_get_n_queued_read sd_bus \* bus uint64_t \* ret int sd_bus_get_n_queued_write sd_bus \* bus uint64_t \* ret # Description `sd_bus_get_n_queued_read()` may be used to query the number of bus messages in the read queue of a bus connection object. The read queue contains all messages read from the transport medium (e.g. network socket) but not yet processed locally. The function expects two arguments: the bus object to query, and a pointer to a 64-bit counter variable to write the current queue size to. Use `sd_bus_process()` in order to process queued messages, i.e. to reduce the size of the read queue (as well as, in fact, the write queue, see below). Similarly, `sd_bus_get_n_queued_write()` may be used to query the number of currently pending bus messages in the write queue of a bus connection object. The write queue contains all messages enqueued into the connection with a call such as `sd_bus_send()` but not yet written to the transport medium. The expected arguments are similar to `sd_bus_get_n_queued_read()`. Here too, use `sd_bus_process()` to reduce the size of the write queue. Alternatively, use `sd_bus_flush()` to synchronously write out any pending bus messages until the write queue is empty. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection was created in a different process, library or module instance. # History `sd_bus_get_n_queued_read()` and `sd_bus_get_n_queued_write()` were added in version 238. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_process(3)`, `sd_bus_send(3)`, `sd_bus_flush(3)` # sd_bus_get_name_creds systemd sd_bus_get_name_creds 3 sd_bus_get_name_creds sd_bus_get_owner_creds Query bus client credentials \#include \ int sd_bus_get_name_creds sd_bus \* bus const char \* name uint64_t mask sd_bus_creds \*\* creds int sd_bus_get_owner_creds sd_bus \* bus uint64_t mask sd_bus_creds \*\* creds # Description `sd_bus_get_name_creds()` queries the credentials of the bus client identified by `name`. The `mask` parameter is a combo of `SD_BUS_CREDS_*` flags that indicate which credential info the caller is interested in. See `sd_bus_creds_new_from_pid(3)` for a list of possible flags. On success, `creds` contains a new sd_bus_creds instance with the requested information. Ownership of this instance belongs to the caller and it should be freed once no longer needed by calling `sd_bus_creds_unref(3)`. `sd_bus_get_owner_creds()` queries the credentials of the creator of the given bus. The `mask` and `creds` parameters behave the same as in `sd_bus_get_name_creds()`. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. `-ENOPKG` The bus cannot be resolved. `-EPERM` The bus has already been started. `-ECHILD` The bus was created in a different process, library or module instance. `-ENOMEM` Memory allocation failed. # History `sd_bus_get_name_creds()` and `sd_bus_get_owner_creds()` were added in version 221. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_creds_unref(3)` # sd_bus_get_name_machine_id systemd sd_bus_get_name_machine_id 3 sd_bus_get_name_machine_id Retrieve a bus client's machine identity \#include \ int sd_bus_get_name_machine_id sd_bus \* bus const char \* name sd_id128_t \* machine # Description `sd_bus_get_name_machine_id()` retrieves the D-Bus machine identity of the machine that the bus client identified by `name` is running on. Internally, it calls the `GetMachineId` method of the `org.freedesktop.DBus.Peer` interface. The D-Bus machine identity is a 128-bit UUID. On Linux systems running systemd, this corresponds to the contents of `/etc/machine-id`. On success, the machine identity is stored in `machine`. # Return Value On success, this function returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. `-ENOPKG` The bus cannot be resolved. `-ECHILD` The bus was created in a different process, library or module instance. `-ENOMEM` Memory allocation failed. # History `sd_bus_get_name_machine_id()` was added in version 221. # See Also `systemd(1)`, `sd-bus(3)` # sd_bus_interface_name_is_valid systemd sd_bus_interface_name_is_valid 3 sd_bus_interface_name_is_valid sd_bus_service_name_is_valid sd_bus_member_name_is_valid sd_bus_object_path_is_valid Check if a string is a valid bus name or object path \#include \ int sd_bus_interface_name_is_valid const char\* p int sd_bus_service_name_is_valid const char\* p int sd_bus_member_name_is_valid const char\* p int sd_bus_object_path_is_valid const char\* p # Description `sd_bus_interface_name_is_valid()` checks if a given string `p` is a syntactically valid bus interface name. Similarly, `sd_bus_service_name_is_valid()` checks if the argument is a valid bus service name, `sd_bus_member_name_is_valid()` checks if the argument is a valid bus interface member name, and `sd_bus_object_path_is_valid()` checks if the argument is a valid bus object path. Those functions generally check that only allowed characters are used and that the length of the string is within limits. # Return Value Those functions return 1 if the argument is a valid interface / service / member name or object path, and 0 if it is not. If the argument is `NULL`, an error is returned. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `p` parameter is `NULL`. # History `sd_bus_interface_name_is_valid()`, `sd_bus_service_name_is_valid()`, `sd_bus_member_name_is_valid()`, and `sd_bus_object_path_is_valid()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_call_method(3)` # sd_bus_is_open systemd sd_bus_is_open 3 sd_bus_is_open sd_bus_is_ready Check whether the bus connection is open or ready \#include \ int sd_bus_is_open sd_bus \* bus int sd_bus_is_ready sd_bus \* bus # Description `sd_bus_is_open()` checks whether the specified bus connection is open, i.e. in the process of being established, already established or in the process of being torn down. It returns zero when the connection has not been started yet (i.e. `sd_bus_start(3)` or some equivalent call has not been invoked yet), or is fully terminated again (for example after `sd_bus_close(3)`), it returns positive otherwise. `sd_bus_is_ready()` checks whether the specified connection is fully established, i.e. completed the connection and authentication phases of the protocol and received the `Hello()` method call response, and is not in the process of being torn down again. It returns zero outside of this state, and positive otherwise. Effectively, this function returns positive while regular messages can be sent or received on the connection. The `bus` argument may be `NULL`, zero is also returned in that case. To be notified when the connection is fully established, use `sd_bus_set_connected_signal(3)` and install a match for the `Connected()` signal on the `org.freedesktop.DBus.Local` interface. To be notified when the connection is torn down again, install a match for the `Disconnected()` signal on the `org.freedesktop.DBus.Local` interface. # Return Value Those functions return 0 if the bus is *not* in the given state, and a positive integer when it is. On failure, a negative errno-style error code is returned. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection has been created in a different process, library or module instance. # History `sd_bus_is_open()` was added in version 221. `sd_bus_is_ready()` was added in version 237. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_start(3)`, `sd_bus_close(3)`, `sd_bus_set_connected_signal(3)` # sd_bus_list_names systemd sd_bus_list_names 3 sd_bus_list_names Retrieve information about registered names on a bus \#include \ int sd_bus_list_names sd_bus \* bus char \*\*\* acquired char \*\*\* activatable # Description `sd_bus_list_names()` retrieves information about the registered names on a bus. If `acquired` is not `NULL`, this function calls [ org.freedesktop.DBus.ListNames](https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-list-names) to retrieve the list of currently-owned names on the bus. If `activatable` is not `NULL`, the function calls [ org.freedesktop.DBus.ListActivatableNames](https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-list-activatable-names) to retrieve the list of all names on the bus that can be activated. Note that ownership of the arrays returned by `sd_bus_list_names()` in `acquired` and `activatable` is transferred to the caller and hence, the caller is responsible for freeing these arrays and their contents. # Return Value On success, `sd_bus_list_names()` returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `bus` or both `acquired` and `activatable` were `NULL`. `-ENOPKG` The bus cannot be resolved. `-ECHILD` The bus was created in a different process, library or module instance. `-ENOMEM` Memory allocation failed. `-ENOTCONN` The bus is not connected. # History `sd_bus_list_names()` was added in version 221. # See Also `systemd(1)`, `sd-bus(3)` # sd_bus_message_append systemd sd_bus_message_append 3 sd_bus_message_append sd_bus_message_appendv Attach fields to a D-Bus message based on a type string \#include \ int sd_bus_message_append sd_bus_message \* m const char \* types … int sd_bus_message_appendv sd_bus_message \* m const char \* types va_list ap # Description The `sd_bus_message_append()` function appends a sequence of fields to the D-Bus message object `m`. The type string `types` describes the types of the field arguments that follow. For each type specified in the type string, one or more arguments need to be specified, in the same order as declared in the type string. The type string is composed of the elements shown in the table below. It contains zero or more single "complete types". Each complete type may be one of the basic types or a fully described container type. A container type may be a structure with the contained types, a variant, an array with its element type, or a dictionary entry with the contained types. The type string is `NUL`-terminated. In case of a basic type, one argument of the corresponding type is expected. A structure is denoted by a sequence of complete types between `(` and `)`. This sequence cannot be empty — it must contain at least one type. Arguments corresponding to this nested sequence follow the same rules as if they were not nested. A variant is denoted by `v`. Corresponding arguments must begin with a type string denoting a complete type, and following that, arguments corresponding to the specified type. An array is denoted by `a` followed by a complete type. Corresponding arguments must begin with the number of entries in the array, followed by the entries themselves, matching the element type of the array. A dictionary is an array of dictionary entries, denoted by `a` followed by a pair of complete types between `{` and `}`. The first of those types must be a basic type. Corresponding arguments must begin with the number of dictionary entries, followed by a pair of values for each entry matching the element type of the dictionary entries. `sd_bus_message_appendv()` is equivalent to `sd_bus_message_append()`, except that it is called with a `va_list` instead of a variable number of arguments. This function does not call the `va_end()` macro. Because it invokes the `va_arg()` macro, the value of `ap` is undefined after the call. For further details on the D-Bus type system, please consult the [D-Bus Specification](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system).
Item type specifiers
a SD_BUS_TYPE_ARRAY array determined by array type and size int, followed by array contents
v SD_BUS_TYPE_VARIANT variant determined by the type argument signature string, followed by variant contents
( SD_BUS_TYPE_STRUCT_BEGIN array start determined by the nested types structure contents
) SD_BUS_TYPE_STRUCT_END array end
{ SD_BUS_TYPE_DICT_ENTRY_BEGIN dictionary entry start determined by the nested types dictionary contents
} SD_BUS_TYPE_DICT_ENTRY_END dictionary entry end
For types `s` and `g` (unicode string or signature), the pointer may be `NULL`, which is equivalent to an empty string. For `h` (UNIX file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession of the caller. See `sd_bus_message_append_basic(3)` for the precise interpretation of those and other types. # Types String Grammar types ::= complete_type* complete_type ::= basic_type | variant | structure | array | dictionary basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" | "b" | "h" | "s" | "o" | "g" variant ::= "v" structure ::= "(" complete_type+ ")" array ::= "a" complete_type dictionary ::= "a" "{" basic_type complete_type "}" # Examples Append a single basic type (the string `a string`): sd_bus_message *m; … sd_bus_message_append(m, "s", "a string"); Append all types of integers: uint8_t y = 1; int16_t n = 2; uint16_t q = 3; int32_t i = 4; uint32_t u = 5; int32_t x = 6; uint32_t t = 7; double d = 8.0; sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d); Append a structure composed of a string and a D-Bus path: sd_bus_message_append(m, "(so)", "a string", "/a/path"); Append an array of UNIX file descriptors: sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO); Append a variant, with the real type "g" (signature), and value "sdbusisgood": sd_bus_message_append(m, "v", "g", "sdbusisgood"); Append a dictionary containing the mapping {1=\>"a", 2=\>"b", 3=\>""}: sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL); # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_append_basic(3)`, `sd_bus_message_append_array(3)`, `sd_bus_message_open_container(3)` # sd_bus_message_append_array systemd sd_bus_message_append_array 3 sd_bus_message_append_array sd_bus_message_append_array_memfd sd_bus_message_append_array_iovec sd_bus_message_append_array_space Append an array of fields to a D-Bus message \#include \ int sd_bus_message_append_array sd_bus_message \* m char type const void \* ptr size_t size int sd_bus_message_append_array_memfd sd_bus_message \* m char type int memfd uint64_t offset uint64_t size int sd_bus_message_append_array_iovec sd_bus_message \* m char type const struct iovec \* iov unsigned n int sd_bus_message_append_array_space sd_bus_message \* m char type size_t size void \*\* ptr # Description The `sd_bus_message_append_array()` function appends an array to a D-Bus message `m`. A container will be opened, the array contents appended, and the container closed. The parameter `type` determines how the pointer `p` is interpreted. `type` must be one of the "trivial" types `y`, `n`, `q`, `i`, `u`, `x`, `t`, `d` (but not `b`), as defined by the [Basic D-Bus Types](https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types) section of the D-Bus specification, and listed in `sd_bus_message_append_basic(3)`. Pointer `p` must point to an array of size `size` bytes containing items of the respective type. Size `size` must be a multiple of the size of the type `type`. As a special case, `p` may be `NULL`, if `size` is 0. The memory pointed to by `p` is copied into the memory area containing the message and stays in possession of the caller. The caller may hence freely change the data after this call without affecting the message the array was appended to. The `sd_bus_message_append_array_memfd()` function appends an array of a trivial type to message `m`, similar to `sd_bus_message_append_array()`. The contents of the memory file descriptor `memfd` starting at the specified offset and of the specified size is used as the contents of the array. The offset and size must be a multiple of the size of the type `type`. However, as a special exception, if the offset is specified as zero and the size specified as UINT64_MAX the full memory file descriptor contents is used. The memory file descriptor is sealed by this call if it has not been sealed yet, and cannot be modified after this call. See `memfd_create(2)` for details about memory file descriptors. Appending arrays with memory file descriptors enables efficient zero-copy data transfer, as the memory file descriptor may be passed as-is to the destination, without copying the memory in it to the destination process. Not all protocol transports support passing memory file descriptors between participants, in which case this call will automatically fall back to copying. Also, as memory file descriptor passing is inefficient for smaller amounts of data, copying might still be enforced even where memory file descriptor passing is supported. The `sd_bus_message_append_array_iovec()` function appends an array of a trivial type to the message `m`, similar to `sd_bus_message_append_array()`. Contents of the I/O vector array `iov` are used as the contents of the array. The total size of `iov` payload (the sum of iov_len fields) must be a multiple of the size of the type `type`. The `iov` argument must point to `n` I/O vector structures. Each structure may have the iov_base field set, in which case the memory pointed to will be copied into the message, or unset (set to zero), in which case a block of zeros of length iov_len bytes will be inserted. The memory pointed at by `iov` may be changed after this call. The `sd_bus_message_append_array_space()` function appends space for an array of a trivial type to message `m`. It behaves the same as `sd_bus_message_append_array()`, but instead of copying items to the message, it returns a pointer to the destination area to the caller in pointer `p`. The caller should subsequently write the array contents to this memory. Modifications to the memory pointed to should only occur until the next operation on the bus message is invoked. Most importantly, the memory should not be altered anymore when another field has been added to the message or the message has been sealed. # Return Value On success, these calls return 0 or a positive integer. On failure, they return a negative errno-style error code. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_append(3)`, `sd_bus_message_append_basic(3)`, `memfd_create(2)`, [The D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html) # sd_bus_message_append_basic systemd sd_bus_message_append_basic 3 sd_bus_message_append_basic Attach a single field to a message \#include \ int sd_bus_message_append_basic sd_bus_message \* m char type const void \* p # Description `sd_bus_message_append_basic()` appends a single field to the message `m`. The parameter `type` determines how the pointer `p` is interpreted. `type` must be one of the basic types as defined by the [Basic Types](https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types) section of the D-Bus specification, and listed in the table below. | Specifier | Constant | Description | Size | Expected C Type | |----|----|----|----|----| | `y` | `SD_BUS_TYPE_BYTE` | unsigned integer | 1 byte | uint8_t | | `b` | `SD_BUS_TYPE_BOOLEAN` | boolean | 4 bytes | int | | `n` | `SD_BUS_TYPE_INT16` | signed integer | 2 bytes | int16_t | | `q` | `SD_BUS_TYPE_UINT16` | unsigned integer | 2 bytes | uint16_t | | `i` | `SD_BUS_TYPE_INT32` | signed integer | 4 bytes | int32_t | | `u` | `SD_BUS_TYPE_UINT32` | unsigned integer | 4 bytes | uint32_t | | `x` | `SD_BUS_TYPE_INT64` | signed integer | 8 bytes | int64_t | | `t` | `SD_BUS_TYPE_UINT64` | unsigned integer | 8 bytes | uint64_t | | `d` | `SD_BUS_TYPE_DOUBLE` | floating-point | 8 bytes | double | | `s` | `SD_BUS_TYPE_STRING` | Unicode string | variable | char\[\] | | `o` | `SD_BUS_TYPE_OBJECT_PATH` | object path | variable | char\[\] | | `g` | `SD_BUS_TYPE_SIGNATURE` | signature | variable | char\[\] | | `h` | `SD_BUS_TYPE_UNIX_FD` | UNIX file descriptor | 4 bytes | int | Item type specifiers {#format-specifiers} The value of the parameter is copied into a memory area held by the message object, stays in the possession of the caller and may hence be freely changed after this call without affecting the bus message it has been added to. If `type` is `h` (UNIX file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession of the caller. For types `s`, `o`, and `g`, the parameter `p` is interpreted as a pointer to a `NUL`-terminated character sequence. As a special case, a `NULL` pointer is interpreted as an empty string. The string should be valid Unicode string encoded as UTF-8. In case of the two latter types, the additional requirements for a D-Bus object path or type signature should be satisfied. Those requirements should be verified by the recipient of the message. # Return Value On success, this call returns 0 or a positive integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` Specified parameter is invalid. `-EPERM` Message has been sealed. `-ESTALE` Message is in invalid state. `-ENXIO` Message cannot be appended to. `-ENOMEM` Memory allocation failed. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_read_basic(3)`, `sd_bus_message_append(3)`, [The D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html) # sd_bus_message_append_string_memfd systemd sd_bus_message_append_string_memfd 3 sd_bus_message_append_string_memfd sd_bus_message_append_string_iovec sd_bus_message_append_string_space Attach a string to a message \#include \ int sd_bus_message_append_string_memfd sd_bus_message \* m int memfd uint64_t offset uint64_t size int sd_bus_message_append_string_iovec sd_bus_message \* m const struct iovec \* iov unsigned n int sd_bus_message_append_string_space sd_bus_message \* m size_t size char \*\* ret # Description The functions `sd_bus_message_append_string_memfd()` and `sd_bus_message_append_string_iovec()` can be used to append a single string (item of type `s`) to message `m`. In case of `sd_bus_message_append_string_memfd()`, the contents of `memfd` starting at the specified `offset` and of the specified `size` are used as the string. `size` must include the terminating `NUL` byte, i.e. the resulting string has length `size` - 1. If `offset` is zero and `size` is `UINT64_MAX`, the full contents of the memory file descriptor are used, and hence must themselves end in a `NUL` byte. If `offset` plus `size` exceeds the actual size of the memory file descriptor, this call fails with `-EMSGSIZE`. The memory file descriptor is sealed by this call if it has not been sealed yet, and cannot be modified after this call. The appended contents must satisfy the same constraints as described for the `s` type in `sd_bus_message_append_basic(3)`. In case of `sd_bus_message_append_string_iovec()`, the payload of `iov` is the string. It must satisfy the same constraints as described for the `s` type in `sd_bus_message_append_basic(3)`. The `iov` argument must point to `n` struct iovec structures. Each structure may have the iov_base field set, in which case the memory pointed to will be copied into the message, or unset, in which case a block of spaces (ASCII 32) of length iov_len will be inserted. The memory pointed at by `iov` may be changed after this call. The `sd_bus_message_append_string_space()` function appends space for a string to message `m`. It behaves similar to `sd_bus_message_append_basic()` with type `s`, but instead of copying a string into the message, it returns a pointer to the destination area to the caller in pointer `ret`. Space for the string of length `size` plus the terminating `NUL` is allocated. # Return Value On success, those calls return 0 or a positive integer. On failure, they return a negative errno-style error code. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_append_basic(3)`, [The D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html) # sd_bus_message_append_strv systemd sd_bus_message_append_strv 3 sd_bus_message_append_strv Attach an array of strings to a message \#include \ int sd_bus_message_append_strv sd_bus_message \* m char \*\* l # Description The `sd_bus_message_append()` function can be used to append an array of strings to message `m`. The parameter `l` shall point to a `NULL`-terminated array of pointers to `NUL`-terminated strings. Each string must satisfy the same constraints as described for the `s` type in `sd_bus_message_append_basic(3)`. The memory pointed at by `p` and the contents of the strings themselves are copied into the memory area containing the message and may be changed after this call. Note that the signature of `l` parameter is to be treated as `const char *const *`, and the contents will not be modified. # Return Value On success, this call returns 0 or a positive integer. On failure, a negative errno-style error code is returned. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_append(3)`, `sd_bus_message_append_array(3)`, [The D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html) # sd_bus_message_at_end systemd sd_bus_message_at_end 3 sd_bus_message_at_end Check if a message has been fully read \#include \ int sd_bus_message_at_end sd_bus_message \* m int complete # Description `sd_bus_message_at_end()` returns whether all data from the currently opened container in `m` or all data from all containers in `m` has been read. If `complete` is zero, this function returns whether all data from the currently opened container has been read. If `complete` is non-zero, this function returns whether all data from all containers in `m` has been read. # Return Value If all data from all containers or the current container (depending on the value of `complete`) has been read, `sd_bus_message_at_end()` returns a positive integer. If there is still data left to be read, it returns zero. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `m` parameter is `NULL`. `-EPERM` The message is not sealed. # History `sd_bus_message_at_end()` was added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_read(3)` # sd_bus_message_copy systemd sd_bus_message_copy 3 sd_bus_message_copy Copy the contents of one message to another \#include \ int sd_bus_message_copy sd_bus_message \* m sd_bus_message \* source int all # Description `sd_bus_message_copy()` copies the contents from message `source` to `m`. If `all` is false, a single complete type is copied (basic or container). If `all` is true, the contents are copied until the end of the currently open container or the end of `source`. # Return Value On success, this call returns true if anything was copied, and false if there was nothing to copy. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `source` or `m` are `NULL`. `-EPERM` Message `m` has been sealed or `source` has *not* been sealed. `-ESTALE` Destination message is in invalid state. `-ENXIO` Destination message cannot be appended to. `-ENOMEM` Memory allocation failed. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_append(3)` # sd_bus_message_dump systemd sd_bus_message_dump 3 sd_bus_message_dump sd_bus_message_dump_json Produce a string representation of a message for debugging purposes \#include \ int sd_bus_message_dump sd_bus_message \* m FILE \* f uint64_t flags int sd_bus_message_dump_json sd_bus_message \* m uint64_t flags sd_json_variant \*\* ret # Description The `sd_bus_message_dump()` function writes a textual representation of the message `m` to the stream `f`. If `f` is `NULL`, standard output (`stdio`) will be used. This function is intended to be used for debugging purposes, and the output is neither stable nor designed to be machine readable. The `sd_bus_message_dump_json()` function converts the DBus message `m` to a JSON variant and stores it in `ret`. The caller should call `sd_json_variant_unref()` for the acquired JSON variant after use. Unlike `sd_bus_message_dump()`, the function itself does not print anything. To print the DBus message in the JSON format, please pass the returned JSON variant to `sd_json_variant_dump()`. The `flags` parameter may be used to modify the output, and is a combination of zero or more of the following flags: `SD_BUS_MESSAGE_DUMP_WITH_HEADER` The header of the message that specifies the message type, flags, and several more additional metadata will be printed or included in the resulting JSON object. `SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY` Only the current container will be printed or converted. When the flag is *not* specified, the contents of the whole message will be printed or converted. Note that these functions move the read pointer of the message. It may be necessary to reset the position afterwards, for example with `sd_bus_message_rewind(3)`. # Examples Output for a signal message (with `SD_BUS_MESSAGE_DUMP_WITH_HEADER`): ‣ Type=signal Endian=l Flags=1 Version=1 Cookie=22 Path=/value/a Interface=org.freedesktop.DBus.Properties Member=PropertiesChanged MESSAGE "sa{sv}as" { STRING "org.freedesktop.systemd.ValueTest"; ARRAY "{sv}" { DICT_ENTRY "sv" { STRING "Value"; VARIANT "s" { STRING "object 0x1e, path /value/a"; }; }; }; ARRAY "s" { STRING "Value2"; STRING "AnExplicitProperty"; }; }; # Return Value On success, this function returns 0 or a positive integer. On failure, it returns a negative errno-style error code. No error codes are currently defined. # See Also `systemd(1)`, `sd-bus(3)`, `sd-json(3)` # sd_bus_message_get_cookie systemd sd_bus_message_get_cookie 3 sd_bus_message_get_cookie sd_bus_message_get_reply_cookie Return the transaction cookie of a message \#include \ int sd_bus_message_get_cookie sd_bus_message \* message uint64_t \* cookie int sd_bus_message_get_reply_cookie sd_bus_message \* message uint64_t \* cookie # Description `sd_bus_message_get_cookie()` returns the transaction cookie of a message. The cookie uniquely identifies a message within each bus peer, but is not globally unique. It is assigned when a message is sent. `sd_bus_message_get_reply_cookie()` returns the transaction cookie of the message the specified message is a response to. When a reply message is generated for a method call message, its cookie is copied over into this field. Note that while every message that is transferred is identified by a cookie, only response messages carry a reply cookie field. Both functions take a message object as first parameter and a place to store the 64-bit cookie in. # Return Value On success, these calls return 0 or a positive integer. On failure, they return a negative errno-style error code. On success, the cookie/reply cookie is returned in the specified 64-bit unsigned integer variable. ## Errors Returned errors may indicate the following problems: `-EINVAL` A specified parameter is invalid. `-ENODATA` No cookie has been assigned to this message. This either indicates that the message has not been sent yet and hence has no cookie assigned, or that the message is not a method response message and hence does not carry a reply cookie field. # History `sd_bus_message_get_cookie()` and `sd_bus_message_get_reply_cookie()` were added in version 209. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_new(3)` # sd_bus_message_get_monotonic_usec systemd sd_bus_message_get_monotonic_usec 3 sd_bus_message_get_monotonic_usec sd_bus_message_get_realtime_usec sd_bus_message_get_seqnum Retrieve the sender timestamps and sequence number of a message \#include \ int sd_bus_message_get_monotonic_usec sd_bus_message \* message uint64_t \* usec int sd_bus_message_get_realtime_usec sd_bus_message \* message uint64_t \* usec int sd_bus_message_get_seqnum sd_bus_message \* message uint64_t \* seqnum # Description `sd_bus_message_get_monotonic_usec()` returns the monotonic timestamp of the time the message was sent. This value is in microseconds since the `CLOCK_MONOTONIC` epoch, see `clock_gettime(2)` for details. Similarly, `sd_bus_message_get_realtime_usec()` returns the realtime (wallclock) timestamp of the time the message was sent. This value is in microseconds since Jan 1st, 1970, i.e. in the `CLOCK_REALTIME` clock. `sd_bus_message_get_seqnum()` returns the kernel-assigned sequence number of the message. The kernel assigns a global, monotonically increasing sequence number to all messages transmitted on the local system, at the time the message was sent. This sequence number is useful for determining message send order, even across different buses of the local system. The sequence number combined with the boot ID of the system (as returned by `sd_id128_get_boot(3)`) is a suitable globally unique identifier for bus messages. Note that the sending order and receiving order of messages might differ, in particular for broadcast messages. This means that the sequence number and the timestamps of messages a client reads are not necessarily monotonically increasing. These timestamps and the sequence number are attached to each message by the kernel and cannot be manipulated by the sender. Note that these timestamps are only available on some bus transports, and only after support for them has been negotiated with the `sd_bus_negotiate_timestamp(3)` call. # Return Value On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style error code. On success, the timestamp or sequence number is returned in the specified 64-bit unsigned integer variable. ## Errors Returned errors may indicate the following problems: `-EINVAL` A specified parameter is invalid. `-ENODATA` No timestamp or sequence number information is attached to the passed message. This error is returned if the underlying transport does not support timestamping or assigning of sequence numbers, or if this feature has not been negotiated with `sd_bus_negotiate_timestamp(3)`. # History `sd_bus_message_get_monotonic_usec()`, `sd_bus_message_get_realtime_usec()`, and `sd_bus_message_get_seqnum()` were added in version 209. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_new(3)`, `sd_bus_negotiate_timestamp(3)`, `clock_gettime(2)`, `sd_id128_get_boot(3)` # sd_bus_message_get_signature systemd sd_bus_message_get_signature 3 sd_bus_message_get_signature sd_bus_message_is_empty sd_bus_message_has_signature Query bus message signature \#include \ const char\* sd_bus_message_get_signature sd_bus_message \* message int complete int sd_bus_message_is_empty sd_bus_message \* message int sd_bus_message_has_signature sd_bus_message \* message const char \* signature # Description `sd_bus_message_get_signature()` returns the signature of message `message`. If `complete` is true, the signature of the whole message is returned, and just the signature of the currently open container otherwise. `sd_bus_message_is_empty()` returns true if the message is empty, i.e. when its signature is empty. `sd_bus_message_has_signature()` returns true if the signature of the message `message` matches given `signature`. Parameter `signature` may be `NULL`, this is treated the same as an empty string, which is equivalent to calling `sd_bus_message_is_empty()`. # Return Value On success, `sd_bus_message_get_signature()` returns the signature, and `NULL` on error. The other functions return 0 or a positive integer on success. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `message` parameter is `NULL`. `NULL` The `message` parameter is `NULL`. # History `sd_bus_message_get_signature()`, `sd_bus_message_is_empty()`, and `sd_bus_message_has_signature()` were added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_new(3)` # sd_bus_message_get_type systemd sd_bus_message_get_type 3 sd_bus_message_get_type sd_bus_message_get_error sd_bus_message_get_errno sd_bus_message_get_creds sd_bus_message_is_signal sd_bus_message_is_method_call sd_bus_message_is_method_error Query bus message addressing/credentials metadata \#include \ int sd_bus_message_get_type sd_bus_message \* m uint8_t \* type sd_bus_error\* sd_bus_message_get_error sd_bus_message \* m int sd_bus_message_get_errno sd_bus_message \* m sd_bus_creds\* sd_bus_message_get_creds sd_bus_message \* m int sd_bus_message_is_signal sd_bus_message \* m const char \* interface const char \* member int sd_bus_message_is_method_call sd_bus_message \* m const char \* interface const char \* member int sd_bus_message_is_method_error sd_bus_message \* m const char \* name # Description `sd_bus_message_get_type()` returns the type of a message in the output parameter `type`, one of `SD_BUS_MESSAGE_METHOD_CALL`, `SD_BUS_MESSAGE_METHOD_RETURN`, `SD_BUS_MESSAGE_METHOD_ERROR`, `SD_BUS_MESSAGE_SIGNAL`. This type is either specified as a parameter when the message is created using `sd_bus_message_new(3)`, or is set automatically when the message is created using `sd_bus_message_new_signal(3)`, `sd_bus_message_new_method_call(3)`, `sd_bus_message_new_method_error(3)` and similar functions. `sd_bus_message_get_error()` returns the error stored in the message `m`, if there is any. Otherwise, it returns `NULL`. `sd_bus_message_get_errno()` returns the error stored in the message `m` as a positive errno-style value, if there is any. Otherwise, it returns zero. Errors are mapped to errno values according to the default and any additional registered error mappings. See `sd-bus-errors(3)` and `sd_bus_error_add_map(3)`. `sd_bus_message_get_creds()` returns the message credentials attached to the message `m`. If no credentials are attached to the message, it returns `NULL`. Ownership of the credentials instance is not transferred to the caller and hence should not be freed. `sd_bus_message_is_signal()` checks if message `m` is a signal message. If `interface` is non-null, it also checks if the message has the same interface set. If `member` is non-null, it also checks if the message has the same member set. Also see `sd_bus_message_new_signal(3)`. It returns true when all checks pass. `sd_bus_message_is_method_call()` checks if message `m` is a method call message. If `interface` is non-null, it also checks if the message has the same interface set. If `member` is non-null, it also checks if the message has the same member set. Also see `sd_bus_message_new_method_call(3)`. It returns true when all checks pass. `sd_bus_message_is_method_error()` checks if message `m` is an error reply message. If `name` is non-null, it also checks if the message has the same error identifier set. Also see `sd_bus_message_new_method_error(3)`. It returns true when all checks pass. # Return Value On success, these functions (except `sd_bus_message_get_error()` and `sd_bus_message_get_creds()`) return a non-negative integer. On failure, they return a negative errno-style error code. `sd_bus_message_get_errno()` always returns a non-negative integer, even on failure. ## Errors Returned errors may indicate the following problems: `-EINVAL` The message parameter `m` or an output parameter is `NULL`. # History `sd_bus_message_get_type()`, `sd_bus_message_is_signal()`, `sd_bus_message_is_method_call()`, and `sd_bus_message_is_method_error()` were added in version 240. `sd_bus_message_get_error()`, `sd_bus_message_get_errno()`, and `sd_bus_message_get_creds()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_new(3)`, `sd_bus_message_set_destination(3)`, `sd-bus-errors(3)`, `sd_bus_error_add_map(3)` # sd_bus_message_new systemd sd_bus_message_new 3 sd_bus_message_new sd_bus_message_ref sd_bus_message_unref sd_bus_message_unrefp SD_BUS_MESSAGE_METHOD_CALL SD_BUS_MESSAGE_METHOD_RETURN SD_BUS_MESSAGE_METHOD_ERROR SD_BUS_MESSAGE_SIGNAL sd_bus_message_get_bus Create a new bus message object and create or destroy references to it \#include \ enum { SD_BUS_MESSAGE_METHOD_CALL , SD_BUS_MESSAGE_METHOD_RETURN , SD_BUS_MESSAGE_METHOD_ERROR , SD_BUS_MESSAGE_SIGNAL , }; int sd_bus_message_new sd_bus \* bus sd_bus_message \*\* m uint8_t type sd_bus_message \* sd_bus_message_ref sd_bus_message \* m sd_bus_message \* sd_bus_message_unref sd_bus_message \* m void sd_bus_message_unrefp sd_bus_message \*\* mp sd_bus \* sd_bus_message_get_bus sd_bus_message \* m # Description `sd_bus_message_new()` creates a new bus message object attached to the bus `bus` and returns it in the output parameter `m`. This object is reference-counted, and will be destroyed when all references are gone. Initially, the caller of this function owns the sole reference to the message object. Note that the message object holds a reference to the bus object, so the bus object will not be destroyed as long as the message exists. Note: this is a low-level call. In most cases functions like `sd_bus_message_new_method_call(3)`, `sd_bus_message_new_method_error(3)`, `sd_bus_message_new_method_return(3)`, and `sd_bus_message_new_signal(3)` that create a message of a certain type and initialize various fields are easier to use. The `type` parameter specifies the type of the message. It must be one of `SD_BUS_MESSAGE_METHOD_CALL` — a method call, `SD_BUS_MESSAGE_METHOD_RETURN` — a method call reply, `SD_BUS_MESSAGE_METHOD_ERROR` — an error reply to a method call, `SD_BUS_MESSAGE_SIGNAL` — a broadcast message with no reply. The flag to allow interactive authorization is initialized based on the current value set in the bus object, see `sd_bus_set_allow_interactive_authorization(3)`. This may be changed using `sd_bus_message_set_allow_interactive_authorization(3)`. `sd_bus_message_ref()` increases the internal reference counter of `m` by one. `sd_bus_message_unref()` decreases the internal reference counter of `m` by one. Once the reference count has dropped to zero, message object is destroyed and cannot be used anymore, so further calls to `sd_bus_message_ref()` or `sd_bus_message_unref()` are illegal. `sd_bus_message_unrefp()` is similar to `sd_bus_message_unref()` but takes a pointer to a pointer to an `sd_bus_message` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). See `sd_bus_new(3)` for an example how to use the cleanup attribute. `sd_bus_message_ref()` and `sd_bus_message_unref()` execute no operation if the passed in bus message object address is `NULL`. `sd_bus_message_unrefp()` will first dereference its argument, which must not be `NULL`, and will execute no operation if *that* is `NULL`. `sd_bus_message_get_bus()` returns the bus object that message `m` is attached to. # Return Value On success, `sd_bus_message_new()` returns 0 or a positive integer. On failure, it returns a negative errno-style error code. `sd_bus_message_ref()` always returns the argument. `sd_bus_message_unref()` always returns `NULL`. `sd_bus_message_get_bus()` always returns the bus object. ## Errors Returned errors may indicate the following problems: `-EINVAL` Specified `type` is invalid. `-ENOTCONN` The bus parameter `bus` is `NULL` or the bus is not connected. `-ENOMEM` Memory allocation failed. # History `sd_bus_message_new()`, `sd_bus_message_ref()`, `sd_bus_message_unref()`, `sd_bus_message_unrefp()`, and `sd_bus_message_get_bus()` were added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_new(3)`, `sd_bus_message_new_method_call(3)`, `sd_bus_message_new_method_error(3)`, `sd_bus_message_new_method_return(3)`, `sd_bus_message_new_signal(3)` # sd_bus_message_new_method_call systemd sd_bus_message_new_method_call 3 sd_bus_message_new_method_call sd_bus_message_new_method_return Create a method call message \#include \ int sd_bus_message_new_method_call sd_bus \* bus sd_bus_message \*\* m const char \* destination const char \* path const char \* interface const char \* member int sd_bus_message_new_method_return sd_bus_message \* call sd_bus_message \*\* m # Description The `sd_bus_message_new_method_call()` function creates a new bus message object that encapsulates a D-Bus method call, and returns it in the `m` output parameter. The call will be made on the destination `destination`, path `path`, on the interface `interface`, member `member`. Briefly, the *destination* is a dot-separated name that identifies a service connected to the bus. The *path* is a slash-separated identifier of an object within the destination that resembles a file system path. The meaning of this path is defined by the destination. The *interface* is a dot-separated name that resembles a Java interface name that identifies a group of methods and signals supported by the object identified by path. Methods and signals are collectively called *members* and are identified by a simple name composed of ASCII letters, numbers, and underscores. See the [D-Bus Tutorial](https://dbus.freedesktop.org/doc/dbus-tutorial.html#concepts) for an in-depth explanation. The `destination` parameter may be `NULL`. The `interface` parameter may be `NULL`, if the destination has only a single member with the given name and there is no ambiguity if the interface name is omitted. Note that this is a low level interface. See `sd_bus_call_method(3)` for a more convenient way of calling D-Bus methods. The `sd_bus_message_new_method_return()` function creates a new bus message object that is a reply to the method call `call` and returns it in the `m` output parameter. The `call` parameter must be a method call message. The sender of `call` is used as the destination. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The output parameter `m` is `NULL`. The `destination` parameter is non-null and is not a valid D-Bus service name (`org.somewhere.Something`), the `path` parameter is not a valid D-Bus path (`/an/object/path`), the `interface` parameter is non-null and is not a valid D-Bus interface name (`an.interface.name`), or the `member` parameter is not a valid D-Bus member (`Name`). The `call` parameter is not a method call object. `-ENOTCONN` The bus parameter `bus` is `NULL` or the bus is not connected. `-ENOMEM` Memory allocation failed. `-EPERM` The `call` parameter is not sealed. `-EOPNOTSUPP` The `call` message does not have a cookie. # Examples
Make a call to a D-Bus method that takes a single parameter
This defines a minimally useful program that will open a connection to the bus, create a message object, send it, wait for the reply, and finally extract and print the answer. It does error handling and proper memory management.
# History `sd_bus_message_new_method_call()` and `sd_bus_message_new_method_return()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_call(3)`, `sd_bus_call_method(3)`, `sd_bus_path_encode(3)` # sd_bus_message_new_method_error systemd sd_bus_message_new_method_error 3 sd_bus_message_new_method_error sd_bus_message_new_method_errorf sd_bus_message_new_method_errno sd_bus_message_new_method_errnof Create an error reply for a method call \#include \ int sd_bus_message_new_method_error sd_bus_message \* call sd_bus_message \*\* m const sd_bus_error \* e int sd_bus_message_new_method_errorf sd_bus_message \* call sd_bus_message \*\* m const char \* name const char \* format … int sd_bus_message_new_method_errno sd_bus_message \* call sd_bus_message \*\* m int error const sd_bus_error \* p int sd_bus_message_new_method_errnof sd_bus_message \* call sd_bus_message \*\* m int error const char \* format … # Description The `sd_bus_message_new_method_error()` function creates a new bus message object that is an error reply to the `call` message, and returns it in the `m` output parameter. The error information from error `e` is appended: the `name` field of `e` is used as the error identifier in the reply header (for example an error name such as `org.freedesktop.DBus.Error.NotSupported` or the equivalent symbolic `SD_BUS_ERROR_NOT_SUPPORTED`), and the `message` field is set as the human-readable error message string if present. The error `e` must have the `name` field set, see `sd_bus_error_is_set(3)`. The `sd_bus_message_new_method_errorf()` function creates an error reply similarly to `sd_bus_message_new_method_error()`, but instead of a ready error structure, it takes an error identifier string `name`, plus a `printf(3)` format string `format` and corresponding arguments. An error reply is sent with the error identifier `name` and the formatted string as the message. `name` and `format` must not be `NULL`. The `sd_bus_message_new_method_errno()` function creates an error reply similarly to `sd_bus_message_new_method_error()`, but in addition to the error structure `p`, it takes an `errno(3)` error value in parameter `error`. If the error `p` is set (see `sd_bus_error_is_set(3)`), it is used in the reply. Otherwise, `error` is translated to an error identifier and used to create a new error structure using `sd_bus_error_set_errno(3)` and that is used in the reply. (If `error` is zero, no error is actually set, and an error reply with no information is created.) The `sd_bus_message_new_method_errnof()` function creates an error reply similarly to `sd_bus_message_new_method_error()`. It takes an `errno(3)` error value in parameter `error`, plus a `printf(3)` format string `format` and corresponding arguments. `%m` may be used in the format string to refer to the error string corresponding to the specified errno code. The error message is initialized using the error identifier generated from `error` and the formatted string. (If `error` is zero, no error is actually set, and an error reply with no information is created.) # Return Value These functions return 0 if the error reply was successfully created, and a negative errno-style error code otherwise. ## Errors Returned errors may indicate the following problems: `-EINVAL` The call message `call` or the output parameter `m` are `NULL`. Message `call` is not a method call message. The error `e` parameter to `sd_bus_message_new_method_error()` is not set, see `sd_bus_error_is_set(3)`. `-EPERM` Message `call` has been sealed. `-ENOTCONN` The bus to which message `call` is attached is not connected. `-ENOMEM` Memory allocation failed. # See Also `systemd(1)`, `sd-bus(3)` # sd_bus_message_new_signal systemd sd_bus_message_new_signal 3 sd_bus_message_new_signal sd_bus_message_new_signal_to Create a signal message \#include \ int sd_bus_message_new_signal sd_bus \* bus sd_bus_message \*\* m const char \* path const char \* interface const char \* member int sd_bus_message_new_signal_to sd_bus \* bus sd_bus_message \*\* m const char \* destination const char \* path const char \* interface const char \* member # Description The `sd_bus_message_new_signal()` function creates a new bus message object that encapsulates a D-Bus signal, and returns it in the `m` output parameter. The signal will be sent to path `path`, on the interface `interface`, member `member`. When this message is sent, no reply is expected. See `sd_bus_message_new_method_call(3)` for a short description of the meaning of the `path`, `interface`, and `member` parameters. `sd_bus_message_new_signal_to()` is a shorthand for creating a new bus message to a specific destination. It's behavior is similar to calling `sd_bus_message_new_signal()` followed by calling `sd_bus_message_set_destination(3)`. # Return Value This function returns 0 if the message object was successfully created, and a negative errno-style error code otherwise. ## Errors Returned errors may indicate the following problems: `-EINVAL` The output parameter `m` is `NULL`. The `path` parameter is not a valid D-Bus path (`/an/object/path`), the `interface` parameter is not a valid D-Bus interface name (`an.interface.name`), or the `member` parameter is not a valid D-Bus member (`Name`). `-ENOTCONN` The bus parameter `bus` is `NULL` or the bus is not connected. `-ENOMEM` Memory allocation failed. # Examples
Send a simple signal
This function in systemd sources is used to emit the `UnitFilesChanged` signal when the unit files have been changed.
# See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_emit_signal(3)`, `sd_bus_message_set_destination(3)` # sd_bus_message_open_container systemd sd_bus_message_open_container 3 sd_bus_message_open_container sd_bus_message_close_container sd_bus_message_enter_container sd_bus_message_exit_container Create and move between containers in D-Bus messages \#include \ int sd_bus_message_open_container sd_bus_message \* m char type const char \* contents int sd_bus_message_close_container sd_bus_message \* m int sd_bus_message_enter_container sd_bus_message \* m char type const char \* contents int sd_bus_message_exit_container sd_bus_message \* m # Description `sd_bus_message_open_container()` appends a new container to the message `m`. After opening a new container, it can be filled with content using `sd_bus_message_append(3)` and similar functions. Containers behave like a stack. To nest containers inside each other, call `sd_bus_message_open_container()` multiple times without calling `sd_bus_message_close_container()` in between. Each container will be nested inside the previous container. `type` represents the container type and should be one of `r`, `a`, `v` or `e` as described in `sd_bus_message_append(3)`. Instead of literals, the corresponding constants `SD_BUS_TYPE_STRUCT`, `SD_BUS_TYPE_ARRAY`, `SD_BUS_TYPE_VARIANT` or `SD_BUS_TYPE_DICT_ENTRY` can also be used. `contents` describes the type of the container's elements and should be a D-Bus type string following the rules described in `sd_bus_message_append(3)`. `sd_bus_message_close_container()` closes the last container opened with `sd_bus_message_open_container()`. On success, the write pointer of the message `m` is positioned after the closed container in its parent container or in `m` itself if there is no parent container. `sd_bus_message_enter_container()` enters the next container of the message `m` for reading. It behaves mostly the same as `sd_bus_message_open_container()`. Entering a container allows reading its contents with `sd_bus_message_read(3)` and similar functions. `type` and `contents` are the same as in `sd_bus_message_open_container()`. `sd_bus_message_exit_container()` exits the scope of the last container entered with `sd_bus_message_enter_container()`. It behaves mostly the same as `sd_bus_message_close_container()`. Note that `sd_bus_message_exit_container()` may only be called after iterating through all members of the container, i.e. reading or skipping over them. Use `sd_bus_message_skip(3)` to skip over fields of a container in order to be able to exit the container with `sd_bus_message_exit_container()` without reading all members. # Return Value On success, these functions return a non-negative integer. `sd_bus_message_open_container()` and `sd_bus_message_close_container()` return 0. `sd_bus_message_enter_container()` returns 1 if it successfully opened a new container, and 0 if that was not possible because the end of the currently open container or message was reached. `sd_bus_message_exit_container()` returns 1 on success. On failure, all of these functions return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `m` or `contents` are `NULL` or `type` is invalid. `-EBADMSG` Message `m` has invalid structure. `-ENXIO` Message `m` does not have a container of type `type` at the current position, or the contents do not match `contents`. `-EPERM` The message `m` is already sealed. `-ESTALE` The message `m` is in an invalid state. `-ENOMEM` Memory allocation failed. `-EBUSY` `sd_bus_message_exit_container()` was called but there are unread members left in the container. # Examples
Append an array of strings to a message
Read an array of strings from a message
# See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_append(3)`, `sd_bus_message_read(3)`, `sd_bus_message_skip(3)`, [The D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html) # sd_bus_message_read systemd sd_bus_message_read 3 sd_bus_message_read sd_bus_message_readv sd_bus_message_peek_type Read a sequence of values from a message \#include \ int sd_bus_message_read sd_bus_message \* m const char \* types ... int sd_bus_message_readv sd_bus_message \* m const char \* types va_list ap int sd_bus_message_peek_type sd_bus_message \* m char \* type const char \*\* contents # Description `sd_bus_message_read()` reads a sequence of fields from the D-Bus message object `m` and advances the read position in the message. The type string `types` describes the types of items expected in the message and the field arguments that follow. The type string may be `NULL` or empty, in which case nothing is read. The type string is composed of the elements described in `sd_bus_message_append(3)`, i.e. basic and container types. It must contain zero or more single "complete types". The type string is `NUL`-terminated. For each type specified in the type string, one or more arguments need to be specified after the `types` parameter, in the same order. The arguments must be pointers to appropriate types (a pointer to `int8_t` for a `y` in the type string, a pointer to `int32_t` for an `i`, a pointer to `const char*` for an `s`, ...) which are set based on the values in the message. As an exception, in case of array and variant types, the first argument is an "input" argument that further specifies how the message should be read. See the table below for a complete list of allowed arguments and their types. Note that, if the basic type is a pointer (e.g., `const char *` in the case of a string), the argument is a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must be copied if they are to be used after the end of the message's lifetime. If the type is `h` (UNIX file descriptor), the descriptor is not duplicated by this call and the returned descriptor remains in possession of the message object, and needs to be duplicated by the caller in order to keep an open reference to it after the message object is freed. Each argument may also be `NULL`, in which case the value is read and ignored.
Item type specifiers
Specifier Constant Description Type of the first argument Types of the subsequent arguments, if any
a SD_BUS_TYPE_ARRAY array int, which specifies the expected length n of the array n sets of arguments appropriate for the array element type
v SD_BUS_TYPE_VARIANT variant signature string arguments appropriate for the types specified by the signature
( SD_BUS_TYPE_STRUCT_BEGIN array start arguments appropriate for the structure elements
) SD_BUS_TYPE_STRUCT_END array end
{ SD_BUS_TYPE_DICT_ENTRY_BEGIN dictionary entry start arguments appropriate for the first type in the pair arguments appropriate for the second type in the pair
} SD_BUS_TYPE_DICT_ENTRY_END dictionary entry end
If objects of the specified types are not present at the current position in the message, an error is returned. The `sd_bus_message_readv()` is equivalent to the `sd_bus_message_read()`, except that it is called with a `va_list` instead of a variable number of arguments. This function does not call the `va_end()` macro. Because it invokes the `va_arg()` macro, the value of `ap` is undefined after the call. `sd_bus_message_peek_type()` determines the type of the next element in `m` to be read by `sd_bus_message_read()` or similar functions. On success, the type is stored in `type`, if it is not `NULL`. If the type is a container type, the type of its elements is stored in `contents`, if it is not `NULL`. If this function successfully determines the type of the next element in `m`, it returns a positive integer. If there are no more elements to be read, it returns zero. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EBUSY` When reading from a container, this error will be returned if unread elements are left in the container. # Examples Read a single basic type (a 64-bit integer): sd_bus_message *m; int64_t x; sd_bus_message_read(m, "x", &x); Read a boolean value: sd_bus_message *m; int x; /* Do not use C99 "bool" type here, it is typically smaller in memory and would cause memory corruption */ sd_bus_message_read(m, "b", &x); Read all types of integers: uint8_t y; int16_t n; uint16_t q; int32_t i; uint32_t u; int64_t x; uint64_t t; double d; sd_bus_message_read(m, "ynqiuxtd", &y, &n, &q, &i, &u, &x, &t, &d); Read a structure composed of a string and a D-Bus path: const char *s, *p; sd_bus_message_read(m, "(so)", &s, &p); Read a variant, with the real type "gt" (signature, unsigned integer): const char *s; uint64_t *v; sd_bus_message_read(m, "v", "gt", &s, &v); Read a dictionary containing three pairs of type {integer=\>string}: int i, j, k; const char *s, *t, *u; sd_bus_message_read(m, "a{is}", 3, &i, &s, &j, &t, &k, &u); Read a single file descriptor, and duplicate it in order to keep it open after the message is freed. sd_bus_message *m; int fd, fd_copy; sd_bus_message_read(m, "h", &fd); fd_copy = fcntl(fd, FD_DUPFD_CLOEXEC, 3); # History `sd_bus_message_read()` and `sd_bus_message_readv()` were added in version 240. `sd_bus_message_peek_type()` was added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_read_basic(3)`, `sd_bus_message_skip(3)`, `sd_bus_message_append(3)`, `sd_bus_message_enter_container(3)` # sd_bus_message_read_array systemd sd_bus_message_read_array 3 sd_bus_message_read_array Access an array of elements in a message \#include \ int sd_bus_message_read_array sd_bus_message \* m char type const void \*\* ret_ptr size_t \* ret_size # Description `sd_bus_message_read_array()` provides access to an array of elements in the bus message `m`. The "read pointer" in the message must be right before an array of type `type`. A pointer to the array data is returned in the parameter `ret_ptr` and the size of the array data (in bytes) is returned in the parameter `ret_size`. If this returns a positive value and the returned `ret_size` is 0, a valid non-`NULL` pointer will be returned as `ret_ptr`, but it may not be dereferenced. The data is aligned as appropriate for the data type. The data is part of the message — it may not be modified and is valid only as long as the message is referenced. If this returns a positive value, the "read pointer" points at the next element after the array. Note that this function only supports arrays of trivial types, i.e. arrays of booleans, the various integer types, as well as floating point numbers. In particular it may not be used for arrays of strings, structures or similar. # Return Value On success and when an array was read, `sd_bus_message_read_array()` returns an integer greater than zero. If invoked while inside a container element (such as an array, e.g. when operating on an array of arrays) and the final element of the outer container has been read already and the read pointer is thus behind the last element of the outer container this call returns 0 (and the returned pointer will be `NULL` and the size will be 0). On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` Specified type is invalid or not a trivial type (see above), or the message parameter or one of the output parameters are `NULL`. `-EOPNOTSUPP` The byte order in the message is different than native byte order. `-EPERM` The message is not sealed. `-EBADMSG` The message cannot be parsed. # History `sd_bus_message_read_array()` was added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_read(3)`, `sd_bus_message_read_strv(3)` # sd_bus_message_read_basic systemd sd_bus_message_read_basic 3 sd_bus_message_read_basic Read a basic type from a message \#include \ int sd_bus_message_read_basic sd_bus_message \* m char type void \* p # Description `sd_bus_message_read_basic()` reads a basic type from a message and advances the read position in the message. The set of basic types and their ascii codes passed in `type` are described in the [D-Bus Specification](https://dbus.freedesktop.org/doc/dbus-specification.html). If `p` is not `NULL`, it should contain a pointer to an appropriate object. For example, if `type` is `'y'`, the object passed in `p` should have type `uint8_t *`. If `type` is `'s'`, the object passed in `p` should have type `const char **`. Note that, if the basic type is a pointer (e.g., `const char *` in the case of a string), the pointer is only borrowed and the contents must be copied if they are to be used after the end of the message's lifetime. Similarly, during the lifetime of such a pointer, the message must not be modified. If `type` is `'h'` (UNIX file descriptor), the descriptor is not duplicated by this call and the returned descriptor remains in possession of the message object, and needs to be duplicated by the caller in order to keep an open reference to it after the message object is freed (for example by calling `fcntl(fd, FD_DUPFD_CLOEXEC, 3)`). See the table below for a complete list of allowed types. | Specifier | Constant | Description | Expected C Type | |----|----|----|----| | `y` | `SD_BUS_TYPE_BYTE` | 8-bit unsigned integer | `uint8_t *` | | `b` | `SD_BUS_TYPE_BOOLEAN` | boolean | `int *` (NB: not `bool *`) | | `n` | `SD_BUS_TYPE_INT16` | 16-bit signed integer | `int16_t *` | | `q` | `SD_BUS_TYPE_UINT16` | 16-bit unsigned integer | `uint16_t *` | | `i` | `SD_BUS_TYPE_INT32` | 32-bit signed integer | `int32_t *` | | `u` | `SD_BUS_TYPE_UINT32` | 32-bit unsigned integer | `uint32_t *` | | `x` | `SD_BUS_TYPE_INT64` | 64-bit signed integer | `int64_t *` | | `t` | `SD_BUS_TYPE_UINT64` | 64-bit unsigned integer | `uint64_t *` | | `d` | `SD_BUS_TYPE_DOUBLE` | IEEE 754 double precision floating-point | `double *` | | `s` | `SD_BUS_TYPE_STRING` | UTF-8 string | `const char **` | | `o` | `SD_BUS_TYPE_OBJECT_PATH` | D-Bus object path string | `const char **` | | `g` | `SD_BUS_TYPE_SIGNATURE` | D-Bus signature string | `const char **` | | `h` | `SD_BUS_TYPE_UNIX_FD` | UNIX file descriptor | `int *` | Item type specifiers {#format-specifiers} If there is no object of the specified type at the current position in the message, an error is returned. # Return Value On success, `sd_bus_message_read_basic()` returns a positive integer. If the end of the currently opened array has been reached, it returns 0. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` Specified type string is invalid or the message parameter is `NULL`. `-ENXIO` The message does not contain the specified type at current position. `-EBADMSG` The message cannot be parsed. # History `sd_bus_message_read_basic()` was added in version 221. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_append_basic(3)`, `sd_bus_message_skip(3)`, `sd_bus_message_read(3)` # sd_bus_message_read_strv systemd sd_bus_message_read_strv 3 sd_bus_message_read_strv sd_bus_message_read_strv_extend Access an array of strings in a message \#include \ int sd_bus_message_read_strv sd_bus_message \* m char \*\*\* l int sd_bus_message_read_strv_extend sd_bus_message \* m char \*\*\* l # Description `sd_bus_message_read_strv()` reads an array of string-like items from the message `m`. The "read pointer" in the message must be right before an array of strings (D-Bus type `as`), object paths (D-Bus type `ao`), or signatures (D-Bus type `ag`). On success, a pointer to a `NULL`-terminated array of strings (strv) is returned in the output parameter `l`. Note that ownership of this array is transferred to the caller. Hence, the caller is responsible for freeing this array and its contents. Also note that as a matter of optimization, if an empty array is encountered a `NULL` pointer might be returned here, and should be considered equivalent to an array with zero entries. `sd_bus_message_read_strv_extend()` is similar, but the second parameter is an input-output parameter. If `*l` is `NULL`, if behaves identically to `sd_bus_message_read_strv()`. Otherwise, `*l` must point to a strv, which will be reallocated and extended with additional strings. This function is particularly useful when combining multiple lists of strings in a message or messages into a single array of strings. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `m` or `l` are `NULL`. `-EPERM` The message is not sealed. `-EBADMSG` The message cannot be parsed. `-ENXIO` The message "read pointer" is not right before an array of the appropriate type. # History `sd_bus_message_read_strv()` was added in version 246. `sd_bus_message_read_strv_extend()` was added in version 252. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_read(3)` # sd_bus_message_rewind systemd sd_bus_message_rewind 3 sd_bus_message_rewind Return to beginning of message or current container \#include \ int sd_bus_message_rewind sd_bus_message \* m int complete # Description `sd_bus_message_rewind()` moves the "read pointer" in the message `m` to either the beginning of the message (if `complete` is true) or to the beginning of the currently open container. If no container is open, `complete` has no effect. # Return Value On success, this function returns 0 or a positive integer. The value is zero if the current container or whole message in case no container is open is empty, and positive otherwise. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `m` parameter is `NULL`. `-EPERM` The message `m` has not been sealed. # History `sd_bus_message_rewind()` was added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_read(3)` # sd_bus_message_seal systemd sd_bus_message_seal 3 sd_bus_message_seal Prepare a D-Bus message for transmission \#include \ int sd_bus_message_seal sd_bus_message \* m uint64_t cookie uint64_t timeout_usec # Description `sd_bus_message_seal()` finishes the message `m` and prepares it for transmission using `sd_bus_send(3)`. `cookie` specifies the identifier used to match the message reply to its corresponding request. `timeout_usec` specifies the maximum time in microseconds to wait for a reply to arrive. Note that in most scenarios, it is not necessary to call this function directly. `sd_bus_call(3)`, `sd_bus_call_async(3)` and `sd_bus_send(3)` will seal any given messages if they have not been sealed yet. # Return Value On success, this function returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `m` parameter is `NULL`. `-EBADMSG` The D-Bus message `m` has open containers. `-ENOMSG` The D-Bus message `m` is a reply but its type signature does not match the return type signature of its corresponding member in the object vtable. # History `sd_bus_message_seal()` was added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_call(3)`, `sd_bus_call_async(3)`, `sd_bus_send(3)` # sd_bus_message_sensitive systemd sd_bus_message_sensitive 3 sd_bus_message_sensitive Mark a message object as containing sensitive data \#include \ int sd_bus_message_sensitive sd_bus_message \* message # Description `sd_bus_message_sensitive()` marks an allocated bus message as containing sensitive data. This ensures that the message data is carefully removed from memory (specifically, overwritten with zero bytes) when released. It is recommended to mark all incoming and outgoing messages like this that contain security credentials and similar data that should be dealt with carefully. Note that it is not possible to unmark messages like this, it is a one way operation. If a message is already marked sensitive and then marked sensitive a second time the message remains marked so and no further operation is executed. As a safety precaution all messages that are created as reply to messages that are marked sensitive are also implicitly marked so. # Return Value On success, this functions return 0 or a positive integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `message` parameter is `NULL`. # History `sd_bus_message_sensitive()` was added in version 245. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_new_method_call(3)` # sd_bus_message_set_destination systemd sd_bus_message_set_destination 3 sd_bus_message_set_destination sd_bus_message_get_destination sd_bus_message_get_path sd_bus_message_get_interface sd_bus_message_get_member sd_bus_message_set_sender sd_bus_message_get_sender Set and query bus message addressing information \#include \ int sd_bus_message_set_destination sd_bus_message \* message const char \* destination const char\* sd_bus_message_get_destination sd_bus_message \* message const char\* sd_bus_message_get_path sd_bus_message \* message const char\* sd_bus_message_get_interface sd_bus_message \* message const char\* sd_bus_message_get_member sd_bus_message \* message int sd_bus_message_set_sender sd_bus_message \* message const char \* sender const char\* sd_bus_message_get_sender sd_bus_message \* message # Description `sd_bus_message_set_destination()` sets the destination service name for the specified bus message object. The specified name must be a valid unique or well-known service name. `sd_bus_message_get_destination()`, `sd_bus_message_get_path()`, `sd_bus_message_get_interface()`, and `sd_bus_message_get_member()` return the destination, path, interface, and member fields from `message` header. The return value will be `NULL` if `message` is `NULL` or the message is of a type that does not use those fields or the message does not have them set. See `sd_bus_message_new_method_call(3)` and `sd_bus_message_set_destination(3)` for more discussion of those values. `sd_bus_message_set_sender()` sets the sender service name for the specified bus message object. The specified name must be a valid unique or well-known service name. This function is useful only for messages to send on direct connections as for connections to bus brokers the broker will fill in the destination field anyway, and the sender field set by original sender is ignored. `sd_bus_message_get_sender()` returns the sender field from `message`. When a string is returned, it is a pointer to internal storage, and may not be modified or freed. It is only valid as long as the `message` remains referenced and this field has not been changed by a different call. # Return Value On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `message` parameter or the output parameter are `NULL`. `-EPERM` For `sd_bus_message_set_destination()` and `sd_bus_message_set_sender()`, the message is already sealed. `-EEXIST` The message already has a destination or sender field set. # History `sd_bus_message_set_destination()` and `sd_bus_message_set_sender()` were added in version 237. `sd_bus_message_get_destination()`, `sd_bus_message_get_path()`, `sd_bus_message_get_interface()`, `sd_bus_message_get_member()`, and `sd_bus_message_get_sender()` were added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_new(3)`, `sd_bus_set_sender(3)` # sd_bus_message_set_expect_reply systemd sd_bus_message_set_expect_reply 3 sd_bus_message_set_expect_reply sd_bus_message_get_expect_reply sd_bus_message_set_auto_start sd_bus_message_get_auto_start sd_bus_message_set_allow_interactive_authorization sd_bus_message_get_allow_interactive_authorization Set and query bus message metadata \#include \ int sd_bus_message_set_expect_reply sd_bus_message \* message int b int sd_bus_message_get_expect_reply sd_bus_message \* message int sd_bus_message_set_auto_start sd_bus_message \* message int b int sd_bus_message_get_auto_start sd_bus_message \* message int sd_bus_message_set_allow_interactive_authorization sd_bus_message \* message int b int sd_bus_message_get_allow_interactive_authorization sd_bus_message \* message # Description `sd_bus_message_set_expect_reply()` sets or clears the `NO_REPLY_EXPECTED` flag on the message `m`. This flag matters only for method call messages and is used to specify that no method return or error reply is expected. It is ignored for other types. Thus, for a method call message, calling sd_bus_message_set_expect_reply(…, 0) sets the flag and suppresses the reply. `sd_bus_message_get_expect_reply()` checks if the `NO_REPLY_EXPECTED` flag is set on the message `m`. It will return positive if it is not set, and zero if it is. `sd_bus_message_set_auto_start()` sets or clears the `NO_AUTO_START` flag on the message `m`. When the flag is set, the bus must not launch an owner for the destination name in response to this message. Calling sd_bus_message_set_auto_start(…, 0) sets the flag. `sd_bus_message_get_auto_start()` checks if the `NO_AUTO_START` flag is set on the message `m`. It will return positive if it is not set, and zero if it is. `sd_bus_message_set_allow_interactive_authorization()` sets or clears the `ALLOW_INTERACTIVE_AUTHORIZATION` flag on the message `m`. Setting this flag informs the receiver that the caller is prepared to wait for interactive authorization via polkit or a similar framework. Note that setting this flag does not guarantee that the receiver will actually perform interactive authorization. Also, make sure to set a suitable message timeout when using this flag since interactive authorization could potentially take a long time as it depends on user input. If `b` is non-zero, the flag is set. `sd_bus_message_get_allow_interactive_authorization()` checks if the `ALLOW_INTERACTIVE_AUTHORIZATION` flag is set on the message `m`. It will return a positive integer if the flag is set. Otherwise, it returns zero. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `message` parameter is `NULL`. `-EPERM` The message `message` is sealed when trying to set a flag. The message `message` has wrong type. # History `sd_bus_message_set_expect_reply()`, `sd_bus_message_get_expect_reply()`, `sd_bus_message_set_auto_start()`, and `sd_bus_message_get_auto_start()` were added in version 240. `sd_bus_message_set_allow_interactive_authorization()` and `sd_bus_message_get_allow_interactive_authorization()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_set_description(3)` # sd_bus_message_skip systemd sd_bus_message_skip 3 sd_bus_message_skip Skip elements in a bus message \#include \ int sd_bus_message_skip sd_bus_message \* m const char\* types # Description `sd_bus_message_skip()` is somewhat similar to `sd_bus_message_read(3)`, but instead of reading the contents of the message, it only moves the "read pointer". Subsequent read operations will read the elements that are after the elements that were skipped. The `types` argument has the same meaning as in `sd_bus_message_read()`. It may also be `NULL`, to skip a single element of any type. # Return Value On success, `sd_bus_message_skip()` returns 0 or a positive integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `m` parameter is `NULL`. `-EBADMSG` The message cannot be parsed. `-EPERM` The message is not sealed. `-ENXIO` The message end has been reached and the requested elements cannot be read. `-ENOMEM` Memory allocation failed. # History `sd_bus_message_skip()` was added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_read(3)`, `sd_bus_message_read_basic(3)` # sd_bus_message_verify_type systemd sd_bus_message_verify_type 3 sd_bus_message_verify_type Check if the message has specified type at the current location \#include \ int sd_bus_message_verify_type sd_bus_message \* m char type const char\* contents # Description `sd_bus_message_verify_type()` checks if the complete type at the current location in the message `m` matches the specified `type` and `contents`. If non-zero, parameter `type` must be one of the types specified in `sd_bus_message_append(3)`. If non-null, parameter `contents` must be a valid sequence of complete types. If both `type` and `contents` are specified `type` must be a container type. If `type` is specified, the type in the message must match. If `contents` is specified, the type in the message must be a container type with this signature. # Return Value On success, this call returns true if the type matches and zero if not (the message `m` contains different data or the end of the message has been reached). On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `m` or both `type` and `contents` are `NULL`. Arguments do not satisfy other constraints listed above. `-EPERM` Message `m` is not sealed. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_append(3)` # sd_bus_negotiate_fds systemd sd_bus_negotiate_fds 3 sd_bus_negotiate_fds sd_bus_negotiate_timestamp sd_bus_negotiate_creds sd_bus_get_creds_mask Control feature negotiation on bus connections \#include \ int sd_bus_negotiate_fds sd_bus \* bus int b int sd_bus_negotiate_timestamp sd_bus \* bus int b int sd_bus_negotiate_creds sd_bus \* bus int b uint64_t mask int sd_bus_get_creds_mask sd_bus \* bus uint64_t \* mask # Description `sd_bus_negotiate_fds()` controls whether file descriptor passing shall be negotiated for the specified bus connection. It takes a bus object and a boolean, which, when true, enables file descriptor passing, and, when false, disables it. Note that not all transports and servers support file descriptor passing. In particular, networked transports generally do not support file descriptor passing. To find out whether file descriptor passing is available after negotiation, use `sd_bus_can_send(3)` and pass `SD_BUS_TYPE_UNIX_FD`. Note that file descriptor passing is always enabled for both sending and receiving or for neither, but never only in one direction. By default, file descriptor passing is negotiated for all connections. `sd_bus_negotiate_timestamp()` controls whether implicit sender timestamps shall be attached automatically to all incoming messages. Takes a bus object and a boolean, which, when true, enables timestamping, and, when false, disables it. Use `sd_bus_message_get_monotonic_usec(3)`, `sd_bus_message_get_realtime_usec(3)`, `sd_bus_message_get_seqnum(3)` to query the timestamps of incoming messages. If negotiation is disabled or not supported, these calls will fail with `-ENODATA`. Note that currently no transports support timestamping of messages. By default, message timestamping is not negotiated for connections. `sd_bus_negotiate_creds()` controls whether and which implicit sender credentials shall be attached automatically to all incoming messages. Takes a bus object and a boolean indicating whether to enable or disable the credential parts encoded in the bit mask value argument. Note that not all transports support attaching sender credentials to messages, or do not support all types of sender credential parameters, or might suppress them under certain circumstances for individual messages. Specifically, dbus1 only supports `SD_BUS_CREDS_UNIQUE_NAME`. The sender credentials are suitable for authorization decisions. By default, only `SD_BUS_CREDS_WELL_KNOWN_NAMES` and `SD_BUS_CREDS_UNIQUE_NAME` are enabled. In fact, these two credential fields are always sent along and cannot be turned off. `sd_bus_get_creds_mask()` returns the set of sender credentials that was negotiated to be attached to all incoming messages in `mask`. This value is an upper boundary only. Hence, always make sure to explicitly check which credentials are attached to a specific message before using it. The `sd_bus_negotiate_fds()` function may be called only before the connection has been started with `sd_bus_start(3)`. Both `sd_bus_negotiate_timestamp()` and `sd_bus_negotiate_creds()` may also be called after a connection has been set up. Note that, when operating on a connection that is shared between multiple components of the same program (for example via `sd_bus_default(3)`), it is highly recommended to only enable additional per message metadata fields, but never disable them again, in order not to disable functionality needed by other components. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EPERM` The bus connection has already been started. `-EINVAL` An argument is invalid. `-ENOPKG` The bus cannot be resolved. `-ECHILD` The bus was created in a different process, library or module instance. # History `sd_bus_negotiate_fds()`, `sd_bus_negotiate_timestamp()`, and `sd_bus_negotiate_creds()` were added in version 212. `sd_bus_get_creds_mask()` was added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_start(3)`, `sd_bus_can_send(3)`, `sd_bus_message_get_monotonic_usec(3)`, `sd_bus_message_get_realtime_usec(3)`, `sd_bus_message_get_seqnum(3)`, `sd_bus_message_get_creds(3)` # sd_bus_new systemd sd_bus_new 3 sd_bus_new sd_bus_ref sd_bus_unref sd_bus_unrefp sd_bus_close_unref sd_bus_close_unrefp sd_bus_flush_close_unref sd_bus_flush_close_unrefp Create a new bus object and create or destroy references to it \#include \ int sd_bus_new sd_bus \*\* bus sd_bus \* sd_bus_ref sd_bus \* bus sd_bus \* sd_bus_unref sd_bus \* bus sd_bus \* sd_bus_close_unref sd_bus \* bus sd_bus \* sd_bus_flush_close_unref sd_bus \* bus void sd_bus_unrefp sd_bus \*\* busp void sd_bus_close_unrefp sd_bus \*\* busp void sd_bus_flush_close_unrefp sd_bus \*\* busp # Description `sd_bus_new()` creates a new bus object. This object is reference-counted, and will be destroyed when all references are gone. Initially, the caller of this function owns the sole reference and the bus object will not be connected to any bus. To connect it to a bus, make sure to set an address with `sd_bus_set_address(3)` or a related call, and then start the connection with `sd_bus_start(3)`. In most cases, it is better to use `sd_bus_default_user(3)`, `sd_bus_default_system(3)` or related calls instead of the more low-level `sd_bus_new()` and `sd_bus_start()`. The higher-level functions not only allocate a bus object but also start the connection to a well-known bus in a single function call. `sd_bus_ref()` increases the reference counter of `bus` by one. `sd_bus_unref()` decreases the reference counter of `bus` by one. Once the reference count has dropped to zero, `bus` is destroyed and cannot be used anymore, so further calls to `sd_bus_ref()` or `sd_bus_unref()` are illegal. `sd_bus_unrefp()` is similar to `sd_bus_unref()` but takes a pointer to a pointer to an `sd_bus` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). Note that this function is defined as an inline function. Use a declaration like the following, in order to allocate a bus object that is freed automatically as the code block is left: { __attribute__((cleanup(sd_bus_unrefp))) sd_bus *bus = NULL; int r; … r = sd_bus_default(&bus); if (r < 0) { errno = -r; fprintf(stderr, "Failed to allocate bus: %m\n"); } … } `sd_bus_ref()` and `sd_bus_unref()` execute no operation if the argument is `NULL`. `sd_bus_unrefp()` will first dereference its argument, which must not be `NULL`, and will execute no operation if *that* is `NULL`. `sd_bus_close_unref()` is similar to `sd_bus_unref()`, but first executes `sd_bus_close(3)`, ensuring that the connection is terminated before the reference to the connection is dropped and possibly the object freed. `sd_bus_flush_close_unref()` is similar to `sd_bus_unref()`, but first executes `sd_bus_flush(3)` as well as `sd_bus_close(3)`, ensuring that any pending messages are synchronously flushed out before the reference to the connection is dropped and possibly the object freed. This call is particularly useful immediately before exiting from a program as it ensures that any pending outgoing messages are written out, and unprocessed but queued incoming messages released before the connection is terminated and released. `sd_bus_close_unrefp()` is similar to `sd_bus_close_unref()`, but may be used in GCC's and LLVM's Clean-up Variable Attribute, see above. Similarly, `sd_bus_flush_close_unrefp()` is similar to `sd_bus_flush_close_unref()`. # Return Value On success, `sd_bus_new()` returns 0 or a positive integer. On failure, it returns a negative errno-style error code. `sd_bus_ref()` always returns the argument. `sd_bus_unref()` and `sd_bus_flush_close_unref()` always return `NULL`. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Memory allocation failed. # History `sd_bus_new()`, `sd_bus_ref()`, and `sd_bus_unref()` were added in version 209. `sd_bus_unrefp()` was added in version 229. `sd_bus_flush_close_unref()` and `sd_bus_flush_close_unrefp()` were added in version 240. `sd_bus_close_unref()` and `sd_bus_close_unrefp()` were added in version 241. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_default_user(3)`, `sd_bus_default_system(3)`, `sd_bus_open_user(3)`, `sd_bus_open_system(3)`, `sd_bus_close(3)` # sd_bus_path_encode systemd sd_bus_path_encode 3 sd_bus_path_encode sd_bus_path_encode_many sd_bus_path_decode sd_bus_path_decode_many Convert an external identifier into an object path and back \#include \ int sd_bus_path_encode const char \* prefix const char \* external_id char \*\* ret_path int sd_bus_path_encode_many char \*\* out const char \* path_template … int sd_bus_path_decode const char \* path const char \* prefix char \*\* ret_external_id int sd_bus_path_decode_many const char \* path const char \* path_template … # Description `sd_bus_path_encode()` and `sd_bus_path_decode()` convert external identifier strings into object paths and back. These functions are useful to map application-specific string identifiers of any kind into bus object paths in a simple, reversible and safe way. `sd_bus_path_encode()` takes a bus path prefix and an external identifier string as arguments, plus a place to store the returned bus path string. The bus path prefix must be a valid bus path, starting with a slash `/`, and not ending in one. The external identifier string may be in any format, may be the empty string, and has no restrictions on the charset — however, it must always be `NUL`-terminated. The returned string will be the concatenation of the bus path prefix plus an escaped version of the external identifier string. This operation may be reversed with `sd_bus_path_decode()`. It is recommended to only use external identifiers that generally require little escaping to be turned into valid bus path identifiers (for example, by sticking to a 7-bit ASCII character set), in order to ensure the resulting bus path is still short and easily processed. `sd_bus_path_decode()` reverses the operation of `sd_bus_path_encode()` and thus regenerates an external identifier string from a bus path. It takes a bus path and a prefix string, plus a place to store the returned external identifier string. If the bus path does not start with the specified prefix, 0 is returned and the returned string is set to `NULL`. Otherwise, the string following the prefix is unescaped and returned in the external identifier string. The escaping used will replace all characters which are invalid in a bus object path by `_`, followed by a hexadecimal value. As a special case, the empty string will be replaced by a lone `_`. `sd_bus_path_encode_many()` works like its counterpart `sd_bus_path_encode()`, but takes a path template as argument and encodes multiple labels according to its embedded directives. For each `%` character found in the template, the caller must provide a string via varargs, which will be encoded and embedded at the position of the `%` character. Any other character in the template is copied verbatim into the encoded path. `sd_bus_path_decode_many()` does the reverse of `sd_bus_path_encode_many()`. It decodes the passed object path according to the given path template. For each `%` character in the template, the caller must provide an output storage (`char **`) via varargs. The decoded label will be stored there. Each `%` character will only match the current label. It will never match across labels. Furthermore, only a single directive is allowed per label. If `NULL` is passed as output storage, the label is verified but not returned to the caller. # Return Value On success, `sd_bus_path_encode()` returns positive or 0, and a valid bus path in the return argument. On success, `sd_bus_path_decode()` returns a positive value if the prefixed matched, or 0 if it did not. If the prefix matched, the external identifier is returned in the return parameter. If it did not match, `NULL` is returned in the return parameter. On failure, a negative errno-style error number is returned by either function. The returned strings must be `free(3)`'d by the caller. # History `sd_bus_path_encode()` and `sd_bus_path_decode()` were added in version 211. `sd_bus_path_encode_many()` and `sd_bus_path_decode_many()` were added in version 227. # See Also `systemd(1)`, `sd-bus(3)`, `free(3)` # sd_bus_pending_method_calls systemd sd_bus_pending_method_calls 3 sd_bus_pending_method_calls Return the number of currently pending, outgoing method calls \#include \ int sd_bus_pending_method_calls sd_bus \* bus # Description `sd_bus_pending_method_calls()` returns the number of currently pending outgoing method calls, i.e. method calls enqueued with `sd_bus_call_async(3)` for which no reply has been received yet, and which have not reached a timeout yet. The `bus` argument may be `NULL`, in which case zero is returned. # Return Value This function returns 0 if there are no pending method calls, or a `NULL` bus object was specified. On failure, a negative errno-style error code is returned. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection has been created in a different process, library or module instance. # History `sd_bus_pending_method_calls()` was added in version 257. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_call_async(3)` # sd_bus_process systemd sd_bus_process 3 sd_bus_process Drive the connection \#include \ int sd_bus_process sd_bus \* bus sd_bus_message \*\* ret # Description `sd_bus_process()` drives the connection between the client and the message bus. That is, it handles connecting, authentication, and processing of messages. When invoked, pending I/O work is executed, and queued incoming messages are dispatched to registered callbacks. Each time it is invoked a single operation is executed. It returns zero when no operations were pending and positive if a message was processed. When zero is returned the caller should poll for I/O events before calling into `sd_bus_process()` again. For that either use the simple, blocking `sd_bus_wait(3)` call, or hook up the bus connection object to an external or manual event loop using `sd_bus_get_fd(3)`. `sd_bus_process()` processes at most one incoming message per call. If the parameter `ret` is not `NULL` and the call processed a message, `*ret` is set to this message. The caller owns a reference to this message and should call `sd_bus_message_unref(3)` when the message is no longer needed. If `ret` is not `NULL` and progress was made, but no message was processed, `*ret` is set to `NULL`. Note that only messages not already handled by the various types of registered message handlers (i.e. by filters registered via `sd_bus_add_filter(3)`, object handlers registered via `sd_bus_add_object(3)`, matches registered via `sd_bus_add_match(3)`, and related) will be returned through this parameter. Also note that if such a message handler returns a zero return value (as opposed to some value \> 0) an incoming message will not be considered handled, and be passed to other suitable handlers (until one returns \> \> 0), or returned by `sd_bus_process()` (in case none returns \> 0). If the bus object is connected to an `sd-event(3)` event loop (with `sd_bus_attach_event(3)`), it is not necessary to call `sd_bus_process()` directly as it is invoked automatically when necessary. # Return Value If progress was made, a positive integer is returned. If no progress was made, 0 is returned. If an error occurs, a negative `errno`-style error code is returned. ## Errors Returned errors may indicate the following problems: `-EINVAL` An invalid bus object was passed. `-ECHILD` The bus connection was allocated in a parent process and is being reused in a child process after `fork()`. `-ENOTCONN` The bus connection has been terminated already. `-ECONNRESET` The bus connection has been terminated just now. `-EBUSY` This function is already being called, i.e. `sd_bus_process()` has been called from a callback function that itself was called by `sd_bus_process()`. # History `sd_bus_process()` was added in version 221. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_wait(3)`, `sd_bus_get_fd(3)`, `sd_bus_message_unref(3)`, `sd-event(3)`, `sd_bus_attach_event(3)` # sd_bus_query_sender_creds systemd sd_bus_query_sender_creds 3 sd_bus_query_sender_creds sd_bus_query_sender_privilege Query bus message sender credentials/privileges \#include \ int sd_bus_query_sender_creds sd_bus_message \* m uint64_t mask sd_bus_creds \*\* creds sd_bus_error\* sd_bus_query_sender_privilege sd_bus_message \* m int capability # Description `sd_bus_query_sender_creds()` returns the credentials of the message `m`. The `mask` parameter is a combo of `SD_BUS_CREDS_*` flags that indicate which credential info the caller is interested in. See `sd_bus_creds_new_from_pid(3)` for a list of possible flags. First, this message checks if the requested credentials are attached to the message itself. If not, but the message contains the pid of the sender and the caller specified the `SD_BUS_CREDS_AUGMENT` flag, this function tries to figure out the missing credentials via other means (starting from the pid). If the PID is not available but the message has a sender, this function calls `sd_bus_get_name_creds(3)` to get the requested credentials. If the message has no sender (when a direct connection is used), this function calls `sd_bus_get_owner_creds(3)` to get the requested credentials. On success, the requested credentials are stored in `creds`. Ownership of the credentials object in `creds` is transferred to the caller and should be freed by calling `sd_bus_creds_unref(3)`. `sd_bus_query_sender_privilege()` checks if the message `m` has the requested privileges. If `capability` is a non-negative integer, this function checks if the message has the capability with the same value. See `capabilities(7)` for a list of capabilities. If `capability` is a negative integer, this function returns whether the sender of the message runs as the same user as the receiver of the message, or if the sender of the message runs as root and the receiver of the message does not run as root. On success and if the message has the requested privileges, this function returns a positive integer. If the message does not have the requested privileges, this function returns zero. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The message `m` or an output parameter is `NULL`. `-ENOTCONN` The bus of `m` is not connected. `-ECHILD` The bus of `m` was created in a different process, library or module instance. `-EPERM` The message `m` is not sealed. # History `sd_bus_query_sender_creds()` and `sd_bus_query_sender_privilege()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_creds_new_from_pid(3)`, `sd_bus_get_name_creds(3)`, `sd_bus_get_owner_creds(3)`, `sd_bus_creds_unref(3)`, `capabilities(7)` # sd_bus_reply_method_error systemd sd_bus_reply_method_error 3 sd_bus_reply_method_error sd_bus_reply_method_errorf sd_bus_reply_method_errorfv sd_bus_reply_method_errno sd_bus_reply_method_errnof sd_bus_reply_method_errnofv Reply with an error to a D-Bus method call \#include \ int sd_bus_reply_method_error sd_bus_message \* call const sd_bus_error \* e int sd_bus_reply_method_errorf sd_bus_message \* call const char \* name const char \* format ... int sd_bus_reply_method_errorfv sd_bus_message \* call const char \* name const char \* format va_list ap int sd_bus_reply_method_errno sd_bus_message \* call int error const sd_bus_error \* p int sd_bus_reply_method_errnof sd_bus_message \* call int error const char \* format ... int sd_bus_reply_method_errnofv sd_bus_message \* call int error const char \* format va_list ap # Description The `sd_bus_reply_method_error()` function sends an error reply to the `call` message. The error structure `e` specifies the error to send, and is used as described in `sd_bus_message_new_method_error(3)`. If no reply is expected to `call`, this function succeeds without sending a reply. The `sd_bus_reply_method_errorf()` is to `sd_bus_reply_method_error()` what `sd_bus_message_new_method_errorf()` is to `sd_bus_message_new_method_error()`. The `sd_bus_reply_method_errno()` is to `sd_bus_reply_method_error()` what `sd_bus_message_new_method_errno()` is to `sd_bus_message_new_method_error()`. The `sd_bus_reply_method_errnof()` is to `sd_bus_reply_method_error()` what `sd_bus_message_new_method_errnof()` is to `sd_bus_message_new_method_error()`. # Return Value This function returns a non-negative integer if the error reply was successfully sent or if `call` does not expect a reply. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The input parameter `call` is `NULL`. Message `call` is not a method call message. Message `call` is not attached to a bus. The error parameter `e` to `sd_bus_reply_method_error()` is not set, see `sd_bus_error_is_set(3)`. `-EPERM` Message `call` has been sealed. `-ENOTCONN` The bus to which message `call` is attached is not connected. `-ENOMEM` Memory allocation failed. In addition, any error returned by `sd_bus_send(3)` may be returned. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_new_method_error(3)` # sd_bus_reply_method_return systemd sd_bus_reply_method_return 3 sd_bus_reply_method_return sd_bus_reply_method_returnv Reply to a D-Bus method call \#include \ int sd_bus_reply_method_return sd_bus_message \* call const char \* types ... int sd_bus_reply_method_returnv sd_bus_message \* call const char \* types va_list ap # Description `sd_bus_reply_method_return()` sends a reply to the `call` message. The type string `types` and the arguments that follow it must adhere to the format described in `sd_bus_message_append(3)`. If no reply is expected to `call`, this function succeeds without sending a reply. # Return Value On success, this function returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The input parameter `call` is `NULL`. Message `call` is not a method call message. Message `call` is not attached to a bus. Message `m` is not a method reply message. `-EPERM` Message `call` has been sealed. `-ENOTCONN` The bus to which message `call` is attached is not connected. `-ENOMEM` Memory allocation failed. In addition, any error returned by `sd_bus_send(3)` may be returned. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_new_method_return(3)` # sd_bus_request_name systemd sd_bus_request_name 3 sd_bus_request_name sd_bus_request_name_async sd_bus_release_name sd_bus_release_name_async Request or release a well-known service name on a bus \#include \ int sd_bus_request_name sd_bus \* bus const char \* name uint64_t flags int sd_bus_request_name_async sd_bus \* bus sd_bus_slot \*\* slot const char \* name uint64_t flags sd_bus_message_handler_t callback void \* userdata int sd_bus_release_name sd_bus \* bus const char \* name int sd_bus_release_name_async sd_bus \* bus sd_bus_slot \*\* slot const char \* name sd_bus_message_handler_t callback void \* userdata # Description `sd_bus_request_name()` requests a well-known service name on a bus. It takes a bus connection, a valid bus name, and a flags parameter. The flags parameter is a combination of zero or more of the following flags: `SD_BUS_NAME_ALLOW_REPLACEMENT` After acquiring the name successfully, permit other peers to take over the name when they try to acquire it with the `SD_BUS_NAME_REPLACE_EXISTING` flag set. If `SD_BUS_NAME_ALLOW_REPLACEMENT` is not set on the original request, such a request by other peers will be denied. `SD_BUS_NAME_REPLACE_EXISTING` Take over the name if it was already acquired by another peer, and that other peer has permitted takeover by setting `SD_BUS_NAME_ALLOW_REPLACEMENT` while acquiring it. `SD_BUS_NAME_QUEUE` Queue the acquisition of the name when the name is already taken. `sd_bus_request_name()` operates in a synchronous fashion: a message requesting the name is sent to the bus broker, and the call waits until the broker responds. `sd_bus_request_name_async()` is an asynchronous version of `sd_bus_request_name()`. Instead of waiting for the request to complete, the request message is enqueued. The specified `callback` will be called when the broker's response is received. If the parameter is specified as `NULL` a default implementation is used instead which will terminate the connection when the name cannot be acquired. The function returns a slot object in its `slot` parameter — if it is passed as non-`NULL` — which may be used as a reference to the name request operation. Use `sd_bus_slot_unref(3)` to destroy this reference. Note that destroying the reference will not unregister the name, but simply ensure the specified callback is no longer called. `sd_bus_release_name()` releases an acquired well-known name. It takes a bus connection and a valid bus name as parameters. This function operates synchronously, sending a release request message to the bus broker and waiting for it to reply. `sd_bus_release_name_async()` is an asynchronous version of `sd_bus_release_name()`. The specified `callback` function is called when the name has been released successfully. If specified as `NULL` a generic implementation is used that ignores the result of the operation. As above, the `slot` (if non-`NULL`) is set to an object that may be used to reference the operation. These functions are supported only on bus connections, i.e. connections to a bus broker and not on direct connections. # Return Value On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style error code. If `SD_BUS_NAME_QUEUE` is specified, `sd_bus_request_name()` will return 0 when the name is already taken by another peer and the client has been added to the queue for the name. In that case, the caller can subscribe to `NameOwnerChanged` signals to be notified when the name is successfully acquired. `sd_bus_request_name()` returns \> 0 when the name has immediately been acquired successfully. ## Errors Returned errors may indicate the following problems: `-EALREADY` The caller already is the owner of the specified name. `-EEXIST` The name has already been acquired by a different peer, and SD_BUS_NAME_REPLACE_EXISTING was not specified or the other peer did not specify SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the name. `-ESRCH` It was attempted to release a name that is currently not registered on the bus. `-EADDRINUSE` It was attempted to release a name that is owned by a different peer on the bus. `-EINVAL` A specified parameter is invalid. This is also generated when the requested name is a special service name reserved by the D-Bus specification, or when the operation is requested on a connection that does not refer to a bus. `-ENOTCONN` The bus connection has been disconnected. `-ECHILD` The bus connection has been created in a different process than the current one. # History `sd_bus_request_name()` and `sd_bus_release_name()` were added in version 209. `sd_bus_request_name_async()` and `sd_bus_release_name_async()` were added in version 237. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_new(3)`, `sd_bus_slot_unref(3)` # sd_bus_send systemd sd_bus_send 3 sd_bus_send sd_bus_send_to sd_bus_message_send Queue a D-Bus message for transfer \#include \ int sd_bus_send sd_bus \* bus sd_bus_message \* m uint64_t \* cookie int sd_bus_send_to sd_bus \* bus sd_bus_message \* m const char \* destination uint64_t \* cookie int sd_bus_message_send sd_bus_message \* m # Description `sd_bus_send()` queues the bus message object `m` for transfer. If `bus` is `NULL`, the bus that `m` is attached to is used. `bus` only needs to be set when the message is sent to a different bus than the one it is attached to, for example when forwarding messages. If the output parameter `cookie` is not `NULL`, it is set to the message identifier. This value can later be used to match incoming replies to their corresponding messages. If `cookie` is set to `NULL` and the message is not sealed, `sd_bus_send()` assumes the message `m` does not expect a reply and adds the necessary headers to indicate this. Note that in most scenarios, `sd_bus_send()` should not be called directly. Instead, use higher level functions such as `sd_bus_call_method(3)` and `sd_bus_reply_method_return(3)` which call `sd_bus_send()` internally. `sd_bus_send_to()` is a shorthand for sending a message to a specific destination. It's main use case is to simplify sending unicast signal messages (signals that only have a single receiver). It's behavior is similar to calling `sd_bus_message_set_destination(3)` followed by calling `sd_bus_send()`. `sd_bus_send()`/`sd_bus_send_to()` will write the message directly to the underlying transport (e.g. kernel socket buffer) if possible. If the connection is not set up fully yet the message is queued locally. If the transport buffers are congested any unwritten message data is queued locally, too. If the connection has been closed or is currently being closed the call fails. `sd_bus_process(3)` should be invoked to write out any queued message data to the transport. `sd_bus_message_send()` is the same as `sd_bus_send()` but without the first and last argument. `sd_bus_message_send(m)` is equivalent to `sd_bus_send(sd_bus_message_get_bus(m), m, NULL)`. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The input parameter `m` is `NULL`. `-EOPNOTSUPP` The bus connection does not support sending file descriptors. `-ECHILD` The bus connection was allocated in a parent process and is being reused in a child process after `fork()`. `-ENOBUFS` The bus connection's write queue is full. `-ENOTCONN` The input parameter `bus` is `NULL` or the bus is not connected. `-ECONNRESET` The bus connection was closed while waiting for the response. `-ENOMEM` Memory allocation failed. # History `sd_bus_send()` and `sd_bus_send_to()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_call_method(3)`, `sd_bus_message_set_destination(3)`, `sd_bus_reply_method_return(3)`, `sd_bus_process(3)` # sd_bus_set_address systemd sd_bus_set_address 3 sd_bus_set_address sd_bus_get_address sd_bus_set_exec Set or query the address of the bus connection \#include \ int sd_bus_set_address sd_bus \* bus const char \* address int sd_bus_get_address sd_bus \* bus const char \*\* address int sd_bus_set_exec sd_bus \* bus const char \* path char \*const \* argv # Description `sd_bus_set_address()` configures a list of addresses of bus brokers to try to connect to from a subsequent `sd_bus_start(3)` call. The argument is a `;`-separated list of addresses to try. Each item must be one of the following: - A unix socket address specified as `unix:guid=guid,path=path` or `unix:guid=guid,abstract=path`. Exactly one of the `path=` and `abstract=` keys must be present, while `guid=` is optional. - A TCP socket address specified as `tcp:[guid=guid,][host=host][,port=port][,family=family]`. One or both of the `host=` and `port=` keys must be present, while the rest is optional. \ may be either `ipv4` or `ipv6`. Note: *connections over TCP are made without encryption*. Thus, this mode should only be used in specific situations where integrity and confidentiality of the connection is not necessary or is ensured through some other means. For local connections, `unix:` connections should be used instead. - An executable to spawn specified as `unixexec:guid=guid,path=path,argv1=argument,argv2=argument,...`. The `path=` key must be present, while `guid=` is optional. - A machine (container) to connect to specified as `x-machine-unix:guid=guid,machine=machine,pid=pid`. Exactly one of the `machine=` and `pid=` keys must be present, while `guid=` is optional. `machine` is the name of a local container. See `machinectl(1)` for more information about the "machine" concept. `machine=.host` may be used to specify the host machine. A connection to the standard system bus socket inside of the specified machine will be created. In all cases, parameter `guid` is an identifier of the remote peer, in the syntax accepted by `sd_id128_from_string(3)`. If specified, the identifier returned by the peer after the connection is established will be checked and the connection will be rejected in case of a mismatch. Note that the addresses passed to `sd_bus_set_address()` might not be verified immediately. If they are invalid, an error may be returned e.g. from a subsequent call to `sd_bus_start(3)`. `sd_bus_get_address()` returns any previously set addresses. In addition to being explicitly set by `sd_bus_set_address()`, the address will also be set automatically by `sd_bus_open(3)` and similar calls, based on environment variables or built-in defaults. `sd_bus_set_exec()` is a shorthand function for setting a `unixexec` address that spawns the given executable with the given arguments. If `argv` is `NULL`, the given executable is spawned without any extra arguments. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The input parameters `bus` or `address` are `NULL`. `-ENOPKG` The bus object `bus` could not be resolved. `-EPERM` The input parameter `bus` is in a wrong state (`sd_bus_set_address()` may only be called once on a newly-created bus object). `-ECHILD` The bus object `bus` was created in a different process. `-ENODATA` The bus object `bus` has no address configured. # History `sd_bus_set_address()`, `sd_bus_get_address()`, and `sd_bus_set_exec()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_new(3)`, `sd_bus_start(3)`, `systemd-machined.service(8)`, `machinectl(1)` # sd_bus_set_close_on_exit systemd sd_bus_set_close_on_exit 3 sd_bus_set_close_on_exit sd_bus_get_close_on_exit Control whether to close the bus connection during the event loop exit phase \#include \ int sd_bus_set_close_on_exit sd_bus \* bus int b int sd_bus_get_close_on_exit sd_bus \* bus # Description `sd_bus_set_close_on_exit()` may be used to enable or disable whether the bus connection is automatically flushed (as in `sd_bus_flush(3)`) and closed (as in `sd_bus_close(3)`) during the exit phase of the event loop. This logic only applies to bus connections that are attached to an `sd-event(3)` event loop, see `sd_bus_attach_event(3)`. By default, this mechanism is enabled and makes sure that any pending messages that have not been written to the bus connection are written out when the event loop is shutting down. In some cases this behaviour is not desirable, for example when the bus connection shall remain usable until after the event loop exited. If `b` is true, the feature is enabled (which is the default), otherwise disabled. `sd_bus_get_close_on_exit()` may be used to query the current setting of this feature. It returns zero when the feature is disabled, and positive if enabled. # Return Value On success, `sd_bus_set_close_on_exit()` returns a non-negative integer. On failure, it returns a negative errno-style error code. `sd_bus_get_close_on_exit()` returns 0 if the feature is currently disabled or a positive integer if it is enabled. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection was created in a different process, library or module instance. # History `sd_bus_set_close_on_exit()` and `sd_bus_get_close_on_exit()` were added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_flush(3)`, `sd_bus_attach_event(3)`, `sd-event(3)`, `sd_event_add_exit(3)` # sd_bus_set_connected_signal systemd sd_bus_set_connected_signal 3 sd_bus_set_connected_signal sd_bus_get_connected_signal Control emission of local connection establishment signal on bus connections \#include \ int sd_bus_set_connected_signal sd_bus \* bus int b int sd_bus_get_connected_signal sd_bus \* bus # Description `sd_bus_set_connected_signal()` may be used to control whether a local, synthetic `Connected()` signal message shall be generated and enqueued for dispatching when the connection is fully established. If the `b` parameter is zero the message is not generated (the default), otherwise it is generated. `sd_bus_get_connected_signal()` may be used to query whether this feature is enabled. It returns zero if not, positive otherwise. The `Connected()` signal message is generated from the `org.freedesktop.DBus.Local` service and interface, and `/org/freedesktop/DBus/Local` object path. Use `sd_bus_match_signal_async(3)` to match on this signal. This message is particularly useful on slow transports where connections take a long time to be established. This is especially the case when `sd_bus_set_watch_bind(3)` is used. The signal is generated when the `sd_bus_is_ready(3)` returns positive for the first time. The `Connected()` signal corresponds with the `Disconnected()` signal that is synthesized locally when the connection is terminated. The latter is generated unconditionally however, unlike the former which needs to be enabled explicitly before it is generated, with `sd_bus_set_connected_signal()`. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection has been created in a different process, library or module instance. # History `sd_bus_set_connected_signal()` and `sd_bus_get_connected_signal()` were added in version 237. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_match_signal_async(3)`, `sd_bus_set_watch_bind(3)`, `sd_bus_is_ready(3)` # sd_bus_set_description systemd sd_bus_set_description 3 sd_bus_set_description sd_bus_get_description sd_bus_set_anonymous sd_bus_is_anonymous sd_bus_set_trusted sd_bus_is_trusted sd_bus_set_allow_interactive_authorization sd_bus_get_allow_interactive_authorization sd_bus_get_scope sd_bus_get_tid sd_bus_get_unique_name Set or query properties of a bus object \#include \ int sd_bus_set_description sd_bus \* bus const char \* description int sd_bus_get_description sd_bus \* bus const char \*\* description int sd_bus_set_anonymous sd_bus \* bus int b int sd_bus_is_anonymous sd_bus \* bus int sd_bus_set_trusted sd_bus \* bus int b int sd_bus_is_trusted sd_bus \* bus int sd_bus_set_allow_interactive_authorization sd_bus \* bus int b int sd_bus_get_allow_interactive_authorization sd_bus \* bus int sd_bus_get_scope sd_bus \* bus const char \*\* scope int sd_bus_get_tid sd_bus \* bus pid_t \* tid int sd_bus_get_unique_name sd_bus \* bus const char \*\* unique # Description `sd_bus_set_description()` sets the description string that is used in logging to the specified string. The string is copied internally and freed when the bus object is deallocated. The `description` argument may be `NULL`, in which case the description is unset. This function must be called before the bus is started. `sd_bus_get_description()` returns a description string in `description`. This string may have been previously set with `sd_bus_set_description()` or `sd_bus_open_with_description(3)` or similar. If not set this way, a default string like `system` or `user` will be returned for the system or user buses, and `-ENXIO` otherwise. `sd_bus_set_anonymous()` enables or disables "anonymous authentication", i.e. lack of authentication, of the bus peer. This function must be called before the bus is started. See the [ D-Bus Authentication Mechanisms](view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms) section of the D-Bus specification for details. `sd_bus_is_anonymous()` returns true if the bus connection allows anonymous authentication (in the sense described in previous paragraph). `sd_bus_set_trusted()` sets the "trusted" state on the `bus` object. If true, all connections on the bus are trusted and access to all privileged and unprivileged methods is granted. This function must be called before the bus is started. `sd_bus_is_trusted()` returns true if the bus connection is trusted (in the sense described in previous paragraph). `sd_bus_set_allow_interactive_authorization()` enables or disables interactive authorization for method calls. If true, messages are marked with the `ALLOW_INTERACTIVE_AUTHORIZATION` flag specified by the [D-Bus](view-source:https://dbus.freedesktop.org/doc/dbus-specification.html) specification, informing the receiving side that the caller is prepared to wait for interactive authorization, which might take a considerable time to complete. If this flag is set, the user may be queried for passwords or confirmation via [polkit](https://www.freedesktop.org/wiki/Software/polkit) or a similar framework. `sd_bus_get_allow_interactive_authorization()` returns true if interactive authorization is allowed and false if not. `sd_bus_get_scope()` stores the scope of the given bus object in `scope`. The scope of the system bus is `system`. The scope of a user session bus is `user`. If the given bus object is not the system or a user session bus, `sd_bus_get_scope()` returns an error. `sd_bus_get_tid()` stores the kernel thread id of the thread associated with the given bus object in `tid`. If `bus` is a default bus object obtained by calling one of the functions of the `sd_bus_default(3)` family of functions, it stores the thread id of the thread the bus object was created in. Otherwise, if the bus object is attached to an event loop, it stores the thread id of the thread the event loop object was created in. If `bus` is not a default bus object and is not attached to an event loop, `sd_bus_get_tid()` returns an error. `sd_bus_get_unique_name()` stores the unique name of the bus object on the bus in `unique`. See [ The D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus) for more information on bus names. Note that the caller does not own the string stored in `unique` and should not free it. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. `-ENOPKG` The bus cannot be resolved. `-EPERM` The bus has already been started. `-ECHILD` The bus was created in a different process, library or module instance. `-ENOMEM` Memory allocation failed. `-ENODATA` The bus object passed to `sd_bus_get_scope()` was not a system or user session bus. `-ENXIO` The bus object passed to `sd_bus_get_tid()` was not a default bus object and is not attached to an event loop. The bus object passed to `sd_bus_get_description()` did not have a `description`. # History `sd_bus_set_description()`, `sd_bus_get_description()`, `sd_bus_set_anonymous()`, `sd_bus_set_trusted()`, `sd_bus_set_allow_interactive_authorization()`, and `sd_bus_get_allow_interactive_authorization()` were added in version 240. `sd_bus_is_anonymous()`, `sd_bus_is_trusted()`, `sd_bus_get_scope()`, `sd_bus_get_tid()`, and `sd_bus_get_unique_name()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_default_user(3)`, `sd_bus_default_system(3)`, `sd_bus_open_user(3)`, `sd_bus_open_system(3)` # sd_bus_set_exit_on_disconnect systemd sd_bus_set_exit_on_disconnect 3 sd_bus_set_exit_on_disconnect sd_bus_get_exit_on_disconnect Control the exit behavior when the bus object disconnects \#include \ int sd_bus_set_exit_on_disconnect sd_bus \* bus int b int sd_bus_get_exit_on_disconnect sd_bus \* bus # Description `sd_bus_set_exit_on_disconnect()` may be used to configure the exit behavior when the given bus object disconnects. If `b` is zero, no special logic is executed when the bus object disconnects. If `b` is non-zero, the behavior on disconnect depends on whether the bus object is attached to an event loop or not. If the bus object is attached to an event loop (see `sd_bus_attach_event(3)`), the event loop is closed when the bus object disconnects (as if calling `sd_event_exit(3)`). Otherwise, `exit(3)` is called. The exit code passed to `sd_event_exit()` and `exit()` is `EXIT_FAILURE`. If the bus object has already disconnected when enabling the exit behavior, the exit behavior is executed immediately. By default, the exit behavior is disabled. `sd_bus_get_exit_on_disconnect()` returns whether the exit on disconnect behavior is enabled for the given bus object. # Return Value On success, `sd_bus_set_exit_on_disconnect()` returns a non-negative integer. On failure, it returns a negative errno-style error code. `sd_bus_get_exit_on_disconnect()` returns a positive integer if the exit on disconnect behavior is enabled. Otherwise, it returns zero. ## Errors Returned errors may indicate the following problems: `-EINVAL` A required parameter was `NULL`. `-ENOPKG` The bus object could not be resolved. `-ECHILD` The bus connection was created in a different process, library or module instance. # History `sd_bus_set_exit_on_disconnect()` and `sd_bus_get_exit_on_disconnect()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_attach_event(3)`, `sd-event(3)`, `sd_event_exit(3)` # sd_bus_set_fd systemd sd_bus_set_fd 3 sd_bus_set_fd Set the file descriptors to use for bus communication \#include \ int sd_bus_set_fd sd_bus \* bus int input_fd int output_fd # Description `sd_bus_set_fd()` sets the file descriptors used to communicate by a bus connection object. Both `input_fd` and `output_fd` must be valid file descriptors, referring to stream-based file objects (e.g. a stream socket, a pair of pipes or FIFOs, or even a TTY device). `input_fd` must be readable, and `output_fd` must be writable. The same file descriptor may be used (and typically is used) as both the input and the output file descriptor. This function must be called before the bus connection is started via `sd_bus_start(3)`. The bus connection object will take possession of the passed file descriptors and will close them automatically when it is freed. Use `sd_bus_set_close_on_exit(3)` to turn off this behaviour. # Return Value On success, `sd_bus_set_fd()` returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An invalid bus object was passed. `-ECHILD` The bus connection was allocated in a parent process and is being reused in a child process after `fork()`. `-EBADF` An invalid file descriptor was passed to `sd_bus_set_fd()`. `-ENOPKG` The bus cannot be resolved. `-EPERM` The bus connection has already been started. # History `sd_bus_set_fd()` was added in version 248. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_get_fd(3)`, `sd_bus_start(3)` # sd_bus_set_method_call_timeout systemd sd_bus_set_method_call_timeout 3 sd_bus_set_method_call_timeout sd_bus_get_method_call_timeout Set or query the default D-Bus method call timeout of a bus object \#include \ int sd_bus_set_method_call_timeout sd_bus \* bus uint64_t usec int sd_bus_get_method_call_timeout sd_bus \* bus uint64_t \* ret # Description `sd_bus_set_method_call_timeout()` sets the default D-Bus method call timeout of `bus` to `usec` microseconds. `sd_bus_get_method_call_timeout()` queries the default D-Bus method call timeout of `bus`. If no method call timeout was set using `sd_bus_set_method_call_timeout()`, the timeout is read from the `$SYSTEMD_BUS_TIMEOUT` environment variable. If this environment variable is unset or does not contain a valid timeout, the implementation falls back to a predefined method call timeout of 25 seconds. Note that `$SYSTEMD_BUS_TIMEOUT` is read once and cached so callers should not rely on being able to change the default method call timeout at runtime by changing the value of `$SYSTEMD_BUS_TIMEOUT`. Instead, call `sd_bus_set_method_call_timeout()` to change the default method call timeout. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The parameters `bus` or `ret` are `NULL`. `-ENOPKG` Bus object `bus` could not be resolved. # History `sd_bus_set_method_call_timeout()` and `sd_bus_get_method_call_timeout()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_call(3)` # sd_bus_set_property systemd sd_bus_set_property 3 sd_bus_set_property sd_bus_set_propertyv sd_bus_get_property sd_bus_get_property_trivial sd_bus_get_property_string sd_bus_get_property_strv Set or query D-Bus service properties \#include \ int sd_bus_set_property sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member sd_bus_error \* ret_error const char \* type ... int sd_bus_set_propertyv sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member sd_bus_error \* ret_error const char \* type va_list ap int sd_bus_get_property sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member sd_bus_error \* ret_error sd_bus_message \*\* reply const char \* type int sd_bus_get_property_trivial sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member sd_bus_error \* ret_error char type void \* ret_ptr int sd_bus_get_property_string sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member sd_bus_error \* ret_error char \*\* ret int sd_bus_get_property_strv sd_bus \* bus const char \* destination const char \* path const char \* interface const char \* member sd_bus_error \* ret_error char \*\*\* ret # Description These functions set or query D-Bus properties. D-Bus properties are service fields exposed via the `org.freedesktop.DBus.Properties` interface. Under the hood, these functions call methods of the `org.freedesktop.DBus.Properties` interface and as a result their semantics are similar to `sd_bus_call_method(3)`. `sd_bus_set_property()` sets a D-Bus property. If setting the property fails or an internal error occurs, an error is returned and an extended description of the error is optionally stored in `ret_error` if it is not `NULL`. `type` and the arguments that follow it describe the new value of the property and must follow the format described in `sd_bus_message_append(3)`. `sd_bus_set_propertyv()` is equivalent to `sd_bus_set_property()`, except that it is called with a `va_list` instead of a variable number of arguments. `sd_bus_get_property()` queries a D-Bus property. If retrieving the property fails or an internal error occurs, an error is returned and an extended description of the error is optionally stored in `ret_error` if it is not `NULL`. On success, the property is stored in `reply`. `type` describes the property type and must follow the format described in `sd_bus_message_append(3)`. `sd_bus_get_property_trivial()`, `sd_bus_get_property_string()` and `sd_bus_get_property_strv()` are shorthands for `sd_bus_get_property()` that are used to query basic, string and string vector properties respectively. The caller is responsible for freeing the string and string vector results stored in `ret` by `sd_bus_get_property_string()` and `sd_bus_get_property_strv()`. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors See the `sd_bus_call_method(3)` man page for a list of possible errors. # History `sd_bus_set_property()`, `sd_bus_set_propertyv()`, `sd_bus_get_property()`, `sd_bus_get_property_trivial()`, `sd_bus_get_property_string()`, and `sd_bus_get_property_strv()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_call_method(3)` # sd_bus_set_sender systemd sd_bus_set_sender 3 sd_bus_set_sender sd_bus_get_sender Configure default sender for outgoing messages \#include \ int sd_bus_set_sender sd_bus \* bus const char\* name int sd_bus_get_sender sd_bus \* bus const char\*\* name # Description `sd_bus_set_sender()` configures the default sender service name to use for outgoing messages. The service name specified in the `name` parameter is set on all outgoing messages that are sent on the connection and have no sender set yet, for example through `sd_bus_message_set_sender(3)`. Note that this function is only supported on direct connections, i.e. not on connections to a bus broker as the broker will fill in the sender service name automatically anyway. By default, no sender name is configured, and hence messages are sent without sender field set. If the `name` parameter is specified as `NULL` the default sender service name is cleared, returning to the default state if a default sender service name was set before. If passed as non-`NULL` the specified name must be a valid unique or well-known service name. `sd_bus_get_sender()` may be used to query the current default service name for outgoing messages. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection has been created in a different process, library or module instance. `-EPERM` The specified bus connection object is a not a direct but a brokered connection. # History `sd_bus_set_sender()` and `sd_bus_get_sender()` were added in version 237. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_message_set_sender(3)` # sd_bus_set_server systemd sd_bus_set_server 3 sd_bus_set_server sd_bus_is_server sd_bus_get_bus_id sd_bus_set_bus_client sd_bus_is_bus_client sd_bus_set_monitor sd_bus_is_monitor Configure connection mode for a bus object \#include \ int sd_bus_set_server sd_bus \* bus int b sd_id128_t id int sd_bus_is_server sd_bus \* bus int sd_bus_get_bus_id sd_bus \* bus sd_id128_t \* id int sd_bus_set_bus_client sd_bus \* bus int b int sd_bus_is_bus_client sd_bus \* bus int sd_bus_set_monitor sd_bus \* bus int b int sd_bus_is_monitor sd_bus \* bus # Description `sd_bus_set_server()` configures the bus object as a server for direct D-Bus connections. `b` enables/disables the server mode. If zero, the server mode is disabled. Otherwise, the server mode is enabled. Configuring a bus object as a server is required to allow establishing direct connections between two peers without going via the D-Bus daemon. `id` must contain a 128-bit integer id for the server. If clients add a guid field to their D-Bus address string, the server id must match this guid or the D-Bus authentication handshake will fail. If no specific id is defined for the server, `sd_id128_randomize(3)` can be used to generate a random id instead. `sd_bus_is_server()` returns whether the server mode is enabled for the given bus object. `sd_bus_get_bus_id()` stores the D-Bus server id configured using `sd_bus_set_server()` (for server bus objects) or received during D-Bus authentication (for client bus objects) in `id`. `sd_bus_set_bus_client()` configures the bus object as a D-Bus daemon client. `b` enables/disables the client mode. If zero, the client mode is disabled and the bus object should connect directly to a D-Bus server. Otherwise, the client mode is enabled and the bus object should connect to a D-Bus daemon. When connecting to an existing bus using any of the functions in the `sd_bus_open(3)` family of functions or any of the functions in the `sd_bus_default(3)` family of functions, the bus object is automatically configured as a bus client. However, when connecting to a D-Bus daemon by calling `sd_bus_set_address(3)` followed by `sd_bus_start(3)`, the bus object should be manually configured as a bus client using `sd_bus_set_bus_client()`. By default, a bus object is not configured as a D-Bus daemon client. `sd_bus_is_bus_client()` returns whether the client mode is enabled/disabled for the given bus object. `sd_bus_set_monitor()` configures the bus object as a D-Bus monitor object. `b` enables/disables the monitor mode. If zero, the monitor mode is disabled. If non-zero, the monitor mode is enabled. When the monitor mode is enabled, no messages may be sent via the bus object and it may not expose any objects on the bus. To start monitoring messages, call the `org.freedesktop.DBus.Monitoring.BecomeMonitor` method of the D-Bus daemon and pass a list of matches indicating which messages to intercept. See [ The D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-become-monitor) for more information. `sd_bus_is_monitor()` returns whether the monitor mode is enabled/disabled for the given bus object. # Return Value On success, `sd_bus_set_server()`, `sd_bus_get_bus_id()`, `sd_bus_set_bus_client()` and `sd_bus_set_monitor()` return a non-negative integer. On failure, they return a negative errno-style error code. `sd_bus_is_server()`, `sd_bus_is_bus_client()` and `sd_bus_is_monitor()` return a positive integer when the server or client mode is enabled, respectively. Otherwise, they return zero. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection has been created in a different process, library or module instance. `-EPERM` The bus connection has already been started. `-ENOPKG` The bus cannot be resolved. `-EINVAL` A required parameter was `NULL` or `b` was zero and `id` did not equal `SD_ID128_NULL`. `-ENOTCONN` The bus is not connected. # History `sd_bus_set_server()`, `sd_bus_is_server()`, `sd_bus_get_bus_id()`, `sd_bus_set_bus_client()`, `sd_bus_is_bus_client()`, `sd_bus_set_monitor()`, and `sd_bus_is_monitor()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)` # sd_bus_set_watch_bind systemd sd_bus_set_watch_bind 3 sd_bus_set_watch_bind sd_bus_get_watch_bind Control socket binding watching on bus connections \#include \ int sd_bus_set_watch_bind sd_bus \* bus int b int sd_bus_get_watch_bind sd_bus \* bus # Description `sd_bus_set_watch_bind()` may be used to enable or disable client-side watching of server socket binding for a bus connection object. If `b` is true, the feature is enabled, otherwise disabled (which is the default). When enabled, and the selected bus address refers to an `AF_UNIX` socket in the file system which does not exist while the connection attempt is made, an `inotify(7)` watch is installed on it, waiting for the socket to appear. As soon as the socket appears the connection is made. This functionality is useful in particular in early-boot programs that need to run before the system bus is available, but want to connect to it the instant it may be connected to. `sd_bus_get_watch_bind()` may be used to query the current setting of this feature. It returns zero when the feature is disabled, and positive if enabled. Note that no timeout is applied while we wait for the socket to appear. This means that any synchronous remote operation (such as `sd_bus_call(3)`, `sd_bus_add_match(3)` or `sd_bus_request_name(3)`), that is used on a connection with this feature enabled that has not been established yet, might block forever if the socket is never created. However, asynchronous remote operations (such as `sd_bus_send(3)`, `sd_bus_call_async(3)`, `sd_bus_add_match_async(3)`) do not block in this case, and safely enqueue the requested operations to be dispatched the instant the connection is set up. Use `sd_bus_is_ready(3)` to determine whether the connection is fully established, i.e. whether the peer socket has been bound, connected to and authenticated. Use `sd_bus_set_connected_signal(3)` to be notified when the connection is fully established. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The bus connection has been created in a different process, library or module instance. # Example
Create a simple system service that publishes a property on the system bus and can reconnect when D-Bus disconnects and reconnects
This is particularly useful for services that are configured to survive a soft-reboot, see `systemd-soft-reboot.service(8)` for more details.
# History `sd_bus_set_watch_bind()` and `sd_bus_get_watch_bind()` were added in version 237. # See Also `systemd(1)`, `sd-bus(3)`, `inotify(7)`, `sd_bus_call(3)`, `sd_bus_add_match(3)`, `sd_bus_request_name(3)`, `sd_bus_is_ready(3)`, `sd_bus_set_connected_signal(3)` # sd_bus_slot_get_bus systemd sd_bus_slot_get_bus 3 sd_bus_slot_get_bus sd_bus_slot_get_current_handler sd_bus_slot_get_current_message sd_bus_slot_get_current_userdata Query information attached to a bus slot object \#include \ sd_bus \* sd_bus_slot_get_bus sd_bus_slot \* slot sd_bus_message_handler_t sd_bus_slot_get_current_handler sd_bus_slot \* slot sd_bus_message \* sd_bus_slot_get_current_message sd_bus_slot \* slot void \* sd_bus_slot_get_current_userdata sd_bus_slot \* slot # Description `sd_bus_slot_get_bus()` returns the bus object that message `slot` is attached to. `sd_bus_slot_get_current_handler()`, `sd_bus_slot_get_current_message()` and `sd_bus_slot_get_current_userdata()` return the current handler, message and userdata respectively of the bus `slot` is attached to if we're currently executing the callback associated with `slot`. # Return Value `sd_bus_slot_get_bus()` always returns the bus object. On success, `sd_bus_slot_get_current_handler()`, `sd_bus_slot_get_current_message()` and `sd_bus_slot_get_current_userdata()` return the requested object. On failure, they return `NULL`. # History `sd_bus_slot_get_bus()`, `sd_bus_slot_get_current_handler()`, `sd_bus_slot_get_current_message()`, and `sd_bus_slot_get_current_userdata()` were added in version 246. # See Also `systemd(1)`, `sd-bus(3)` # sd_bus_slot_ref systemd sd_bus_slot_ref 3 sd_bus_slot_ref sd_bus_slot_unref sd_bus_slot_unrefp Create and destroy references to a bus slot object \#include \ sd_bus_slot \* sd_bus_slot_ref sd_bus_slot \* slot sd_bus_slot \* sd_bus_slot_unref sd_bus_slot \* slot void sd_bus_slot_unrefp sd_bus_slot \*\* slotp # Description `sd_bus_slot_ref()` increases the internal reference counter of `slot` by one. `sd_bus_slot_unref()` decreases the internal reference counter of `slot` by one. Once the reference count has dropped to zero, slot object is destroyed and cannot be used anymore, so further calls to `sd_bus_slot_ref()` or `sd_bus_slot_unref()` are illegal. `sd_bus_slot_unrefp()` is similar to `sd_bus_slot_unref()` but takes a pointer to a pointer to an `sd_bus_slot` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). See `sd_bus_new(3)` for an example how to use the cleanup attribute. `sd_bus_slot_ref()` and `sd_bus_slot_unref()` execute no operation if the passed in bus object address is `NULL`. `sd_bus_slot_unrefp()` will first dereference its argument, which must not be `NULL`, and will execute no operation if *that* is `NULL`. # Return Value `sd_bus_slot_ref()` always returns the argument. `sd_bus_slot_unref()` always returns `NULL`. # History `sd_bus_slot_ref()`, `sd_bus_slot_unref()`, and `sd_bus_slot_unrefp()` were added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_new(3)`, `sd_bus_message_new(3)`, `sd_bus_call_method_async(3)` # sd_bus_slot_set_description systemd sd_bus_slot_set_description 3 sd_bus_slot_set_description sd_bus_slot_get_description Set or query the description of bus slot objects \#include \ int sd_bus_slot_set_description sd_bus_slot\* slot const char \* description int sd_bus_slot_get_description sd_bus_slot\* bus const char \*\* description # Description `sd_bus_slot_set_description()` sets the description string that is used in logging to the specified string. The string is copied internally and freed when the bus slot object is deallocated. The `description` argument may be `NULL`, in which case the description is unset. `sd_bus_slot_get_description()` returns a description string in `description`. If the string is not set, e.g. with `sd_bus_slot_set_description()`, and the slot is a bus match callback slot, the match string will be returned. Otherwise, `-ENXIO` is returned. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An required argument is `NULL`. `-ENXIO` The bus slot object has no description. `-ENOMEM` Memory allocation failed. # History `sd_bus_slot_set_description()` and `sd_bus_slot_get_description()` were added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_slot_ref(3)`, `sd_bus_slot_set_userdata(3)` # sd_bus_slot_set_destroy_callback systemd sd_bus_slot_set_destroy_callback 3 sd_bus_slot_set_destroy_callback sd_bus_slot_get_destroy_callback sd_bus_track_set_destroy_callback sd_bus_track_get_destroy_callback sd_bus_destroy_t Define the callback function for resource cleanup \#include \ typedef void (\* sd_bus_destroy_t ) void \* userdata int sd_bus_slot_set_destroy_callback sd_bus_slot \* slot sd_bus_destroy_t callback int sd_bus_slot_get_destroy_callback sd_bus_slot \* slot sd_bus_destroy_t \* callback int sd_bus_track_set_destroy_callback sd_bus_track \* track sd_bus_destroy_t callback int sd_bus_track_get_destroy_callback sd_bus_track \* track sd_bus_destroy_t \* callback # Description `sd_bus_slot_set_destroy_callback()` sets `callback` as the callback function to be called right before the bus slot object `slot` is deallocated. The `userdata` pointer from the slot object will be passed as the `userdata` parameter. This pointer can be set by an argument to the constructor functions, see `sd_bus_add_match(3)`, or directly, see `sd_bus_slot_set_userdata(3)`. This callback function is called even if `userdata` is `NULL`. Note that this callback is invoked at a time where the bus slot object itself is already invalidated, and executing operations or taking new references to the bus slot object is not permissible. `sd_bus_slot_get_destroy_callback()` returns the current callback for `slot` in the `callback` parameter. `sd_bus_track_set_destroy_callback()` and `sd_bus_track_get_destroy_callback()` provide equivalent functionality for the `userdata` pointer associated with bus peer tracking objects. For details about bus peer tracking objects, see `sd_bus_track_new(3)`. # Return Value On success, `sd_bus_slot_set_destroy_callback()` and `sd_bus_track_set_destroy_callback()` return 0 or a positive integer. On failure, they return a negative errno-style error code. `sd_bus_slot_get_destroy_callback()` and `sd_bus_track_get_destroy_callback()` return positive if the destroy callback function is set, 0 if not. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `slot` or `track` parameter is `NULL`. # History `sd_bus_destroy_t()`, `sd_bus_slot_set_destroy_callback()`, `sd_bus_slot_get_destroy_callback()`, `sd_bus_track_set_destroy_callback()`, and `sd_bus_track_get_destroy_callback()` were added in version 239. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_slot_set_floating(3)`, `sd_bus_add_match(3)`, `sd_bus_track_new(3)`, `sd_bus_slot_set_userdata(3)`, `sd_bus_track_set_userdata(3)` # sd_bus_slot_set_floating systemd sd_bus_slot_set_floating 3 sd_bus_slot_set_floating sd_bus_slot_get_floating Control whether a bus slot object is "floating" \#include \ int sd_bus_slot_set_floating sd_bus_slot \* slot int b int sd_bus_slot_get_floating sd_bus_slot \* slot # Description `sd_bus_slot_set_floating()` controls whether the specified bus slot object `slot` shall be "floating" or not. A floating bus slot object's lifetime is bound to the lifetime of the bus object it is associated with, meaning that it remains allocated as long as the bus object itself and is freed automatically when the bus object is freed. Regular (i.e. non-floating) bus slot objects keep the bus referenced, hence the bus object remains allocated at least as long as there remains at least one referenced bus slot object around. The floating state hence controls the direction of referencing between the bus object and the bus slot objects: if floating the bus pins the bus slot, and otherwise the bus slot pins the bus objects. Use `sd_bus_slot_set_floating()` to switch between both modes: if the `b` parameter is zero, the slot object is made into a regular (non-floating) slot object, otherwise it is made into a floating slot object. Bus slot objects may be allocated with calls such as `sd_bus_add_match(3)`. If the `slot` of these functions is non-`NULL` the slot object will be of the regular kind (i.e. non-floating), otherwise it will be created floating. With `sd_bus_slot_set_floating()` a bus slot object allocated as regular can be converted into a floating object and back. This is particularly useful for creating a bus slot object, then changing parameters of it, and then turning it into a floating object, whose lifecycle is managed by the bus object. `sd_bus_slot_get_floating()` returns the current floating state of the specified bus slot object. It returns negative on error, zero if the bus slot object is a regular (non-floating) object and positive otherwise. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `slot` parameter is `NULL`. `-ECHILD` The bus connection has been created in a different process, library or module instance. `-ESTALE` The bus object the specified bus slot object is associated with has already been freed, and hence no change in the floating state can be made anymore. # History `sd_bus_slot_set_floating()` and `sd_bus_slot_get_floating()` were added in version 239. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_slot_set_destroy_callback(3)`, `sd_bus_add_match(3)` # sd_bus_slot_set_userdata systemd sd_bus_slot_set_userdata 3 sd_bus_slot_set_userdata sd_bus_slot_get_userdata Set and query the value in the "userdata" field \#include \ void\* sd_bus_slot_set_userdata sd_bus_slot\* slot void\* userdata void\* sd_bus_slot_get_userdata sd_bus_slot\* slot # Description The userdata pointer allows data to be passed between the point where a callback is registered, for example when a filter is added using `sd_bus_add_filter(3)` or an asynchronous function call is made using `sd_bus_call_async(3)`, and the point where the callback is called, without having any global state. The pointer has type `void*` and is not used by the sd-bus functions in any way, except to pass to the callback function. Usually, the userdata field is set when the slot object is initially registered. `sd_bus_slot_set_userdata()` may be used to change it later for the bus slot object `slot`. Previous value of the field is returned. The argument and returned value may be `NULL`. It will be passed as the `userdata` argument to the callback function attached to the slot. `sd_bus_slot_set_userdata()` gets the value of the userdata field in the bus slot object `slot`. # Return Value On success, these functions return the value of the userdata field before the function call. If the `slot` object is `NULL`, `NULL` will be returned to signify an error, but this is not distinguishable from the userdata field value being `NULL`. # History `sd_bus_slot_set_userdata()` and `sd_bus_slot_get_userdata()` were added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_slot_set_destroy_callback(3)`, `sd_bus_add_match(3)`, `sd_bus_slot_get_current_userdata(3)` # sd_bus_start systemd sd_bus_start 3 sd_bus_start Initiate a bus connection to the D-bus broker daemon \#include \ int sd_bus_start sd_bus \* bus # Description `sd_bus_start()` connects an existing bus connection object to the D-Bus broker daemon, usually `dbus-daemon(1)` or `dbus-broker(1)`. The mechanism to use for the connection must be configured before the call to `sd_bus_start()`, using one of `sd_bus_set_address(3)`, `sd_bus_set_fd(3)`, or `sd_bus_set_exec(3)`. `sd_bus_start()` will open the connection socket or spawn the executable as needed, and asynchronously start a `org.freedesktop.DBus.Hello()` call. The answer to the Hello call will be processed later from `sd_bus_process(3)`. If opening of the connection or queuing of the asynchronous call fail, the connection will be closed with `sd_bus_close(3)`. In most cases, it is better to use `sd_bus_default_user(3)`, `sd_bus_default_system(3)` or related calls instead of the more low-level `sd_bus_new()` and `sd_bus_start()`. The higher-level functions not only allocate a bus object but also start the connection to a well-known bus in a single function call. # Return Value On success, this function returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors `-EINVAL` The input parameter `bus` is `NULL`. `-ENOPKG` Bus object `bus` could not be resolved. `-EPERM` The input parameter `bus` is in a wrong state (`sd_bus_start()` may only be called once on a newly-created bus object). `-ECHILD` The bus object `bus` was created in a different process. In addition, other connection-related errors may be returned. See `sd_bus_send(3)`. # History `sd_bus_start()` was added in version 246. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_default(3)`, `sd_bus_call_async(3)` # sd_bus_track_add_name systemd sd_bus_track_add_name 3 sd_bus_track_add_name sd_bus_track_add_sender sd_bus_track_remove_name sd_bus_track_remove_sender sd_bus_track_count sd_bus_track_count_sender sd_bus_track_count_name sd_bus_track_contains sd_bus_track_first sd_bus_track_next Add, remove and retrieve bus peers tracked in a bus peer tracking object \#include \ int sd_bus_track_add_name sd_bus_track\* t const char\* name int sd_bus_track_add_sender sd_bus_track\* t sd_bus_message\* message int sd_bus_track_remove_name sd_bus_track\* t const char\* name int sd_bus_track_remove_sender sd_bus_track\* t sd_bus_message\* message unsigned sd_bus_track_count sd_bus_track\* t int sd_bus_track_count_name sd_bus_track\* t const char\* name int sd_bus_track_count_sender sd_bus_track\* t sd_bus_message\* message int sd_bus_track_contains sd_bus_track\* t const char\* name const char\* sd_bus_track_first sd_bus_track\* t const char\* sd_bus_track_next sd_bus_track\* t # Description `sd_bus_track_add_name()` adds a peer to track to a bus peer tracking object. The first argument should refer to a bus peer tracking object created with `sd_bus_track_new(3)`, the second name should refer to a D-Bus peer name to track, either in unique or well-known service format. If the name is not tracked yet it will be added to the list of names to track. If it already is being tracked and non-recursive mode is enabled, no operation is executed by this call. If recursive mode is enabled a per-name counter is increased by one each time this call is invoked, and `sd_bus_track_remove_name()` has to be called as many times as `sd_bus_track_add_name()` was invoked before in order to stop tracking of the name. Use `sd_bus_track_set_recursive(3)` to switch from the default non-recursive mode to recursive mode, or back. Note that the specified name is tracked as it is, well-known names are not resolved to unique names by this call. Note that multiple bus peer tracking objects may track the same name. `sd_bus_track_remove_name()` undoes the effect of `sd_bus_track_add_name()` and removes a bus peer name from the list of peers to watch. Depending on whether non-recursive or recursive mode is enabled for the bus peer tracking object this call will either remove the name fully from the tracking object, or will simply decrement the per-name counter by one, removing the name only when the counter reaches zero (see above). Note that a bus peer disconnecting from the bus will implicitly remove its names fully from the bus peer tracking object, regardless of the current per-name counter. `sd_bus_track_add_sender()` and `sd_bus_track_remove_sender()` are similar to `sd_bus_track_add_name()` and `sd_bus_track_remove_name()` but take a bus message as argument. The sender of this bus message is determined and added to/removed from the bus peer tracking object. As messages always originate from unique names, and never from well-known names this means that this call will effectively only add unique names to the bus peer tracking object. `sd_bus_track_count()` returns the number of names currently being tracked by the specified bus peer tracking object. Note that this function always returns the actual number of names tracked, and hence if `sd_bus_track_add_name()` has been invoked multiple times for the same name it is only counted as one, regardless of whether recursive mode is used or not. `sd_bus_track_count_name()` returns the current per-name counter for the specified name. If non-recursive mode is used this returns either 1 or 0, depending on whether the specified name has been added to the tracking object before, or not. If recursive mode has been enabled, values larger than 1 may be returned too, in case `sd_bus_track_add_name()` has been called multiple times for the same name. `sd_bus_track_count_sender()` is similar to `sd_bus_track_count_name()`, but takes a bus message object and returns the per-name counter matching the sender of the message. `sd_bus_track_contains()` may be used to determine whether the specified name has been added at least once to the specified bus peer tracking object. `sd_bus_track_first()` and `sd_bus_track_next()` may be used to enumerate all names currently being tracked by the passed bus peer tracking object. `sd_bus_track_first()` returns the first entry in the object, and resets an internally maintained read index. Each subsequent invocation of `sd_bus_track_next()` returns the next name contained in the bus object. If the end is reached `NULL` is returned. If no names have been added to the object yet `sd_bus_track_first()` will return `NULL` immediately. The order in which names are returned is undefined; in particular which name is considered the first returned is not defined. If recursive mode is enabled and the same name has been added multiple times to the bus peer tracking object it is only returned once by this enumeration. If new names are added to or existing names removed from the bus peer tracking object while it is being enumerated the enumeration ends on the next invocation of `sd_bus_track_next()` as `NULL` is returned. # Return Value On success, `sd_bus_track_add_name()` and `sd_bus_track_add_sender()` return 0 if the specified name has already been added to the bus peer tracking object before and positive if it has not. On failure, they return a negative errno-style error code. `sd_bus_track_remove_name()` and `sd_bus_track_remove_sender()` return positive if the specified name was previously tracked by the bus peer tracking object and has now been removed. In non-recursive mode, 0 is returned if the specified name was not being tracked yet. In recursive mode `-EUNATCH` is returned in this case. On failure, they return a negative errno-style error code. `sd_bus_track_count()` returns the number of names currently being tracked, or 0 on failure. `sd_bus_track_count_name()` and `sd_bus_track_count_sender()` return the current per-name counter for the specified name or the sender of the specified message. Zero is returned for names that are not being tracked yet, a positive value for names added at least once. Larger values than 1 are only returned in recursive mode. On failure, a negative errno-style error code is returned. `sd_bus_track_contains()` returns the passed name if it exists in the bus peer tracking object. On failure, and if the name has not been added yet `NULL` is returned. `sd_bus_track_first()` and `sd_bus_track_next()` return the first/next name contained in the bus peer tracking object, and `NULL` if the end of the enumeration is reached and on error. ## Errors Returned errors may indicate the following problems: `-EUNATCH` `sd_bus_track_remove_name()` or `sd_bus_track_remove_sender()` have been invoked for a name not previously added to the bus peer object. `-EINVAL` Specified parameter is invalid. `-ENOMEM` Memory allocation failed. # History `sd_bus_track_add_name()`, `sd_bus_track_add_sender()`, `sd_bus_track_remove_name()`, `sd_bus_track_remove_sender()`, `sd_bus_track_count()`, `sd_bus_track_count_name()`, `sd_bus_track_count_sender()`, `sd_bus_track_contains()`, `sd_bus_track_first()`, and `sd_bus_track_next()` were added in version 232. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_track_new(3)` # sd_bus_track_new systemd sd_bus_track_new 3 sd_bus_track_new sd_bus_track_ref sd_bus_track_unref sd_bus_track_unrefp sd_bus_track_set_recursive sd_bus_track_get_recursive sd_bus_track_get_bus sd_bus_track_get_userdata sd_bus_track_set_userdata Track bus peers \#include \ typedef int (\* sd_bus_track_handler_t ) sd_bus_track \* track void \* userdata int sd_bus_track_new sd_bus\* bus sd_bus_track\*\* ret sd_bus_track_handler_t handler void\* userdata sd_bus_track \* sd_bus_track_ref sd_bus_track \* t sd_bus_track \* sd_bus_track_unref sd_bus_track \* t void sd_bus_track_unrefp sd_bus_track \*\* t int sd_bus_track_get_recursive sd_bus_track \* t int sd_bus_track_set_recursive sd_bus_track \* t int b sd_bus\* sd_bus_track_get_bus sd_bus_track \* t void\* sd_bus_track_get_userdata sd_bus_track \* t void\* sd_bus_track_set_userdata sd_bus_track \* t void \*userdata # Description `sd_bus_track_new()` creates a new bus peer tracking object. The object is allocated for the specified bus, and returned in the `*ret` parameter. After use, the object should be freed again by dropping the acquired reference with `sd_bus_track_unref()` (see below). A bus peer tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to specific bus peers are added via `sd_bus_track_add_name(3)` or `sd_bus_track_add_sender()`. They may be dropped again via `sd_bus_track_remove_name()` and `sd_bus_track_remove_sender()`. Alternatively, references on peers are removed automatically when they disconnect from the bus. If non-`NULL` the `handler` may specify a function that is invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via `sd_bus_track_remove_name()` or implicitly because the peer disconnected from the bus. The final argument `userdata` may be used to attach a generic user data pointer to the object. This pointer is passed to the handler callback when it is invoked. `sd_bus_track_ref()` creates a new reference to a bus peer tracking object. This object will not be destroyed until `sd_bus_track_unref()` has been called as many times plus once more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to `sd_bus_track_ref()` or `sd_bus_track_unref()` on the same object are illegal. `sd_bus_track_unref()` destroys a reference to a bus peer tracking object. `sd_bus_track_unrefp()` is similar to `sd_bus_track_unref()` but takes a pointer to a pointer to an `sd_bus_track` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). Note that this function is defined as inline function. `sd_bus_track_ref()`, `sd_bus_track_unref()` and `sd_bus_track_unrefp()` execute no operation if the passed in bus peer tracking object is `NULL`. Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked or not tracked. In this mode invoking `sd_bus_track_add_name()` multiple times in a row for the same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if necessary, and executes no operation if the peer is already being tracked. A single invocation of `sd_bus_track_remove_name()` removes the reference on the peer again, regardless how many times `sd_bus_track_add_name()` was called before. If operating in recursive mode, the number of times `sd_bus_track_add_name()` is invoked for the same peer name is counted and `sd_bus_track_remove_name()` must be called the same number of times before the peer is not tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is irrelevant and the tracking of the specific peer is immediately removed. `sd_bus_track_get_recursive()` may be used to determine whether the bus peer tracking object is operating in recursive mode. `sd_bus_track_set_recursive()` may be used to enable or disable recursive mode. By default, a bus peer tracking object operates in non-recursive mode, and `sd_bus_track_get_recursive()` for a newly allocated object hence returns a value equal to zero. Use `sd_bus_track_set_recursive()` to enable recursive mode, right after allocation. It takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which `sd_bus_track_add_name()` was already invoked at least once (and which hence track already one or more peers) may not be switched from recursive to non-recursive mode anymore. `sd_bus_track_get_bus()` returns the bus object the bus peer tracking object belongs to. It returns the bus object initially passed to `sd_bus_track_new()` when the object was allocated. `sd_bus_track_get_userdata()` returns the generic user data pointer set on the bus peer tracking object at the time of creation using `sd_bus_track_new()` or at a later time, using `sd_bus_track_set_userdata()`. # Return Value On success, `sd_bus_track_new()` and `sd_bus_track_set_recursive()` return 0 or a positive integer. On failure, they return a negative errno-style error code. `sd_bus_track_ref()` always returns the argument. `sd_bus_track_unref()` always returns `NULL`. `sd_bus_track_get_recursive()` returns 0 if non-recursive mode is selected (default), and greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned. `sd_bus_track_get_bus()` returns the bus object associated to the bus peer tracking object. `sd_bus_track_get_userdata()` returns the generic user data pointer associated with the bus peer tracking object. `sd_bus_track_set_userdata()` returns the previous user data pointer set. # Reference ownership The `sd_bus_track_new()` function creates a new object and the caller owns the sole reference. When not needed anymore, this reference should be destroyed with `sd_bus_track_unref()`. ## Errors Returned errors may indicate the following problems: `-EBUSY` Bus peers have already been added to the bus peer tracking object and `sd_bus_track_set_recursive()` was called to change tracking mode. `-EINVAL` Specified parameter is invalid (`NULL` in case of output parameters). `-ENOMEM` Memory allocation failed. # History `sd_bus_track_new()`, `sd_bus_track_handler_t()`, `sd_bus_track_ref()`, `sd_bus_track_unref()`, `sd_bus_track_unrefp()`, `sd_bus_track_get_recursive()`, `sd_bus_track_set_recursive()`, `sd_bus_track_get_bus()`, `sd_bus_track_get_userdata()`, and `sd_bus_track_set_userdata()` were added in version 232. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_track_add_name(3)` # sd_bus_wait systemd sd_bus_wait 3 sd_bus_wait Wait for I/O on a bus connection \#include \ int sd_bus_wait sd_bus \* bus uint64_t timeout_usec # Description `sd_bus_wait()` synchronously waits for I/O on the specified bus connection object. This function is supposed to be called whenever `sd_bus_process(3)` returns zero, indicating that no work is pending on the connection. Internally, this call invokes `ppoll(2)`, to wait for I/O on the bus connection. If the `timeout_usec` parameter is specified, the call will block at most for the specified amount of time in μs. Pass `UINT64_MAX` to permit it to sleep indefinitely. After each invocation of `sd_bus_wait()` the `sd_bus_process()` call should be invoked in order to process any now pending I/O work. Note that `sd_bus_wait()` is suitable only for simple programs as it does not permit waiting for other I/O events. For more complex programs either connect the bus connection object to an external event loop using `sd_bus_get_fd(3)` or to an `sd-event(3)` event loop using `sd_bus_attach_event(3)`. # Return Value If any I/O was seen, a positive value is returned, zero otherwise. If an error occurs, a negative `errno`-style error code is returned. ## Errors Returned errors may indicate the following problems: `-EINVAL` An invalid bus object was passed. `-ECHILD` The bus connection was allocated in a parent process and is being reused in a child process after `fork()`. `-ENOTCONN` The bus connection has been terminated already. # History `sd_bus_wait()` was added in version 240. # See Also `systemd(1)`, `sd-bus(3)`, `sd_bus_process(3)`, `sd_bus_get_fd(3)`, `sd-event(3)`, `sd_bus_attach_event(3)` # sd_device_enumerator_add_match_parent systemd sd_device_enumerator_add_match_parent 3 sd_device_enumerator_add_match_parent sd_device_enumerator_add_match_property sd_device_enumerator_add_match_property_required sd_device_enumerator_add_match_subsystem sd_device_enumerator_add_match_sysattr sd_device_enumerator_add_match_sysname sd_device_enumerator_add_nomatch_sysname sd_device_enumerator_add_match_tag sd_device_enumerator_allow_uninitialized sd_device_enumerator_add_all_parents Add a filter to the device enumerator \#include \ int sd_device_enumerator_add_match_parent sd_device_enumerator \* enumerator sd_device \* parent int sd_device_enumerator_add_match_property sd_device_enumerator \* enumerator const char \* property const char \* value int sd_device_enumerator_add_match_property_required sd_device_enumerator \* enumerator const char \* property const char \* value int sd_device_enumerator_add_match_subsystem sd_device_enumerator \* enumerator const char \* subsystem int match int sd_device_enumerator_add_match_sysattr sd_device_enumerator \* enumerator const char \* sysattr const char \* value int match int sd_device_enumerator_add_match_sysname sd_device_enumerator \* enumerator const char \* sysname int sd_device_enumerator_add_nomatch_sysname sd_device_enumerator \* enumerator const char \* sysname int sd_device_enumerator_add_match_tag sd_device_enumerator \* enumerator const char \* tag int sd_device_enumerator_allow_uninitialized sd_device_enumerator \* enumerator int sd_device_enumerator_add_all_parents sd_device_enumerator \* enumerator # Description The `sd_device_enumerator_add_match_parent()` function adds a filter to the `enumerator` so that only devices under the tree of the specified `parent` device are enumerated. If this is called multiple times the previously set `parent` device is cleared and only the last call takes an effect. The `sd_device_enumerator_add_match_property()` function adds a filter to the `enumerator` so that only devices with the specified `property` equals to the `value` are enumerated. Both `property` and `value` can be a glob pattern. When this is called multiple times, devices that have at least one of the specified properties with matching values are enumerated. That is, filters are ORed. The `sd_device_enumerator_add_match_property_required()` function adds a filter to the `enumerator` so that only devices with the specified `property` equals to the `value` are enumerated. This function is similar to `sd_device_enumerator_add_match_property()`, but when this is called multiple times, devices that have *all* specified properties with matching values are enumerated. That is, filters are ANDed. The `sd_device_enumerator_add_match_subsystem()` function adds a filter to the `enumerator` so that all devices in the specified `subsystem` are enumerated when `match` is `true`. When `match` is `false`, then all devices except those in the specified `subsystem` are enumerated. When called multiple times, positive filters are ORed, and negative ones are ANDed. The `sd_device_enumerator_add_match_sysattr()` function adds a filter on the sysfs attribute `sysattr` matching `value`. `value` can be a glob pattern. If `value` is `NULL`, devices that either have (if `match` is `true`) or do not have (if `match` is `false`) the specified `sysattr` are included, regardless of its value. That is, `NULL` is mostly equivalent to `*`. When this function is called multiple times, only devices that match all specified `sysattr` filters are enumerated. That is, these filters are ANDed. The `sd_device_enumerator_add_match_sysname()` function adds a filter so that only devices whose sysname equals to `sysname` are enumerated. `sysname` can be a glob pattern. When called multiple times, filters are ORed. The `sd_device_enumerator_add_nomatch_sysname()` function adds a filter so that devices whose sysname equals to `sysname` are excluded from the enumeration. This is useful for excluding specific devices from the enumeration process. When called multiple times, filters are ANDed. The `sd_device_enumerator_add_match_tag()` function adds a filter so that only devices tagged with `tag` are enumerated. When called multiple times, filters are ORed. The `sd_device_enumerator_allow_uninitialized()` function allows devices that have not yet been initialized by udev to be included in the enumeration. The `sd_device_enumerator_add_all_parents()` function enumerates all parent devices of the matching devices. This is useful for cases where you want to include all parent devices in the enumeration, such as when you are interested in the entire device tree leading up to a specific device. # Return Value All functions return `0` or a positive integer on success, or a negative errno-style error code on failure. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Memory allocation failed. `-EINVAL` One of the arguments is invalid. # Examples
Detect Removable USB Devices (Using Match and Exclude)
# History `sd_device_enumerator_add_match_parent()`, `sd_device_enumerator_add_match_property()`, `sd_device_enumerator_add_match_subsystem()`, `sd_device_enumerator_add_match_sysattr()`, `sd_device_enumerator_add_match_sysname()`, `sd_device_enumerator_add_match_tag()`, and `sd_device_enumerator_allow_uninitialized()` were added in version 240. `sd_device_enumerator_add_nomatch_sysname()` was added in version 251. `sd_device_enumerator_add_match_property_required()` was added in version 255. `sd_device_enumerator_add_all_parents()` was added in version 258. # See Also `sd_device_ref(3)`, `sd_device_enumerator_new(3)`, `sd_device_enumerator_get_device_first(3)` # sd_device_enumerator_get_device_first systemd sd_device_enumerator_get_device_first 3 sd_device_enumerator_get_device_first sd_device_enumerator_get_device_next sd_device_enumerator_get_subsystem_first sd_device_enumerator_get_subsystem_next Enumerates devices and get the first or next device. \#include \ sd_device \* sd_device_enumerator_get_device_first sd_device_enumerator \* enumerator sd_device \* sd_device_enumerator_get_device_next sd_device_enumerator \* enumerator sd_device \* sd_device_enumerator_get_subsystem_first sd_device_enumerator \* enumerator sd_device \* sd_device_enumerator_get_subsystem_next sd_device_enumerator \* enumerator # Description The `sd_device_enumerator_get_device_first()` function enumerates all matching devices under `/sys/bus/SUBSYSTEM/devices/` and `/sys/class/SUBSYSTEM/devices/`, and returns a pointer to the first `sd_device` object. If no devices are found, `NULL` is returned. The `sd_device_enumerator_get_device_next()` function returns the pointer to the next `sd_device` from the `enumerator`. It should be called after `sd_device_enumerator_get_device_first()` or after a previous call to this function. If no more devices are available, `NULL` is returned. The `sd_device_enumerator_get_subsystem_first()` function enumerates all matching subsystem devices in `/sys/module/`, `/sys/bus/`, and `/sys/bus/SUBSYSTEM/drivers/` (such as `/sys/bus/pci/drivers/`). It returns a pointer to the first `sd_device` object. If no devices are found `NULL` is returned. Note that this does *not* enumerate devices provided by `sd_device_enumerator_get_device_first/next()`. Hence, e.g. `/sys/bus/pci/`, `/sys/bus/pci/drivers/ahci/` and so on are enumerated, but `/sys/bus/pci/devices/0000:00:00.0/` and so on are not. The `sd_device_enumerator_get_subsystem_next()` function returns the next subsystem device from the enumerator. It should be called after `sd_device_enumerator_get_subsystem_first()` or after a previous call to this function. If no more subsystem devices are available, `NULL` is returned. # Return Value On success, these functions return a pointer to an `sd_device` object. On failure or when no more devices are available, `NULL` is returned. The returned pointers are owned by the enumerator and should not be freed by the caller. # History `sd_device_enumerator_get_device_first()`, `sd_device_enumerator_get_device_next()`, `sd_device_enumerator_get_subsystem_first()`, and `sd_device_enumerator_get_subsystem_next()` were introduced in systemd version 240. # See Also `sd_device_enumerator_new(3)`, `sd_device_enumerator_add_match_parent(3)`, `sd_device_ref(3)` # sd_device_enumerator_new systemd sd_device_enumerator_new 3 sd_device_enumerator_new sd_device_enumerator_ref sd_device_enumerator_unref sd_device_enumerator_unrefp Create, reference, and release a device enumerator object \#include \ int sd_device_enumerator_new sd_device_enumerator \*\* ret sd_device_enumerator\* sd_device_enumerator_ref sd_device_enumerator \* enumerator sd_device_enumerator\* sd_device_enumerator_unref sd_device_enumerator \* enumerator void sd_device_enumerator_unrefp sd_device_enumerator \*\* enumerator # Description The `sd_device_enumerator` family of functions provides a way to iterate over devices recognized by `systemd-udevd(8)`. The enumerator allows filtering and matching devices by subsystem, properties and other attributes. `sd_device_enumerator_new()` creates a new device enumerator object and stores the result in the pointer referenced by `ret`. Returns 0 on success, or a negative errno-style error code on failure. `sd_device_enumerator_ref()` increases the reference count of the specified `enumerator` by one. `sd_device_enumerator_unref()` decreases the reference count of the `enumerator` by one. When the reference count reaches zero, the enumerator object is destroyed and cannot be used anymore, so further calls to `sd_device_enumerator_unref()` or `sd_device_enumerator_unrefp()` are illegal. `sd_device_enumerator_unrefp()` is similar to `sd_device_enumerator_unref()` but takes a pointer to a pointer to an `sd_device_enumerator` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). Note that this function is defined as an inline function. Use a declaration like the following, in order to allocate a `sd_device_enumerator` object that is freed automatically as the code block is left: { __attribute__((cleanup(sd_device_enumerator_unrefp))) sd_device_enumerator *enumerator = NULL; int r; … r = sd_device_enumerator_new(&enumerator); if (r < 0) fprintf(stderr, "Failed to allocate sd_device_enumerator: %s\n", strerror(-r)); … } `sd_device_enumerator_ref()` and `sd_device_enumerator_unref()` execute no operation if the `enumerator` is `NULL`. `sd_device_enumerator_unrefp()` will first dereference its argument, which must not be `NULL`, and will execute no operation if *that* is `NULL`. # Return Value `sd_device_enumerator_new()` returns 0 on success or a negative errno-style error code on failure. `sd_device_enumerator_ref()` always returns the enumerator pointer. `sd_device_enumerator_unref()` always returns `NULL`. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Memory allocation failed. `-EINVAL` The argument is invalid. # Example
Using sd_device_enumerator_new()
# History `sd_device_enumerator_new()`, `sd_device_enumerator_ref()`, `sd_device_enumerator_unref()`, and `sd_device_enumerator_unrefp()` were added in version 240. # See Also `sd_device_ref(3)`, `sd_device_enumerator_add_match_parent(3)` # sd_device_get_syspath systemd sd_device_get_syspath 3 sd_device_get_syspath sd_device_get_devpath sd_device_get_sysname sd_device_get_sysnum sd_device_get_subsystem sd_device_get_driver_subsystem sd_device_get_devtype sd_device_get_devname sd_device_get_devnum sd_device_get_ifindex sd_device_get_driver sd_device_get_diskseq sd_device_get_device_id Returns various fields of device objects \#include \ int sd_device_get_syspath sd_device \* device const char \*\* ret int sd_device_get_devpath sd_device \* device const char \*\* ret int sd_device_get_sysname sd_device \* device const char \*\* ret int sd_device_get_sysnum sd_device \* device const char \*\* ret int sd_device_get_subsystem sd_device \* device const char \*\* ret int sd_device_get_driver_subsystem sd_device \* device const char \*\* ret int sd_device_get_devtype sd_device \* device const char \*\* ret int sd_device_get_devname sd_device \* device const char \*\* ret int sd_device_get_devnum sd_device \* device dev_t \* ret int sd_device_get_ifindex sd_device \* device int \* ret int sd_device_get_driver sd_device \* device const char \*\* ret int sd_device_get_diskseq sd_device \* device uint64_t \* ret int sd_device_get_device_id sd_device \* device const char \*\* ret # Description `sd_device_get_syspath()` returns the sysfs path of the specified device record, including the `/sys` prefix. Example: `/sys/devices/virtual/tty/tty7` `sd_device_get_devpath()` returns the sysfs path of the specified device record, excluding the `/sys` prefix. Example: `/devices/virtual/tty/tty7` `sd_device_get_sysname()` returns the sysfs name of the specified device record, i.e. the last component of the sysfs path. Example: `tty7` for the device `/sys/devices/virtual/tty/tty7` `sd_device_get_sysnum()` returns the sysfs device number of the specified device record, i.e. the numeric suffix of the last component of the sysfs path. Example: `7` for the device `/sys/devices/virtual/tty/tty7` `sd_device_get_subsystem()` returns the kernel subsystem of the specified device record. This is a short string fitting into a filename, and thus does not contain a slash and cannot be empty. Example: `tty`, `block` or `net`. `sd_device_get_driver_subsystem()` returns the connected bus type of the devices loaded by the specified driver device record. For example, when `iwlwifi` driver device is specified, which is used by the wireless network interfaces connected to PCI bus, this function returns `pci`. This function only succeeds when `sd_device_get_subsystem()` returns `drivers`. Example: `pci`, `i2c`, or `hid`. `sd_device_get_devtype()` returns the device type of the specified device record, if the subsystem manages multiple types of devices. Example: for devices of the `block` subsystem this can be `disk` or `partition` `sd_device_get_devname()` returns the device node path of the specified device record if the device has a device node. Example: for `/sys/devices/virtual/tty/tty7` the string `/dev/tty7` is typically returned. `sd_device_get_devnum()` returns the device node major/minor (i.e. `dev_t`) of the specified device record if the device has a device node (i.e. the one returned by `sd_device_get_devname()`). For devices belonging to the `block` subsystem this refers to a block device node, in all other cases to a character device node. Example: for the `/sys/devices/virtual/tty/tty7` device this typically returns the device number with major/minor `4:7`. `sd_device_get_ifindex()` returns the network interface index of the specified device record, if the device encapsulates a network interface device, i.e. belongs to the `net` subsystem. Example: the `lo` interface typically has interface index 1. `sd_device_get_driver()` returns the kernel driver name attached to the device. Note that the driver field is set on the devices consumed by the driver, not on the device created by it. Example: a PCI device `/sys/bus/pci/devices/0000:00:1f.6` might be attached to a driver `e1000e`. `sd_device_get_diskseq()` returns the kernel disk sequence number of the block device. This number monotonically increases whenever a backing medium of a block device changes without the device name changing, and is relevant for block devices encapsulating devices with changing media (e.g. floppy or CD-ROM), or loopback block devices. Only defined for block devices, i.e. those of subsystem `block`. `sd_device_get_device_id()` returns the short string that identifies the device record. When the device ID obtained by the function for a specified device record is passed to `sd_device_new_from_device_id()`, a new instance of the same device record will be gained. When a block or character device is specified, which has corresponding device node, this returns `b` or `c`, respectively, followed by the device node major and minor numbers separated with a colon. Example: `b259:1` or `c10:121`. When a network interface device is specified, this returns `n` followed by the interface index, which can be obtained by `sd_device_get_ifindex()`. Example: `n1`. When a device in the `driver` subsystem is specified, this returns `+drivers:` followed by its driver subsystem and sysfs name separated with a colon. Example: `+drivers:pci:iwlwifi` for a driver device record whose driver subsystem is `pci` and sysfs name is `iwlwifi`, When another type of device is specified, this function returns `+` followed by its subsystem and sysfs name separated with a colon. Example: `+acpi:ACPI0003:00`, `+input:input16`, or `+pci:0000:00:1f.6`. # Return Value On success, these calls return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` A specified parameter is invalid. `-ENOENT` The requested field is not present in the device record. # History `sd_device_get_syspath()`, `sd_device_get_devpath()`, `sd_device_get_sysname()`, `sd_device_get_sysnum()`, `sd_device_get_subsystem()`, `sd_device_get_devtype()`, `sd_device_get_devname()`, `sd_device_get_devnum()`, `sd_device_get_ifindex()`, `sd_device_get_driver()`, and `sd_device_get_diskseq()` were added in version 251. `sd_device_get_driver_subsystem()` and `sd_device_get_device_id()` were added in version 257. # See Also `systemd(1)`, `sd-device(3)` # sd_device_ref systemd sd_device_ref 3 sd_device_ref sd_device_unref sd_device_unrefp Create or destroy references to a device object \#include \ sd_device\* sd_device_ref sd_device \* device sd_device\* sd_device_unref sd_device \* device void sd_device_unrefp sd_device \*\* device `sd_device_ref()` increases the internal reference counter of `device` by one. `sd_device_unref()` decreases the internal reference counter of `device` by one. Once the reference count has dropped to zero, `device` is destroyed and cannot be used anymore, so further calls to `sd_device_ref()` or `sd_device_unref()` are illegal. `sd_device_unrefp()` is similar to `sd_device_unref()` but takes a pointer to a pointer to an `sd_device` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). Note that this function is defined as an inline function. Use a declaration like the following, in order to allocate a device object that is freed automatically as the code block is left: { __attribute__((cleanup(sd_device_unrefp))) sd_device *device = NULL; int r; … r = sd_device_new_from_syspath(&device, "…"); if (r < 0) { errno = -r; fprintf(stderr, "Failed to allocate device: %m\n"); } … } `sd_device_ref()` and `sd_device_unref()` execute no operation if the argument is `NULL`. `sd_device_unrefp()` will first dereference its argument, which must not be `NULL`, and will execute no operation if *that* is `NULL`. # Return Value `sd_device_ref()` always returns the argument, and `sd_device_unref()` always returns `NULL`. # History `sd_device_ref()`, `sd_device_unref()`, and `sd_device_unrefp()` were added in version 251. # sd_event_add_child systemd sd_event_add_child 3 sd_event_add_child sd_event_add_child_pidfd sd_event_source_get_child_pid sd_event_source_get_child_pidfd sd_event_source_get_child_pidfd_own sd_event_source_set_child_pidfd_own sd_event_source_get_child_process_own sd_event_source_set_child_process_own sd_event_source_send_child_signal sd_event_child_handler_t Add a child process state change event source to an event loop \#include \ typedef struct sd_event_source sd_event_source; typedef int (\* sd_event_child_handler_t ) sd_event_source \* s const siginfo_t \* si void \* userdata int sd_event_add_child sd_event \* event sd_event_source \*\* source pid_t pid int options sd_event_child_handler_t handler void \* userdata int sd_event_add_child_pidfd sd_event \* event sd_event_source \*\* source int pidfd int options sd_event_child_handler_t handler void \* userdata int sd_event_source_get_child_pid sd_event_source \* source pid_t \* ret int sd_event_source_get_child_pidfd sd_event_source \* source int sd_event_source_get_child_pidfd_own sd_event_source \* source int sd_event_source_set_child_pidfd_own sd_event_source \* source int own int sd_event_source_get_child_process_own sd_event_source \* source int sd_event_source_set_child_process_own sd_event_source \* source int own int sd_event_source_send_child_signal sd_event_source \* source int sig const siginfo_t \* info unsigned flags # Description `sd_event_add_child()` adds a new child process state change event source to an event loop. The event loop object is specified in the `event` parameter, the event source object is returned in the `source` parameter. The `pid` parameter specifies the PID of the process to watch, which must be a direct child process of the invoking process. The `options` parameter determines which state changes will be watched for. It must contain an OR-ed mask of `WEXITED` (watch for the child process terminating), `WSTOPPED` (watch for the child process being stopped by a signal), `WCONTINUED` (watch for the child process being resumed by a signal) and `WNOWAIT` (Do not reap the child process after it exits). See `waitid(2)` for further information. The `handler` must be a function to call when the process changes state or `NULL`. The handler function will be passed the `userdata` pointer, which may be chosen freely by the caller. The handler also receives a pointer to a siginfo_t structure containing information about the child process event. The handler may return negative to signal an error (see below), other return values are ignored. If `handler` is `NULL`, a default handler that calls `sd_event_exit(3)` will be used. Only a single handler may be installed for a specific child process. The handler is enabled for a single event (`SD_EVENT_ONESHOT`), but this may be changed with `sd_event_source_set_enabled(3)`. If the handler function returns a negative error code, it will either be disabled after the invocation, even if the `SD_EVENT_ON` mode was requested before, or it will cause the loop to terminate, see `sd_event_source_set_exit_on_failure(3)`. To destroy an event source object use `sd_event_source_unref(3)`, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure an event source does not fire anymore, even when there's still a reference to it kept, consider setting the event source to `SD_EVENT_OFF` with `sd_event_source_set_enabled(3)`. The kernel autoreaping logic must be disabled for this function to work as expected (see `signal(7)`). When watching for `WSTOPPED` or `WCONTINUED`, the `SIGCHLD` signal must be blocked in all threads before this function is called (using `sigprocmask(2)` or `pthread_sigmask(3)`). If the second parameter of `sd_event_add_child()` is passed as `NULL` no reference to the event source object is returned. In this case, the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed. Note that the `handler` function is invoked at a time where the child process is not reaped yet (and thus still is exposed as a zombie process by the kernel). However, the child will be reaped automatically after the function returns. Child processes for which no child process state change event sources are installed will not be reaped by the event loop implementation. If the `handler` parameter to `sd_event_add_child()` is `NULL`, and the event source fires, this will be considered a request to exit the event loop. In this case, the `userdata` parameter, cast to an integer, is passed as the exit code parameter to `sd_event_exit(3)`. If both a child process state change event source and a `SIGCHLD` signal event source is installed in the same event loop, the configured event source priorities decide which event source is dispatched first. If the signal handler is processed first, it should leave the child processes for which child process state change event sources are installed unreaped. `sd_event_add_child_pidfd()` is similar to `sd_event_add_child()` but takes a file descriptor referencing the process ("pidfd") instead of the numeric PID. A suitable file descriptor may be acquired via `pidfd_open(2)` and related calls. The passed file descriptor is not closed when the event source is freed again, unless `sd_event_source_set_child_pidfd_own()` is used to turn this behaviour on. Note that regardless which of `sd_event_add_child()` and `sd_event_add_child_pidfd()` is used for allocating an event source, the watched process has to be a direct child process of the invoking process. Also in both cases `SIGCHLD` has to be blocked in the invoking process when watching for `WSTOPPED` or `WCONTINUED` and the kernel autoreaping logic has to be disabled. `sd_event_source_get_child_pid()` retrieves the configured PID of a child process state change event source created previously with `sd_event_add_child()`. It takes the event source object as the `source` parameter and a pointer to a `pid_t` variable to return the process ID in. `sd_event_source_get_child_pidfd()` retrieves the file descriptor referencing the watched process ("pidfd"). The event loop internally makes use of pidfds to watch child processes, regardless of whether the individual event sources are allocated via `sd_event_add_child()` or `sd_event_add_child_pidfd()`. If the latter call was used to allocate the event source, this function returns the original file descriptor used for allocation. This call takes the event source object as the `source` parameter and returns the numeric file descriptor. `sd_event_source_get_child_pidfd_own()` may be used to query whether the pidfd the event source encapsulates shall be closed when the event source is freed. This function returns zero if the pidfd shall be left open, and positive if it shall be closed automatically. By default, this setting defaults to on if the event source was allocated via `sd_event_add_child()` and off if it was allocated via `sd_event_add_child_pidfd()`. The `sd_event_source_set_child_pidfd_own()` function may be used to change the setting and takes a boolean parameter with the new setting. `sd_event_source_get_child_process_own()` may be used to query whether the process the event source watches shall be killed (with `SIGKILL`) and reaped when the event source is freed. This function returns zero if the process shell be left running, and positive if it shall be killed and reaped automatically. By default, this setting defaults to off. The `sd_event_source_set_child_process_own()` function may be used to change the setting and takes a boolean parameter with the new setting. Note that currently if the calling process is terminated abnormally the watched process might survive even thought the event source ceases to exist. This behaviour might change eventually. `sd_event_source_send_child_signal()` may be used to send a UNIX signal to the watched process via `pidfd_send_signal(2)`. The specified parameters match those of the underlying system call, except that the `info` is never modified (and is thus declared constant). Like for the underlying system call, the `flags` parameter currently must be zero. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Not enough memory to allocate an object. `-EINVAL` An invalid argument has been passed. This includes specifying an empty mask in `options` or a mask which contains values different than a combination of `WEXITED`, `WSTOPPED`, and `WCONTINUED`. `-EBUSY` A handler is already installed for this child process, or `SIGCHLD` is not blocked. `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. `-EDOM` The passed event source is not a child process event source. # Example
Exit loop when the child terminates
# History `sd_event_add_child()`, `sd_event_child_handler_t()`, and `sd_event_source_get_child_pid()` were added in version 217. `sd_event_add_child_pidfd()`, `sd_event_source_get_child_pidfd()`, `sd_event_source_get_child_pidfd_own()`, `sd_event_source_set_child_pidfd_own()`, `sd_event_source_get_child_process_own()`, `sd_event_source_set_child_process_own()`, and `sd_event_source_send_child_signal()` were added in version 245. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_now(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_priority(3)`, `sd_event_source_set_userdata(3)`, `sd_event_source_set_description(3)`, `sd_event_source_set_floating(3)`, `waitid(2)`, `sigprocmask(2)`, `pthread_sigmask(3)`, `pidfd_open(2)`, `pidfd_send_signal(2)`, `rt_sigqueueinfo(2)`, `kill(2)` # sd_event_add_defer systemd sd_event_add_defer 3 sd_event_add_defer sd_event_add_post sd_event_add_exit sd_event_handler_t Add static event sources to an event loop \#include \ typedef struct sd_event_source sd_event_source; typedef int (\* sd_event_handler_t ) sd_event_source \* s void \* userdata int sd_event_add_defer sd_event \* event sd_event_source \*\* source sd_event_handler_t handler void \* userdata int sd_event_add_post sd_event \* event sd_event_source \*\* source sd_event_handler_t handler void \* userdata int sd_event_add_exit sd_event \* event sd_event_source \*\* source sd_event_handler_t handler void \* userdata # Description These three functions add new static event sources to an event loop. The event loop object is specified in the `event` parameter, the event source object is returned in the `source` parameter. The event sources are enabled statically and will "fire" when the event loop is run and the conditions described below are met. The `handler` is a function to call or `NULL`. The handler function will be passed the `userdata` pointer, which may be chosen freely by the caller. The handler may return negative to signal an error (see below), other return values are ignored. If `handler` is `NULL`, a default handler that calls `sd_event_exit(3)` will be used. `sd_event_add_defer()` adds a new event source that will be dispatched instantly, before the event loop goes to sleep again and waits for new events. By default, the handler will be called once (`SD_EVENT_ONESHOT`). Note that if the event source is set to `SD_EVENT_ON` the event loop will never go to sleep again, but continuously call the handler, possibly interleaved with other event sources. `sd_event_add_post()` adds a new event source that is run before the event loop will sleep and wait for new events, but only after at least one other non-post event source was dispatched. By default, the source is enabled permanently (`SD_EVENT_ON`). Note that this event source type will still allow the event loop to go to sleep again, even if set to `SD_EVENT_ON`, as long as no other event source is ever triggered. `sd_event_add_exit()` adds a new event source that will be dispatched when the event loop is terminated with `sd_event_exit(3)`. The `sd_event_source_set_enabled(3)` function may be used to enable the event source permanently (`SD_EVENT_ON`) or to make it fire just once (`SD_EVENT_ONESHOT`). If the handler function returns a negative error code, it will either be disabled after the invocation, even if the `SD_EVENT_ON` mode was requested before, or it will cause the loop to terminate, see `sd_event_source_set_exit_on_failure(3)`. To destroy an event source object use `sd_event_source_unref(3)`, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure an event source does not fire anymore, even when there's still a reference to it kept, consider setting the event source to `SD_EVENT_OFF` with `sd_event_source_set_enabled(3)`. If the second parameter of these functions is passed as `NULL` no reference to the event source object is returned. In this case, the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed. If the `handler` parameter to `sd_event_add_defer()` or `sd_event_add_post()` is `NULL`, and the event source fires, this will be considered a request to exit the event loop. In this case, the `userdata` parameter, cast to an integer, is passed as the exit code parameter to `sd_event_exit(3)`. Similar functionality is not available for `sd_event_add_exit()`, as these types of event sources are only dispatched when exiting anyway. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Not enough memory to allocate an object. `-EINVAL` An invalid argument has been passed. `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. # History `sd_event_add_defer()`, `sd_event_add_post()`, `sd_event_add_exit()`, and `sd_event_handler_t()` were added in version 217. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_now(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_priority(3)`, `sd_event_source_set_userdata(3)`, `sd_event_source_set_description(3)`, `sd_event_source_set_floating(3)`, `sd_event_exit(3)` # sd_event_add_inotify systemd sd_event_add_inotify 3 sd_event_add_inotify sd_event_add_inotify_fd sd_event_source_get_inotify_mask sd_event_source_get_inotify_path sd_event_inotify_handler_t Add an "inotify" file system inode event source to an event loop \#include \ typedef struct sd_event_source sd_event_source; typedef int (\* sd_event_inotify_handler_t ) sd_event_source \* s const struct inotify_event \* event void \* userdata int sd_event_add_inotify sd_event \* event sd_event_source \*\* source const char \* path uint32_t mask sd_event_inotify_handler_t handler void \* userdata int sd_event_add_inotify_fd sd_event \* event sd_event_source \*\* source int fd uint32_t mask sd_event_inotify_handler_t handler void \* userdata int sd_event_source_get_inotify_mask sd_event_source \* source uint32_t \* ret int sd_event_source_get_inotify_path sd_event_source \* source const char \*\* ret # Description `sd_event_add_inotify()` adds a new `inotify(7)` file system inode event source to an event loop. The event loop object is specified in the `event` parameter, the event source object is returned in the `source` parameter. The `path` parameter specifies the path of the file system inode to watch. The `mask` parameter specifies which types of inode events to watch specifically. It must contain an OR-ed combination of `IN_ACCESS`, `IN_ATTRIB`, `IN_CLOSE_WRITE`, … flags. See `inotify(7)` for further information. The `handler` must reference a function to call when the inode changes or `NULL`. The handler function will be passed the `userdata` pointer, which may be chosen freely by the caller. The handler also receives a pointer to a struct inotify_event structure containing information about the inode event. The handler may return negative to signal an error (see below), other return values are ignored. If `handler` is `NULL`, a default handler that calls `sd_event_exit(3)` will be used. `sd_event_add_inotify_fd()` is identical to `sd_event_add_inotify()`, except that it takes a file descriptor to an inode (possibly an `O_PATH` one, but any other will do too) instead of a path in the file system. If multiple event sources are installed for the same inode the backing inotify watch descriptor is automatically shared. The mask parameter may contain any flag defined by the inotify API, with the exception of `IN_MASK_ADD`. The handler is enabled continuously (`SD_EVENT_ON`), but this may be changed with `sd_event_source_set_enabled(3)`. Alternatively, the `IN_ONESHOT` mask flag may be used to request `SD_EVENT_ONESHOT` mode. If the handler function returns a negative error code, it will be disabled after the invocation, even if the `SD_EVENT_ON` mode was requested before. As a special limitation the priority of inotify event sources may only be altered (see `sd_event_source_set_priority(3)`) in the time between creation of the event source object with `sd_event_add_inotify()` and the beginning of the next event loop iteration. Attempts of changing the priority any later will be refused. Consider freeing and allocating a new inotify event source to change the priority at that point. To destroy an event source object use `sd_event_source_unref(3)`, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure an event source does not fire anymore, even when there's still a reference to it kept, consider disabling it with `sd_event_source_set_enabled(3)`. If the second parameter of `sd_event_add_inotify()` is passed as `NULL` no reference to the event source object is returned. In this case, the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed. If the `handler` parameter to `sd_event_add_inotify()` is `NULL`, and the event source fires, this will be considered a request to exit the event loop. In this case, the `userdata` parameter, cast to an integer, is passed as the exit code parameter to `sd_event_exit(3)`. `sd_event_source_get_inotify_mask()` retrieves the configured inotify watch mask of an event source created previously with `sd_event_add_inotify()`. It takes the event source object as the `source` parameter and a pointer to a `uint32_t` variable to return the mask in. `sd_event_source_get_inotify_path()` retrieves the target path of the configured inotify watch of an event source created previously with `sd_event_add_inotify()`. It takes the event source object as the `source` parameter and a pointer to a `const char **` variable to return the path in. The caller must not free the returned path. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Not enough memory to allocate an object. `-EINVAL` An invalid argument has been passed. This includes specifying a mask with `IN_MASK_ADD` set. `-ESTALE` Returned by `sd_event_source_add_inotify()` or `sd_event_source_add_inotify_fd()` when the event loop is already terminated. Returned by `sd_event_source_get_inotify_path()` when no active inode data is assigned to the event source, e.g. when the event source is disabled. `-ECHILD` The event loop has been created in a different process, library or module instance. `-EDOM` The passed event source is not an inotify process event source. `-EBADF` The passed file descriptor is not valid. `-ENOSYS` `sd_event_add_inotify_fd()` or `sd_event_source_get_inotify_path()` was called without `/proc/` mounted. # Examples
A simple program that uses inotify to monitor one or two directories
# History `sd_event_inotify_handler_t()`, `sd_event_add_inotify()`, and `sd_event_source_get_inotify_mask()` were added in version 239. `sd_event_add_inotify_fd()` was added in version 250. `sd_event_source_get_inotify_path()` was added in version 256. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_now(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_defer(3)`, `sd_event_add_child(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_priority(3)`, `sd_event_source_set_userdata(3)`, `sd_event_source_set_description(3)`, `sd_event_source_set_floating(3)`, `waitid(2)` # sd_event_add_io systemd sd_event_add_io 3 sd_event_add_io sd_event_source_get_io_events sd_event_source_set_io_events sd_event_source_get_io_revents sd_event_source_get_io_fd sd_event_source_set_io_fd sd_event_source_get_io_fd_own sd_event_source_set_io_fd_own sd_event_source sd_event_io_handler_t Add an I/O event source to an event loop \#include \ typedef struct sd_event_source sd_event_source; typedef int (\* sd_event_io_handler_t ) sd_event_source \* s int fd uint32_t revents void \* userdata int sd_event_add_io sd_event \* event sd_event_source \*\* source int fd uint32_t events sd_event_io_handler_t handler void \* userdata int sd_event_source_get_io_events sd_event_source \* source uint32_t \* ret int sd_event_source_set_io_events sd_event_source \* source uint32_t events int sd_event_source_get_io_revents sd_event_source \* source uint32_t \* ret int sd_event_source_get_io_fd sd_event_source \* source int sd_event_source_set_io_fd sd_event_source \* source int fd int sd_event_source_get_io_fd_own sd_event_source \* source int sd_event_source_set_io_fd_own sd_event_source \* source int b # Description `sd_event_add_io()` adds a new I/O event source to an event loop. The event loop object is specified in the `event` parameter, the event source object is returned in the `source` parameter. The `fd` parameter takes the UNIX file descriptor to watch, which may refer to a socket, a FIFO, a message queue, a serial connection, a character device, or any other file descriptor compatible with Linux `epoll(7)`. The `events` parameter takes a bit mask of events to watch for, a combination of the following event flags: `EPOLLIN`, `EPOLLOUT`, `EPOLLRDHUP`, `EPOLLPRI`, and `EPOLLET`, see `epoll_ctl(2)` for details. Note that not all file descriptors are compatible with epoll, for example regular file or directories are not. If this function is called with a file descriptor that does not support epoll, `-EPERM` is returned (also see below). In most cases such file descriptors may be treated as always-readable or always-writable, so that IO event watching is unnecessary. The `handler` is a function to call when the event source is triggered or `NULL`. The `userdata` pointer will be passed to the handler function, and may be chosen freely by the caller. The handler will also be passed the file descriptor the event was seen on, as well as the actual event flags. It's generally a subset of the events watched, however may additionally include `EPOLLERR` and `EPOLLHUP`. The handler may return negative to signal an error (see below), other return values are ignored. If `handler` is `NULL`, a default handler that calls `sd_event_exit(3)` will be used. By default, an event source will stay enabled continuously (`SD_EVENT_ON`), but this may be changed with `sd_event_source_set_enabled(3)`. If the handler function returns a negative error code, it will either be disabled after the invocation, even if the `SD_EVENT_ON` mode was requested before, or it will cause the loop to terminate, see `sd_event_source_set_exit_on_failure(3)`. Note that an event source set to `SD_EVENT_ON` will fire continuously unless data is read from or written to the file descriptor to reset the mask of events seen. Setting the I/O event mask to watch for to 0 does not mean that the event source will not be triggered anymore, as `EPOLLHUP` and `EPOLLERR` may be triggered even with a zero event mask. To temporarily disable an I/O event source use `sd_event_source_set_enabled(3)` with `SD_EVENT_OFF` instead. To destroy an event source object use `sd_event_source_unref(3)`, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure an event source does not fire anymore, even if it is still referenced, disable the event source using `sd_event_source_set_enabled(3)` with `SD_EVENT_OFF`. If the second parameter of `sd_event_add_io()` is `NULL` no reference to the event source object is returned. In this case, the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed. If the `handler` to `sd_event_add_io()` is `NULL`, and the event source fires, this will be considered a request to exit the event loop. In this case, the `userdata` parameter, cast to an integer, is passed as the exit code parameter to `sd_event_exit(3)`. Note that this call does not take possession of the file descriptor passed in, ownership (and thus the duty to close it when it is no longer needed) remains with the caller. However, with the `sd_event_source_set_io_fd_own()` call (see below) the event source may optionally take ownership of the file descriptor after the event source has been created. In that case the file descriptor is closed automatically as soon as the event source is released. It is recommended to use `sd_event_add_io()` only in conjunction with file descriptors that have `O_NONBLOCK` set, to ensure that all I/O operations from invoked handlers are properly asynchronous and non-blocking. Using file descriptors without `O_NONBLOCK` might result in unexpected starvation of other event sources. See `fcntl(2)` for details on enabling `O_NONBLOCK` mode. `sd_event_source_get_io_events()` retrieves the configured mask of watched I/O events of an event source created previously with `sd_event_add_io()`. It takes the event source object and a pointer to a variable to store the mask in. `sd_event_source_set_io_events()` configures the mask of watched I/O events of an event source created previously with `sd_event_add_io()`. It takes the event source object and the new event mask. `sd_event_source_get_io_revents()` retrieves the I/O event mask of currently seen but undispatched events from an event source created previously with `sd_event_add_io()`. It takes the event source object and a pointer to a variable to store the event mask in. When called from a handler function on the handler's event source object this will return the same mask as passed to the handler's `revents` parameter. This call is primarily useful to check for undispatched events of an event source from the handler of an unrelated (possibly higher priority) event source. Note the relation between `sd_event_source_get_pending()` and `sd_event_source_get_io_revents()`: both functions will report non-zero results when there's an event pending for the event source, but the former applies to all event source types, the latter only to I/O event sources. `sd_event_source_get_io_fd()` retrieves the UNIX file descriptor of an event source created previously with `sd_event_add_io()`. It takes the event source object and returns the non-negative file descriptor or a negative error number on error (see below). `sd_event_source_set_io_fd()` changes the UNIX file descriptor of an I/O event source created previously with `sd_event_add_io()`. It takes the event source object and the new file descriptor as parameters. If the event source owned the previous file descriptor, that is if `sd_event_source_set_io_fd_own()` had been called for the event source with a non-zero value, then the previous file descriptor will be closed and the event source will also take the ownership of the new file descriptor on success. `sd_event_source_set_io_fd_own()` controls whether the file descriptor of the event source shall take ownership of the file descriptor. Takes a boolean parameter `b`. When true (nonzero), the file descriptor will be closed automatically when the event source is freed or when the file descriptor is replaced by `sd_event_source_set_io_fd()`. By default, the descriptor is not owned by the event source, and the application has to do close it on its own if needed. `sd_event_source_get_io_fd_own()` may be used to query the current setting of the file descriptor ownership boolean flag as set with `sd_event_source_set_io_fd_own()`. It returns positive if the file descriptor is closed automatically when the event source is destroyed, zero if not, and negative on error. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned values may indicate the following problems: `-ENOMEM` Not enough memory to allocate an object. `-EINVAL` An invalid argument has been passed. `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. `-EDOM` The passed event source is not an I/O event source. `-EPERM` The passed file descriptor does not support the `epoll(7)` API, for example because it is a regular file or directory. See `epoll_ctl(2)` for details. # History `sd_event_io_handler_t()`, `sd_event_add_io()`, `sd_event_source_get_io_events()`, `sd_event_source_set_io_events()`, `sd_event_source_get_io_revents()`, `sd_event_source_get_io_fd()`, and `sd_event_source_set_io_fd()` were added in version 229. `sd_event_source_get_io_fd_own()` and `sd_event_source_set_io_fd_own()` were added in version 239. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_now(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_priority(3)`, `sd_event_source_set_userdata(3)`, `sd_event_source_set_description(3)`, `sd_event_source_get_pending(3)`, `sd_event_source_set_floating(3)`, `epoll_ctl(2)`, `epoll(7)` # sd_event_add_memory_pressure systemd sd_event_add_memory_pressure 3 sd_event_add_memory_pressure sd_event_source_set_memory_pressure_type sd_event_source_set_memory_pressure_period sd_event_trim_memory sd_event_add_cpu_pressure sd_event_source_set_cpu_pressure_type sd_event_source_set_cpu_pressure_period sd_event_add_io_pressure sd_event_source_set_io_pressure_type sd_event_source_set_io_pressure_period Add and configure an event source for memory, CPU, or IO pressure notifications \#include \ typedef struct sd_event_source sd_event_source; int sd_event_add_memory_pressure sd_event \* event sd_event_source \*\* ret_source sd_event_handler_t handler void \* userdata int sd_event_source_set_memory_pressure_type sd_event_source \* source const char \* type int sd_event_source_set_memory_pressure_period sd_event_source \* source uint64_t threshold_usec uint64_t window_usec int sd_event_add_cpu_pressure sd_event \* event sd_event_source \*\* ret_source sd_event_handler_t handler void \* userdata int sd_event_source_set_cpu_pressure_type sd_event_source \* source const char \* type int sd_event_source_set_cpu_pressure_period sd_event_source \* source uint64_t threshold_usec uint64_t window_usec int sd_event_add_io_pressure sd_event \* event sd_event_source \*\* ret_source sd_event_handler_t handler void \* userdata int sd_event_source_set_io_pressure_type sd_event_source \* source const char \* type int sd_event_source_set_io_pressure_period sd_event_source \* source uint64_t threshold_usec uint64_t window_usec int sd_event_trim_memory void # Description `sd_event_add_memory_pressure()` adds a new event source that is triggered whenever memory pressure is seen. Similarly, `sd_event_add_cpu_pressure()` and `sd_event_add_io_pressure()` add new event sources that are triggered whenever CPU or IO pressure is seen, respectively. This functionality is built around the Linux kernel's [Pressure Stall Information (PSI)](https://docs.kernel.org/accounting/psi.html) logic. These functions expect an event loop object as first parameter, and return the allocated event source object in the second parameter, on success. The `handler` parameter is a function to call when pressure is seen, or `NULL`. The handler function will be passed the `userdata` pointer, which may be chosen freely by the caller. The handler may return negative to signal an error (see below), other return values are ignored. If `handler` is `NULL`, a default handler is used. For `sd_event_add_memory_pressure()`, the default handler compacts allocation caches maintained by `libsystemd` as well as glibc (via `malloc_trim(3)`). For `sd_event_add_cpu_pressure()` and `sd_event_add_io_pressure()`, the default handler is a no-op. It is recommended to pass a custom handler for CPU and IO pressure to take meaningful action when pressure is detected. To destroy an event source object use `sd_event_source_unref(3)`, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure an event source does not fire anymore, even if it is still referenced, disable the event source using `sd_event_source_set_enabled(3)` with `SD_EVENT_OFF`. If the second parameter of `sd_event_add_memory_pressure()`, `sd_event_add_cpu_pressure()`, or `sd_event_add_io_pressure()` is `NULL` no reference to the event source object is returned. In this case, the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed. The memory pressure event source will fire according to the following logic: 1. If the `$MEMORY_PRESSURE_WATCH`/`$MEMORY_PRESSURE_WRITE` environment variables are set at the time the event source is established, it will watch the file, FIFO or AF_UNIX socket specified via `$MEMORY_PRESSURE_WATCH` (which must contain an absolute path name) for `POLLPRI` (in case it is a regular file) or `POLLIN` events (otherwise). After opening the inode, it will write the (decoded) Base64 data provided via `$MEMORY_PRESSURE_WRITE` into it before it starts polling on it (the variable may be unset in which case this is skipped). Typically, if used, `$MEMORY_PRESSURE_WATCH` will contain a path such as `/proc/pressure/memory` or a path to a specific `memory.pressure` file in the control group file system (cgroupfs). 2. If these environment variables are not set, the local PSI interface file `memory.pressure` of the control group the invoking process is running in is used. 3. If that file does not exist, the system-wide PSI interface file `/proc/pressure/memory` is watched instead. The CPU pressure event source follows the same logic, but uses the `$CPU_PRESSURE_WATCH`/`$CPU_PRESSURE_WRITE` environment variables, the `cpu.pressure` cgroup file, and the system-wide PSI interface file `/proc/pressure/cpu` instead. Note that `/proc/pressure/cpu` only provides the `some` line, not the `full` line, so only `some` is valid when watching at the system level. The IO pressure event source follows the same logic, but uses the `$IO_PRESSURE_WATCH`/`$IO_PRESSURE_WRITE` environment variables, the `io.pressure` cgroup file, and the system-wide PSI interface file `/proc/pressure/io` instead. Or in other words: preferably any explicit configuration passed in by an invoking service manager (or similar) is used as notification source, before falling back to local notifications of the service, and finally to global notifications of the system. Well-behaving services and applications are recommended to react to memory pressure events by executing one or more of the following operations, in order to ensure optimal behaviour even on loaded and resource-constrained systems: - Release allocation caches such as `malloc_trim()` or similar, both implemented in the libraries consumed by the program and in private allocation caches of the program itself. - Release any other form of in-memory caches that can easily be recovered if needed (e.g. browser caches). - Terminate idle worker threads or processes, or similar. - Even exit entirely from the program if it is idle and can be automatically started when needed (for example via socket or bus activation). Any of the suggested operations should help easing memory pressure situations and allowing the system to make progress by reclaiming the memory for other purposes. This event source typically fires on memory pressure stalls, i.e. when operational latency above a configured threshold already has been seen. This should be taken into consideration when discussing whether later latency to re-acquire any released resources is acceptable: it is usually more important to think of the latencies that already happened than those coming up in future. The `sd_event_source_set_memory_pressure_type()` and `sd_event_source_set_memory_pressure_period()` functions can be used to fine-tune the PSI parameters for memory pressure notifications. The former takes either `some`, `full` as second parameter, the latter takes threshold and period times in microseconds as parameters. For details about these three parameters see the PSI documentation. Note that these two calls must be invoked immediately after allocating the event source, as they must be configured before polling begins. Also note that these calls will fail if memory pressure parameterization has been passed in via the `$MEMORY_PRESSURE_WATCH`/`$MEMORY_PRESSURE_WRITE` environment variables (or in other words: configuration supplied by a service manager wins over internal settings). Similarly, `sd_event_source_set_cpu_pressure_type()` and `sd_event_source_set_cpu_pressure_period()` can be used to fine-tune the PSI parameters for CPU pressure notifications, and `sd_event_source_set_io_pressure_type()` and `sd_event_source_set_io_pressure_period()` can be used to fine-tune the PSI parameters for IO pressure notifications. They work identically to their memory pressure counterparts. The type parameter takes either `some` or `full`, and the period function takes threshold and period times in microseconds. The same constraints apply: these calls must be invoked immediately after allocating the event source, and will fail if pressure parameterization has been passed in via the corresponding `$*_PRESSURE_WATCH`/`$*_PRESSURE_WRITE` environment variables. The `sd_event_trim_memory()` function releases various internal allocation caches maintained by `libsystemd` and then invokes glibc's `malloc_trim(3)`. This makes the operation executed when the handler function parameter of `sd_event_add_memory_pressure` is passed as `NULL` directly accessible for invocation at any time (see above). This function will log a structured log message at `LOG_DEBUG` level (with message ID f9b0be465ad540d0850ad32172d57c21) about the memory pressure operation. For further details see [Resource Pressure Handling in systemd](https://systemd.io/PRESSURE). # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Not enough memory to allocate an object. `-EINVAL` An invalid argument has been passed. `-EHOSTDOWN` The `$MEMORY_PRESSURE_WATCH`, `$CPU_PRESSURE_WATCH`, or `$IO_PRESSURE_WATCH` variable has been set to the literal string `/dev/null`, in order to explicitly disable pressure handling. `-EBADMSG` The `$MEMORY_PRESSURE_WATCH`, `$CPU_PRESSURE_WATCH`, or `$IO_PRESSURE_WATCH` variable has been set to an invalid string, for example a relative rather than an absolute path. `-ENOTTY` The `$MEMORY_PRESSURE_WATCH`, `$CPU_PRESSURE_WATCH`, or `$IO_PRESSURE_WATCH` variable points to a regular file outside of the procfs or cgroupfs file systems. `-EOPNOTSUPP` No configuration via `$MEMORY_PRESSURE_WATCH`, `$CPU_PRESSURE_WATCH`, or `$IO_PRESSURE_WATCH` has been specified and the local kernel does not support the PSI interface. `-EBUSY` This is returned by `sd_event_source_set_memory_pressure_type()`, `sd_event_source_set_memory_pressure_period()`, `sd_event_source_set_cpu_pressure_type()`, `sd_event_source_set_cpu_pressure_period()`, `sd_event_source_set_io_pressure_type()`, and `sd_event_source_set_io_pressure_period()` if invoked on event sources at a time later than immediately after allocating them. `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. `-EDOM` The passed event source is not a signal event source. # History `sd_event_add_memory_pressure()`, `sd_event_source_set_memory_pressure_type()`, `sd_event_source_set_memory_pressure_period()`, and `sd_event_trim_memory()` were added in version 254. `sd_event_add_cpu_pressure()`, `sd_event_source_set_cpu_pressure_type()`, `sd_event_source_set_cpu_pressure_period()`, `sd_event_add_io_pressure()`, `sd_event_source_set_io_pressure_type()`, and `sd_event_source_set_io_pressure_period()` were added in version 261. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_description(3)`, `sd_event_source_set_userdata(3)`, `sd_event_source_set_floating(3)` # sd_event_add_signal systemd sd_event_add_signal 3 sd_event_add_signal sd_event_source_get_signal sd_event_signal_handler_t SD_EVENT_SIGNAL_PROCMASK Add a UNIX process signal event source to an event loop \#include \ typedef struct sd_event_source sd_event_source; SD_EVENT_SIGNAL_PROCMASK typedef int (\* sd_event_signal_handler_t ) sd_event_source \* s const struct signalfd_siginfo \* si void \* userdata int sd_event_add_signal sd_event \* event sd_event_source \*\* source int signal sd_event_signal_handler_t handler void \* userdata int sd_event_source_get_signal sd_event_source \* source # Description `sd_event_add_signal()` adds a new UNIX process signal event source to an event loop. The event loop object is specified in the `event` parameter, and the event source object is returned in the `source` parameter. The `signal` parameter specifies the numeric signal to be handled (see `signal(7)`). The `handler` parameter is a function to call when the signal is received or `NULL`. The handler function will be passed the `userdata` pointer, which may be chosen freely by the caller. The handler also receives a pointer to a signalfd_siginfo structure containing information about the received signal. See `signalfd(2)` for further information. The handler may return negative to signal an error (see below), other return values are ignored. If `handler` is `NULL`, a default handler that calls `sd_event_exit(3)` will be used. Only a single handler may be installed for a specific signal. The signal must be blocked in all threads before this function is called (using `sigprocmask(2)` or `pthread_sigmask(3)`). For convenience, if the special flag `SD_EVENT_SIGNAL_PROCMASK` is ORed into the specified signal the signal will be automatically masked as necessary, for the calling thread. Note that this only works reliably if the signal is already masked in all other threads of the process, or if there are no other threads at the moment of invocation. By default, the event source is enabled permanently (`SD_EVENT_ON`), but this may be changed with `sd_event_source_set_enabled(3)`. If the handler function returns a negative error code, it will either be disabled after the invocation, even if the `SD_EVENT_ON` mode was requested before, or it will cause the loop to terminate, see `sd_event_source_set_exit_on_failure(3)`. To destroy an event source object use `sd_event_source_unref(3)`, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure an event source does not fire anymore, even if it is still referenced, disable the event source using `sd_event_source_set_enabled(3)` with `SD_EVENT_OFF`. If the second parameter of `sd_event_add_signal()` is `NULL` no reference to the event source object is returned. In this case, the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed. If the `handler` parameter to `sd_event_add_signal()` is `NULL`, and the event source fires, this will be considered a request to exit the event loop. In this case, the `userdata` parameter, cast to an integer, is passed as the exit code parameter to `sd_event_exit(3)`. `sd_event_source_get_signal()` returns the configured signal number of an event source created previously with `sd_event_add_signal()`. It takes the event source object as the `source` parameter. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Not enough memory to allocate an object. `-EINVAL` An invalid argument has been passed. `-EBUSY` A handler is already installed for this signal or the signal was not blocked previously. `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. `-EDOM` The passed event source is not a signal event source. # History `sd_event_add_signal()`, `sd_event_signal_handler_t()`, and `sd_event_source_get_signal()` were added in version 217. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_now(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_description(3)`, `sd_event_source_set_userdata(3)`, `sd_event_source_set_floating(3)`, `signal(7)`, `signalfd(2)`, `sigprocmask(2)`, `pthread_sigmask(3)` # sd_event_add_time systemd sd_event_add_time 3 sd_event_add_time sd_event_add_time_relative sd_event_source_get_time sd_event_source_set_time sd_event_source_set_time_relative sd_event_source_get_time_accuracy sd_event_source_set_time_accuracy sd_event_source_get_time_clock sd_event_time_handler_t Add a timer event source to an event loop \#include \ typedef struct sd_event_source sd_event_source; typedef int (\* sd_event_time_handler_t ) sd_event_source \* s uint64_t usec void \* userdata int sd_event_add_time sd_event \* event sd_event_source \*\* source clockid_t clock uint64_t usec uint64_t accuracy sd_event_time_handler_t handler void \* userdata int sd_event_add_time_relative sd_event \* event sd_event_source \*\* source clockid_t clock uint64_t usec uint64_t accuracy sd_event_time_handler_t handler void \* userdata int sd_event_source_get_time sd_event_source \* source uint64_t \* ret int sd_event_source_set_time sd_event_source \* source uint64_t usec int sd_event_source_set_time_relative sd_event_source \* source uint64_t usec int sd_event_source_get_time_accuracy sd_event_source \* source uint64_t \* ret int sd_event_source_set_time_accuracy sd_event_source \* source uint64_t usec int sd_event_source_get_time_clock sd_event_source \* source clockid_t \* ret # Description `sd_event_add_time()` adds a new timer event source to an event loop. The event loop object is specified in the `event` parameter, the event source object is returned in the `source` parameter. The `clock` parameter takes a clock identifier, one of `CLOCK_REALTIME`, `CLOCK_MONOTONIC`, `CLOCK_BOOTTIME`, `CLOCK_REALTIME_ALARM`, or `CLOCK_BOOTTIME_ALARM`. See `timerfd_create(2)` for details regarding the various types of clocks. The `usec` parameter specifies the earliest time, in microseconds (μs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past is specified (including `0`), this timer source "fires" immediately and is ready to be dispatched. If the parameter is specified as `UINT64_MAX` the timer event will never elapse, which may be used as an alternative to explicitly disabling a timer event source with `sd_event_source_set_enabled(3)`. The `accuracy` parameter specifies an additional accuracy value in μs specifying how much the timer event may be delayed. Use `0` to select the default accuracy (250ms). Use 1μs for maximum accuracy. Consider specifying 60000000μs (1min) or larger for long-running events that may be delayed substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, improving power efficiency. The `handler` is a function to call when the timer elapses or `NULL`. The `userdata` pointer will be passed to the handler function, and may be chosen freely by the caller. The configured trigger time is also passed to the handler, even if the call actually happens slightly later, subject to the specified accuracy value, the kernel timer slack (see `prctl(2)`), and additional scheduling latencies. To query the actual time the handler was called use `sd_event_now(3)`. The handler may return negative to signal an error (see below), other return values are ignored. If `handler` is `NULL`, a default handler that calls `sd_event_exit(3)` will be used. By default, the timer will elapse once (`SD_EVENT_ONESHOT`), but this may be changed with `sd_event_source_set_enabled(3)`. If the handler function returns a negative error code, it will either be disabled after the invocation, even if the `SD_EVENT_ON` mode was requested before, or it will cause the loop to terminate, see `sd_event_source_set_exit_on_failure(3)`. Note that a timer event set to `SD_EVENT_ON` will fire continuously unless its configured time is updated using `sd_event_source_set_time()`. `sd_event_add_time_relative()` is like `sd_event_add_time()`, but takes a relative time specification. It's relative to the current time of the event loop iteration, as returned by `sd_event_now(3)`. To destroy an event source object use `sd_event_source_unref(3)`, but note that the event source is only removed from the event loop when all references to the event source are dropped. To make sure an event source does not fire anymore, even if it is still referenced, disable the event source using `sd_event_source_set_enabled(3)` with `SD_EVENT_OFF`. If the second parameter of `sd_event_add_time()` is `NULL` no reference to the event source object is returned. In this case, the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed. If the `handler` parameter to `sd_event_add_time()` is `NULL`, and the event source fires, this will be considered a request to exit the event loop. In this case, the `userdata` parameter, cast to an integer, is passed as the exit code parameter to `sd_event_exit(3)`. Use `CLOCK_BOOTTIME_ALARM` and `CLOCK_REALTIME_ALARM` to define event sources that may wake up the system from suspend. In order to set up relative timers (that is, relative to the current time), retrieve the current time via `sd_event_now(3)`, add the desired timespan to it, and use the result as the `usec` parameter to `sd_event_add_time()`. In order to set up repetitive timers (that is, timers that are triggered in regular intervals), set up the timer normally, for the first invocation. Each time the event handler is invoked, update the timer's trigger time with `sd_event_source_set_time(3)` for the next timer iteration, and reenable the timer using `sd_event_source_set_enabled()`. To calculate the next point in time to pass to `sd_event_source_set_time()`, either use as base the `usec` parameter passed to the timer callback, or the timestamp returned by `sd_event_now()`. In the former case timer events will be regular, while in the latter case, the scheduling latency will keep accumulating on the timer. `sd_event_source_get_time()` retrieves the configured time value of an event source created previously with `sd_event_add_time()` or `sd_event_add_time_relative()`. It takes the event source object and a pointer to a variable to store the time in, relative to the selected clock's epoch, in μs. The returned value is relative to the epoch, even if the event source was created with a relative time via `sd_event_add_time_relative()`. `sd_event_source_set_time()` changes the time of an event source created previously with `sd_event_add_time()` or `sd_event_add_time_relative()`. It takes the event source object and a time relative to the selected clock's epoch, in μs. `sd_event_source_set_time_relative()` is similar to `sd_event_source_set_time()`, but takes a time relative to the current time of the event loop iteration, as returned by `sd_event_now()`. `sd_event_source_get_time_accuracy()` retrieves the configured accuracy value of an event source created previously with `sd_event_add_time()`. It takes the event source object and a pointer to a variable to store the accuracy in. The accuracy is specified in μs. `sd_event_source_set_time_accuracy()` changes the configured accuracy of a timer event source created previously with `sd_event_add_time()`. It takes the event source object and accuracy, in μs. `sd_event_source_get_time_clock()` retrieves the configured clock of an event source created previously with `sd_event_add_time()`. It takes the event source object and a pointer to a variable to store the clock identifier in. # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned values may indicate the following problems: `-ENOMEM` Not enough memory to allocate an object. `-EINVAL` An invalid argument has been passed. `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. `-EOPNOTSUPP` The selected clock is not supported by the event loop implementation. `-EDOM` The passed event source is not a timer event source. `-EOVERFLOW` The passed relative time is outside of the allowed range for time values (i.e. the specified value added to the current time is outside the 64 bit unsigned integer range). # History `sd_event_add_time()`, `sd_event_source_get_time()`, `sd_event_source_set_time()`, `sd_event_source_get_time_accuracy()`, `sd_event_source_set_time_accuracy()`, and `sd_event_source_get_time_clock()` were added in version 213. `sd_event_time_handler_t()` was added in version 217. `sd_event_add_time_relative()` and `sd_event_source_set_time_relative()` were added in version 247. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_now(3)`, `sd_event_add_io(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_priority(3)`, `sd_event_source_set_userdata(3)`, `sd_event_source_set_description(3)`, `sd_event_source_set_floating(3)`, `clock_gettime(2)`, `timerfd_create(2)`, `prctl(2)` # sd_event_exit systemd sd_event_exit 3 sd_event_exit sd_event_get_exit_code Ask the event loop to exit \#include \ int sd_event_exit sd_event \* event int code int sd_event_get_exit_code sd_event \* event int \* ret # Description `sd_event_exit()` requests the event loop specified in the `event` event loop object to exit. The `code` parameter may be any integer value and is returned as-is by `sd_event_loop(3)` after the last event loop iteration. It may also be queried using `sd_event_get_exit_code()`, see below. When exiting is requested the event loop will stop listening for and dispatching regular event sources. Instead it will proceed with executing only event sources registered with `sd_event_add_exit(3)` in the order defined by their priority. After all exit event sources have been dispatched the event loop is terminated. If `sd_event_exit()` is invoked a second time while the event loop is still processing exit event sources, the exit code stored in the event loop object is updated, but otherwise no further operation is executed. `sd_event_get_exit_code()` may be used to query the exit code passed to an earlier call of `sd_event_exit()`. The return parameter `ret` may be set to `NULL`, in order to simply check if `sd_event_exit()` has been called before (as `sd_event_get_exit_code()` fails with `-ENODATA` if that's not the case, see below). While the full positive and negative integer ranges may be used for the exit code, care should be taken not pick exit codes that conflict with regular exit codes returned by `sd_event_loop()`, if these exit codes shall be distinguishable. Note that for most event source types passing the callback pointer as `NULL` in the respective constructor call (i.e. in `sd_event_add_time(3)`, `sd_event_add_signal(3)`, …) has the effect of `sd_event_exit()` being invoked once the event source triggers, with the specified userdata pointer cast to an integer as the exit code parameter. This is useful to automatically terminate an event loop after some condition, such as a timeout or reception of `SIGTERM` or similar. See the documentation for the respective constructor call for details. # Return Value On success, `sd_event_exit()` and `sd_event_get_exit_code()` return 0 or a positive integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The event loop object or error code pointer are invalid. `-ECHILD` The event loop was created in a different process, library or module instance. `-ESTALE` The event loop has exited already and all exit handlers are already processed. `-ENODATA` Returned by `sd_event_get_exit_code()` in case the event loop has not been requested to exit yet. # History `sd_event_exit()` and `sd_event_get_exit_code()` were added in version 229. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_add_exit(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_io(3)`, `sd_event_add_defer(3)`, `sd_event_add_inotify(3)` # sd_event_get_fd systemd sd_event_get_fd 3 sd_event_get_fd Obtain a file descriptor to poll for event loop events \#include \ int sd_event_get_fd sd_event \* event # Description `sd_event_get_fd()` returns the file descriptor that an event loop object returned by the `sd_event_new(3)` function uses to wait for events. This file descriptor may itself be polled for `POLLIN`/`EPOLLIN` events. This makes it possible to embed an `sd-event(3)` event loop into another, possibly foreign, event loop. The returned file descriptor refers to an `epoll(7)` object. It is recommended not to alter it by invoking `epoll_ctl(2)` on it, in order to avoid interference with the event loop's inner logic and assumptions. # Return Value On success, `sd_event_get_fd()` returns a non-negative file descriptor. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `event` is not a valid pointer to an sd_event structure. `-ECHILD` The event loop has been created in a different process, library or module instance. # Examples
Integration in the GLib event loop
# History `sd_event_get_fd()` was added in version 217. # See Also `sd-event(3)`, `sd_event_new(3)`, `sd_event_wait(3)`, `epoll_ctl(2)`, `epoll(7)` # sd_event_new systemd sd_event_new 3 sd_event_new sd_event_default sd_event_ref sd_event_unref sd_event_unrefp sd_event_get_tid sd_event Acquire and release an event loop object \#include \ typedef struct sd_event sd_event; int sd_event_new sd_event \*\* event int sd_event_default sd_event \*\* event sd_event \* sd_event_ref sd_event \* event sd_event \* sd_event_unref sd_event \* event void sd_event_unrefp sd_event \*\* event int sd_event_get_tid sd_event \* event pid_t \* ret # Description `sd_event_new()` allocates a new event loop object. The event loop object is returned in the `event` parameter. After use, drop the returned reference with `sd_event_unref()`. When the last reference is dropped, the object is freed. `sd_event_default()` acquires a reference to the default event loop object of the calling thread, possibly allocating a new object if no default event loop object has been allocated yet for the thread. After use, drop the returned reference with `sd_event_unref()`. When the last reference is dropped, the event loop is freed. If this function is called while the object returned from a previous call from the same thread is still referenced, the same object is returned again, but the reference is increased by one. It is recommended to use this call instead of `sd_event_new()` in order to share event loop objects between various components that are dispatched in the same thread. All threads have exactly either zero or one default event loop objects associated, but never more. After allocating an event loop object, add event sources to it with `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_add_post(3)` or `sd_event_add_exit(3)`, and then execute the event loop using `sd_event_loop(3)`. `sd_event_ref()` increases the reference count of the specified event loop object by one. `sd_event_unref()` decreases the reference count of the specified event loop object by one. If the count hits zero, the object is freed. Note that it is freed regardless of whether it is the default event loop object for a thread or not. This means that allocating an event loop with `sd_event_default()`, then releasing it, and then acquiring a new one with `sd_event_default()` will result in two distinct objects. Note that, in order to free an event loop object, all remaining event sources of the event loop also need to be freed as each keeps a reference to it. `sd_event_unrefp()` is similar to `sd_event_unref()` but takes a pointer to a pointer to an `sd_event` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). Note that this function is defined as inline function. Use a declaration like the following, in order to allocate an event loop object that is freed automatically as the code block is left: { __attribute__((cleanup(sd_event_unrefp))) sd_event *event = NULL; int r; … r = sd_event_default(&event); if (r < 0) { errno = -r; fprintf(stderr, "Failed to allocate event loop: %m\n"); } … } `sd_event_ref()`, `sd_event_unref()` and `sd_event_unrefp()` execute no operation if the passed in event loop object is `NULL`. `sd_event_get_tid()` retrieves the thread identifier ("TID") of the thread the specified event loop object is associated with. This call is only supported for event loops allocated with `sd_event_default()`, and returns the identifier for the thread the event loop is the default event loop of. See `gettid(2)` for more information on thread identifiers. # Return Value On success, `sd_event_new()`, `sd_event_default()` and `sd_event_get_tid()` return 0 or a positive integer. On failure, they return a negative errno-style error code. `sd_event_ref()` always returns a pointer to the event loop object passed in. `sd_event_unref()` always returns `NULL`. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Not enough memory to allocate the object. `-EMFILE` The maximum number of event loops has been allocated. `-ENXIO` `sd_event_get_tid()` was invoked on an event loop object that was not allocated with `sd_event_default()`. # History `sd_event_new()`, `sd_event_default()`, `sd_event_ref()`, and `sd_event_unref()` were added in version 213. `sd_event_unrefp()` and `sd_event_get_tid()` were added in version 229. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_run(3)`, `gettid(2)` # sd_event_now systemd sd_event_now 3 sd_event_now Retrieve current event loop iteration timestamp \#include \ int sd_event_now sd_event \* event clockid_t clock uint64_t \* ret # Description `sd_event_now()` returns the time when the most recent event loop iteration began. A timestamp is taken right after returning from the event sleep, and before dispatching any event sources. The `event` parameter specifies the event loop object to retrieve the timestamp from. The `clock` parameter specifies the clock to retrieve the timestamp for, and is one of `CLOCK_REALTIME` (or equivalently `CLOCK_REALTIME_ALARM`), `CLOCK_MONOTONIC`, or `CLOCK_BOOTTIME` (or equivalently `CLOCK_BOOTTIME_ALARM`), see `clock_gettime(2)` for more information on the various clocks. The retrieved timestamp is stored in the `ret` parameter, in μs since the clock's epoch. If this function is invoked before the first event loop iteration, the current time is returned, as reported by `clock_gettime()`. To distinguish this case from a regular invocation the return value will be positive, and zero when the returned timestamp refers to an actual event loop iteration. # Return Value If the first event loop iteration has not run yet `sd_event_now()` writes current time to `ret` and returns a positive return value. Otherwise, it will write the requested timestamp to `ret` and return 0. On failure, the call returns a negative errno-style error code. ## Errors Returned values may indicate the following problems: `-EINVAL` An invalid parameter was passed. `-EOPNOTSUPP` Unsupported clock type. `-ECHILD` The event loop object was created in a different process, library or module instance. # History `sd_event_now()` was added in version 229. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_add_time(3)`, `clock_gettime(2)` # sd_event_run systemd sd_event_run 3 sd_event_run sd_event_loop Run an event loop \#include \ int sd_event_run sd_event \* event uint64_t usec int sd_event_loop sd_event \* event # Description `sd_event_run()` may be used to run a single iteration of the event loop specified in the `event` parameter. The function waits until an event to process is available, and dispatches the registered handler for it. The `usec` parameter specifies the maximum time (in microseconds) to wait for an event. Use `(uint64_t) -1` to specify an infinite timeout. `sd_event_loop()` invokes `sd_event_run()` in a loop, thus implementing the actual event loop. The call returns as soon as exiting was requested using `sd_event_exit(3)`. The event loop object `event` is created with `sd_event_new(3)`. Events sources to wait for and their handlers may be registered with `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_defer(3)`, `sd_event_add_post(3)` and `sd_event_add_exit(3)`. For low-level control of event loop execution, use `sd_event_prepare(3)`, `sd_event_wait(3)` and `sd_event_dispatch(3)` which are wrapped by `sd_event_run()`. Along with `sd_event_get_fd(3)`, these functions allow integration of an `sd-event(3)` event loop into foreign event loop implementations. # Return Value On failure, these functions return a negative errno-style error code. `sd_event_run()` returns a positive, non-zero integer if an event source was dispatched, and zero when the specified timeout hit before an event source has seen any event, and hence no event source was dispatched. `sd_event_loop()` returns the exit code specified when invoking `sd_event_exit()`. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `event` parameter is invalid or `NULL`. `-EBUSY` The event loop object is not in the right state (see `sd_event_prepare(3)` for an explanation of possible states). `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. Other errors are possible, too. # History `sd_event_run()` and `sd_event_loop()` were added in version 220. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_exit(3)`, `sd_event_get_fd(3)`, `sd_event_wait(3)`, [GLib Main Event Loop](https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html) # sd_event_set_exit_on_idle systemd sd_event_set_exit_on_idle 3 sd_event_set_exit_on_idle sd_event_get_exit_on_idle Enable event loop exit-on-idle support \#include \ int sd_event_set_exit_on_idle sd_event \* event int b int sd_event_get_exit_on_idle sd_event \* event # Description `sd_event_set_exit_on_idle()` may be used to enable or disable the exit-on-idle support in the event loop object specified in the `event` parameter. If enabled, the event loop will exit with a zero exit code there are no more enabled (`SD_EVENT_ON`, `SD_EVENT_ONESHOT`), non-exit, non-post event sources. `sd_event_get_exit_on_idle()` may be used to determine whether exit-on-idle support was previously requested by a call to `sd_event_set_exit_on_idle()` with a true `b` parameter and successfully enabled. # Return Value On success, `sd_event_set_exit_on_idle()` and `sd_event_get_exit_on_idle()` return a non-zero positive integer if the exit-on-idle support was successfully enabled. They return zero if the exit-on-idle support was explicitly disabled with a false `b` parameter. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The event loop has been created in a different process, library or module instance. `-EINVAL` The passed event loop object was invalid. # History `sd_event_set_exit_on_idle()` and `sd_event_get_exit_on_idle()` were added in version 259. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `systemd.service(5)` # sd_event_set_signal_exit systemd sd_event_set_signal_exit 3 sd_event_set_signal_exit Automatically leave event loop on SIGINT and SIGTERM \#include \ int sd_event_set_signal_exit sd_event \* event int b # Description `sd_event_set_signal_exit()` may be used to ensure the event loop terminates once a `SIGINT` or `SIGTERM` signal is received. It is a convenience wrapper around invocations of `sd_event_add_signal(3)` for both signals. The two signals are automatically added to the calling thread's signal mask (if a program is multi-threaded care should be taken to either invoke this function before the first thread is started or to manually block the two signals process-wide first). If the parameter `b` is specified as true, the event loop will terminate on `SIGINT` and `SIGTERM`. If specified as false, it will no longer. When this functionality is turned off the calling thread's signal mask is restored to match the state before it was turned on, for the two signals. By default, the two signals are not handled by the event loop, and Linux' default signal handling for them is in effect. It is customary for UNIX programs to exit on either of these two signals, hence it is typically a good idea to enable this functionality for the main event loop of a program. # Return Value `sd_event_set_signal_exit()` returns a positive non-zero value when the setting was successfully changed. It returns a zero when the specified setting was already in effect. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The event loop has been created in a different process, library or module instance. `-EINVAL` The passed event loop object was invalid. # History `sd_event_set_signal_exit()` was added in version 252. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_add_signal(3)` # sd_event_set_watchdog systemd sd_event_set_watchdog 3 sd_event_set_watchdog sd_event_get_watchdog Enable event loop watchdog support \#include \ int sd_event_set_watchdog sd_event \* event int b int sd_event_get_watchdog sd_event \* event # Description `sd_event_set_watchdog()` may be used to enable or disable automatic watchdog notification support in the event loop object specified in the `event` parameter. Specifically, depending on the `b` boolean argument this will make sure the event loop wakes up in regular intervals and sends watchdog notification messages to the service manager, if this was requested by the service manager. Watchdog support is determined with `sd_watchdog_enabled(3)`, and watchdog messages are sent with `sd_notify(3)`. See the `WatchdogSec=` setting in `systemd.service(5)` for details on how to enable watchdog support for a service and the protocol used. The wake-up interval is chosen as half the watchdog timeout declared by the service manager via the `$WATCHDOG_USEC` environment variable. If the service manager did not request watchdog notifications, or if the process was not invoked by the service manager this call with a true `b` parameter executes no operation. Passing a false `b` parameter will disable the automatic sending of watchdog notification messages if it was enabled before. Newly allocated event loop objects have this feature disabled. The first watchdog notification message is sent immediately when `sd_event_set_watchdog()` is invoked with a true `b` parameter. The watchdog logic is designed to allow the service manager to automatically detect services that ceased processing of incoming events, and thus appear "hung". Watchdog notifications are sent out only at the beginning of each event loop iteration. If an event source dispatch function blocks for an excessively long time and does not return execution to the event loop quickly, this might hence cause the notification message to be delayed, and possibly result in abnormal program termination, as configured in the service unit file. `sd_event_get_watchdog()` may be used to determine whether watchdog support was previously requested by a call to `sd_event_set_watchdog()` with a true `b` parameter and successfully enabled. # Return Value On success, `sd_event_set_watchdog()` and `sd_event_get_watchdog()` return a non-zero positive integer if the service manager requested watchdog support and watchdog support was successfully enabled. They return zero if the service manager did not request watchdog support, or if watchdog support was explicitly disabled with a false `b` parameter. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ECHILD` The event loop has been created in a different process, library or module instance. `-EINVAL` The passed event loop object was invalid. # History `sd_event_set_watchdog()` and `sd_event_get_watchdog()` were added in version 229. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_new(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_watchdog_enabled(3)`, `sd_notify(3)`, `systemd.service(5)` # sd_event_source_get_event systemd sd_event_source_get_event 3 sd_event_source_get_event Retrieve the event loop of an event source \#include \ sd_event\* sd_event_source_get_event sd_event_source \* source # Description `sd_event_source_get_event()` may be used to retrieve the event loop object the event source object specified as `source` is associated with. The event loop object is specified when creating an event source object with calls such as `sd_event_add_io(3)` or `sd_event_add_time(3)`. # Return Value On success, `sd_event_source_get_event()` returns the associated event loop object. On failure, it returns `NULL`. # History `sd_event_source_get_event()` was added in version 229. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_userdata(3)` # sd_event_source_get_pending systemd sd_event_source_get_pending 3 sd_event_source_get_pending Determine pending state of event sources \#include \ int sd_event_source_get_pending sd_event_source \* source # Description `sd_event_source_get_pending()` may be used to determine whether the event source object specified as `source` has seen events but has not been dispatched yet (and thus is marked "pending"). Event source objects initially are not marked pending, when they are created with calls such as `sd_event_add_io(3)`, `sd_event_add_time(3)`, with the exception of those created with `sd_event_add_defer(3)` which are immediately marked pending, and `sd_event_add_exit(3)` for which the "pending" concept is not defined. For details see the respective manual pages. In each event loop iteration one event source of those marked pending is dispatched, in the order defined by the event source priority, as set with `sd_event_source_set_priority(3)`. For I/O event sources, as created with `sd_event_add_io(3)`, the call `sd_event_source_get_io_revents(3)` may be used to query the type of event pending in more detail. # Return Value On success, `sd_event_source_get_pending()` returns an integer greater than zero when the event source is marked pending, and zero when the event source is not marked pending. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `source` is not a valid pointer to an sd_event_source object. `-EDOM` `source` refers to an event source object created with `sd_event_add_exit(3)`. `-ENOMEM` Not enough memory. `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. # History `sd_event_source_get_pending()` was added in version 229. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_unref(3)` # sd_event_source_set_description systemd sd_event_source_set_description 3 sd_event_source_set_description sd_event_source_get_description Set or retrieve descriptive names of event sources \#include \ int sd_event_source_set_description sd_event_source \* source const char \* description int sd_event_source_get_description sd_event_source \* source const char \*\* ret # Description `sd_event_source_set_description()` may be used to set an arbitrary descriptive name for the event source object specified as `source`. This name will be used in debugging messages generated by `sd-event(3)` for this event source, and may be queried using `sd_event_source_get_description()` for debugging purposes. The `description` parameter shall point to a `NUL`-terminated string or be `NULL`. In the latter case, the descriptive name will be unset. The string is copied internally, hence the `description` argument is not referenced after the function returns. `sd_event_source_get_description()` may be used to query the current descriptive name assigned to the event source object `source`. It returns a pointer to the current name in `ret`, stored in memory internal to the event source. The memory is invalidated when the event source is destroyed or the descriptive name is changed. Event source objects generally have no description set when they are created, except for UNIX signal event sources created with `sd_event_add_signal(3)`, whose descriptive name is initialized to the signal's C constant name (e.g. `SIGINT` or `SIGTERM`). # Return Value On success, `sd_event_source_set_description()` and `sd_event_source_get_description()` return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `source` is not a valid pointer to an sd_event_source object or the `description` argument for `sd_event_source_get_description()` is `NULL`. `-ENOMEM` Not enough memory to copy the name. `-ECHILD` The event loop has been created in a different process, library or module instance. `-ENXIO` No name was set for the event source. # History `sd_event_source_set_description()` and `sd_event_source_get_description()` were added in version 229. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_userdata(3)` # sd_event_source_set_destroy_callback systemd sd_event_source_set_destroy_callback 3 sd_event_source_set_destroy_callback sd_event_source_get_destroy_callback sd_event_destroy_t Define the callback function for resource cleanup \#include \ typedef int (\* sd_event_destroy_t ) void \* userdata int sd_event_source_set_destroy_callback sd_event_source \* source sd_event_destroy_t callback int sd_event_source_get_destroy_callback sd_event_source \* source sd_event_destroy_t \* callback # Description `sd_event_source_set_destroy_callback()` sets `callback` as the callback function to be called right before the event source object `source` is deallocated. The `userdata` pointer from the event source object will be passed as the `userdata` parameter. This pointer can be set by an argument to the constructor functions, see `sd_event_add_io(3)`, or directly, see `sd_event_source_set_userdata(3)`. This callback function is called even if `userdata` is `NULL`. Note that this callback is invoked at a time where the event source object itself is already invalidated, and executing operations or taking new references to the event source object is not permissible. `sd_event_source_get_destroy_callback()` returns the current callback for `source` in the `callback` parameter. # Return Value On success, `sd_event_source_set_destroy_callback()` returns 0 or a positive integer. On failure, it returns a negative errno-style error code. `sd_event_source_get_destroy_callback()` returns positive if the destroy callback function is set, 0 if not. On failure, returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `source` parameter is `NULL`. # History `sd_event_destroy_t()`, `sd_event_source_set_destroy_callback()`, and `sd_event_source_get_destroy_callback()` were added in version 239. # See Also `systemd(1)`, `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_userdata(3)` # sd_event_source_set_enabled systemd sd_event_source_set_enabled 3 sd_event_source_set_enabled sd_event_source_get_enabled SD_EVENT_ON SD_EVENT_OFF SD_EVENT_ONESHOT Enable or disable event sources \#include \ enum { SD_EVENT_OFF = 0, SD_EVENT_ON = 1, SD_EVENT_ONESHOT = -1, }; int sd_event_source_set_enabled sd_event_source \* source int enabled int sd_event_source_get_enabled sd_event_source \* source int \* ret # Description `sd_event_source_set_enabled()` may be used to enable or disable the event source object specified as `source`. The `enabled` parameter takes one of `SD_EVENT_ON` (to enable), `SD_EVENT_OFF` (to disable) or `SD_EVENT_ONESHOT`. If invoked with `SD_EVENT_ONESHOT` the event source will be enabled but automatically reset to `SD_EVENT_OFF` after one dispatch. For `SD_EVENT_OFF`, the event source `source` may be `NULL`, in which case the function does nothing. Otherwise, `source` must be a valid pointer to an sd_event_source object. Event sources that are disabled will not result in event loop wakeups and will not be dispatched, until they are enabled again. `sd_event_source_get_enabled()` may be used to query whether the event source object `source` is currently enabled or not. If both the `source` and the output parameter `ret` are `NULL`, this function returns false. Otherwise, `source` must be a valid pointer to an sd_event_source object. If the output parameter `ret` is not `NULL`, it is set to the enablement state (one of `SD_EVENT_ON`, `SD_EVENT_OFF`, `SD_EVENT_ONESHOT`). The function also returns true if the event source is not disabled. Event source objects are enabled when they are first created with calls such as `sd_event_add_io(3)`, `sd_event_add_time(3)`. However, depending on the event source type they are enabled continuously (`SD_EVENT_ON`) or only for a single invocation of the event source handler (`SD_EVENT_ONESHOT`). For details see the respective manual pages. As event source objects stay active and may be dispatched as long as there is at least one reference to them, in many cases it is a good idea to combine a call to `sd_event_source_unref(3)` with a prior call to `sd_event_source_set_enabled()` with `SD_EVENT_OFF`, to ensure the event source is not dispatched again until all other remaining references are dropped. # Return Value On success, `sd_event_source_set_enabled()` returns a non-negative integer. `sd_event_source_get_enabled()` returns zero if the source is disabled (`SD_EVENT_OFF`) and a positive integer otherwise. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `source` is not a valid pointer to an sd_event_source object. `-ENOMEM` Not enough memory. `-ECHILD` The event loop has been created in a different process, library or module instance. # History `sd_event_source_set_enabled()` and `sd_event_source_get_enabled()` were added in version 229. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_unref(3)`, `sd_event_source_set_ratelimit(3)` # sd_event_source_set_exit_on_failure systemd sd_event_source_set_exit_on_failure 3 sd_event_source_set_exit_on_failure sd_event_source_get_exit_on_failure Set or retrieve the exit-on-failure feature of event sources \#include \ int sd_event_source_set_exit_on_failure sd_event_source \* source int b int sd_event_source_get_exit_on_failure sd_event_source \* source # Description `sd_event_source_set_exit_on_failure()` may be used to set/unset the exit-on-failure flag of the event source object specified as `source`. The flag defaults to off. If on and the callback function set for the event source returns a failure code (i.e. a negative value) the event loop is exited too, using the callback return code as the exit code for `sd_event_exit(3)`. If off, the event source is disabled but the event loop continues to run. Setting this flag is useful for "dominant" event sources that define the purpose and reason for the event loop, and whose failure hence should propagate to the event loop itself — as opposed to "auxiliary" event sources whose failures should remain local and affect the event source, but not propagate further. `sd_event_source_get_exit_on_failure()` may be used to query the flag currently set for the event source object `source`. # Return Value On success, `sd_event_source_set_exit_on_failure()` returns a non-negative integer. `sd_event_source_get_exit_on_failure()` returns 0 if the flag is off, \> 0 if the flag is on. On failure, both return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `source` is not a valid pointer to an sd_event_source object. `-EDOM` The event source refers to an exit event source (as created with `sd_event_add_exit(3)`), for which this functionality is not supported. # History `sd_event_source_set_exit_on_failure()` and `sd_event_source_get_exit_on_failure()` were added in version 247. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)` # sd_event_source_set_floating systemd sd_event_source_set_floating 3 sd_event_source_set_floating sd_event_source_get_floating Set or retrieve 'floating' state of event sources \#include \ int sd_event_source_set_floating sd_event_source \* source int floating int sd_event_source_get_floating sd_event_source \* source # Description `sd_event_source_set_floating()` takes a boolean and sets the 'floating' state of the specified event source object. This is used to change the direction of reference counts for the object and the event loop it is associated with. In non-floating mode, the event source object holds a reference to the event loop object, but not vice versa. The creator of the event source object must hold a reference to it as long as the source should exist. In floating mode, the event loop holds a reference to the source object, and will decrease the reference count when being freed. This means that a reference to the event loop should be held to prevent both from being destroyed. Various calls that allocate event source objects (i.e. `sd_event_add_io(3)`, `sd_event_add_time(3)` and similar) will automatically set an event source object to 'floating' mode if the caller passed `NULL` in the parameter used to return a reference to the event source object. Nevertheless, it may be necessary to gain temporary access to the source object, for example to adjust event source properties after allocation (e.g. its priority or description string). In those cases the object may be created in non-floating mode, and the returned reference used to adjust the properties, and the object marked as floating afterwards, and the reference in the caller dropped. `sd_event_source_get_floating()` may be used to query the current 'floating' state of the event source object `source`. It returns zero if 'floating' mode is off, positive if it is on. # Return Value On success, `sd_event_source_set_floating()` and `sd_event_source_get_floating()` return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `source` is not a valid pointer to an sd_event_source object. `-ECHILD` The event loop has been created in a different process, library or module instance. # History `sd_event_source_set_floating()` and `sd_event_source_get_floating()` were added in version 244. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_description(3)`, `sd_event_source_set_priority(3)` # sd_event_source_set_prepare systemd sd_event_source_set_prepare 3 sd_event_source_set_prepare Set a preparation callback for event sources \#include \ int sd_event_source_set_prepare sd_event_source \* source sd_event_handler_t callback typedef int (\* sd_event_handler_t ) sd_event_source \* s void \* userdata # Description `sd_event_source_set_prepare()` may be used to set a preparation callback for the event source object specified as `source`. The callback function specified as `callback` will be invoked immediately before the event loop goes to sleep to wait for incoming events. It is invoked with the user data pointer passed when the event source was created. The event source will be disabled if the callback function returns a negative error code. The callback function may be used to reconfigure the precise events to wait for. If the `callback` parameter is passed as `NULL` the callback function is reset. Event source objects have no preparation callback associated when they are first created with calls such as `sd_event_add_io(3)`, `sd_event_add_time(3)`. Preparation callback functions are supported for all event source types with the exception of those created with `sd_event_add_exit(3)`. Preparation callback functions are dispatched in the order indicated by the event source's priority field, as set with `sd_event_source_set_priority(3)`. Preparation callbacks of disabled event sources (see `sd_event_source_set_enabled(3)`) are not invoked. # Return Value On success, `sd_event_source_set_prepare()` returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `source` is not a valid pointer to an sd_event_source object. `-ESTALE` The event loop is already terminated. `-ENOMEM` Not enough memory. `-ECHILD` The event loop has been created in a different process, library or module instance. `-EDOM` The specified event source has been created with `sd_event_add_exit(3)`. # History `sd_event_source_set_prepare()` and `sd_event_handler_t()` were added in version 229. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_enabled(3)`, `sd_event_source_set_priority(3)`, `sd_event_source_set_userdata(3)` # sd_event_source_set_priority systemd sd_event_source_set_priority 3 sd_event_source_set_priority sd_event_source_get_priority SD_EVENT_PRIORITY_IMPORTANT SD_EVENT_PRIORITY_NORMAL SD_EVENT_PRIORITY_IDLE Set or retrieve the priority of event sources \#include \ enum { SD_EVENT_PRIORITY_IMPORTANT = -100, SD_EVENT_PRIORITY_NORMAL = 0, SD_EVENT_PRIORITY_IDLE = 100, }; int sd_event_source_set_priority sd_event_source \* source int64_t priority int sd_event_source_get_priority sd_event_source \* source int64_t \* priority # Description `sd_event_source_set_priority()` may be used to set the priority for the event source object specified as `source`. The priority is specified as an arbitrary signed 64-bit integer. The priority is initialized to `SD_EVENT_PRIORITY_NORMAL` (0) when the event source is allocated with a call such as `sd_event_add_io(3)` or `sd_event_add_time(3)`, and may be changed with this call. If multiple event sources have seen events at the same time, they are dispatched in the order indicated by the event sources' priorities. Event sources with smaller priority values are dispatched first. As well-known points of reference, the constants `SD_EVENT_PRIORITY_IMPORTANT` (-100), `SD_EVENT_PRIORITY_NORMAL` (0) and `SD_EVENT_PRIORITY_IDLE` (100) may be used to indicate event sources that shall be dispatched early, normally or late. It is recommended to specify priorities based on these definitions, and relative to them — however, the full 64-bit signed integer range is available for ordering event sources. Priorities define the order in which event sources that have seen events are dispatched. Care should be taken to ensure that high-priority event sources (those with negative priority values assigned) do not cause starvation of low-priority event sources (those with positive priority values assigned). The order in which event sources with the same priority are dispatched is undefined, but the event loop generally tries to dispatch them in the order it learnt about events on them. As the backing kernel primitives do not provide accurate information about the order in which events occurred this is not necessarily reliable. However, it is guaranteed that if events are seen on multiple same-priority event sources at the same time, each one is not dispatched again until all others have been dispatched once. This behavior guarantees that within each priority particular event sources do not starve or dominate the event loop. The priority of event sources may be changed at any time of their lifetime, with the exception of inotify event sources (i.e. those created with `sd_event_add_inotify(3)`) whose priority may only be changed in the time between their initial creation and the first subsequent event loop iteration. `sd_event_source_get_priority()` may be used to query the current priority assigned to the event source object `source`. # Return Value On success, `sd_event_source_set_priority()` and `sd_event_source_get_priority()` return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` `source` is not a valid pointer to an sd_event_source object. `-ENOMEM` Not enough memory. `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. # History `sd_event_source_set_priority()` and `sd_event_source_get_priority()` were added in version 229. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)` # sd_event_source_set_ratelimit systemd sd_event_source_set_ratelimit 3 sd_event_source_set_ratelimit sd_event_source_get_ratelimit sd_event_source_is_ratelimited sd_event_source_set_ratelimit_expire_callback sd_event_source_leave_ratelimit Configure rate limiting on event sources \#include \ int sd_event_source_set_ratelimit sd_event_source \* source uint64_t interval_usec unsigned burst int sd_event_source_get_ratelimit sd_event_source \* source uint64_t\* ret_interval_usec unsigned\* ret_burst int sd_event_source_is_ratelimited sd_event_source \* source int sd_event_source_set_ratelimit_expire_callback sd_event_source \* source sd_event_handler_t callback int sd_event_source_leave_ratelimit sd_event_source \* source # Description `sd_event_source_set_ratelimit()` may be used to enforce rate limiting on an event source. When used an event source will be temporarily turned off when it fires more often then a specified burst number within a specified time interval. This is useful as simple mechanism to avoid event source starvation if high priority event sources fire very frequently. Pass the event source to operate on as first argument, a time interval in microseconds as second argument and a maximum dispatch limit ("burst") as third parameter. Whenever the event source is dispatched more often than the specified burst within the specified interval it is placed in a mode similar to being disabled with `sd_event_source_set_enabled(3)` and the `SD_EVENT_OFF` parameter. However, it is disabled only temporarily – once the specified interval is over regular operation resumes. It is again disabled temporarily once the specified rate limiting is hit the next time. If either the interval or the burst value are specified as zero, rate limiting is turned off. By default, event sources do not have rate limiting enabled. Note that rate limiting and disabling via `sd_event_source_set_enabled()` are independent of each other, and an event source will only effect event loop wake-ups and is dispatched while it both is enabled and rate limiting is not in effect. `sd_event_source_get_ratelimit()` may be used to query the current rate limiting parameters set on the event source object `source`. The previously set interval and burst vales are returned in the second and third argument. `sd_event_source_is_ratelimited()` may be used to query whether the event source is currently affected by rate limiting, i.e. it has recently hit the rate limit and is currently temporarily disabled due to that. `sd_event_source_set_ratelimit_expire_callback()` may be used to set a callback function that is invoked every time the event source leaves rate limited state. Note that function is called in the same event loop iteration in which state transition occurred. `sd_event_source_leave_ratelimit()` may be used to immediately reenable an event source that was temporarily disabled due to rate limiting. This will reset the ratelimit counters for the current time interval. Rate limiting is currently implemented for I/O, timer, signal, defer and inotify event sources. # Return Value On success, `sd_event_source_set_ratelimit()`, `sd_event_source_set_ratelimit_expire_callback` and `sd_event_source_get_ratelimit()` return a non-negative integer. On failure, they return a negative errno-style error code. `sd_event_source_is_ratelimited()` returns zero if rate limiting is currently not in effect and greater than zero if it is in effect; it returns a negative errno-style error code on failure. `sd_event_source_leave_ratelimit()` returns zero if rate limiting was not in effect on the specified event source, and positive if it was and rate limiting is now turned off again; it returns a negative errno-style error code on failure. ## Errors Returned errors may indicate the following problems: `-EINVAL` `source` is not a valid pointer to an sd_event_source object. `-ECHILD` The event loop has been created in a different process, library or module instance. `-EDOM` It was attempted to use the rate limiting feature on an event source type that does not support rate limiting. `-ENOEXEC` `sd_event_source_get_ratelimit()` was called on an event source that does not have rate limiting configured. # History `sd_event_source_set_ratelimit()`, `sd_event_source_get_ratelimit()`, and `sd_event_source_is_ratelimited()` were added in version 248. `sd_event_source_set_ratelimit_expire_callback()` was added in version 250. `sd_event_source_leave_ratelimit()` was added in version 254. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_enabled(3)` # sd_event_source_set_userdata systemd sd_event_source_set_userdata 3 sd_event_source_set_userdata sd_event_source_get_userdata Set or retrieve user data pointer of event sources \#include \ void\* sd_event_source_set_userdata sd_event_source \* source void \* userdata void\* sd_event_source_get_userdata sd_event_source \* source # Description `sd_event_source_set_userdata()` may be used to set an arbitrary user data pointer for the event source object specified as `source`. The user data pointer is usually specified when creating an event source object with calls such as `sd_event_add_io(3)` or `sd_event_add_time(3)`, and may be updated with this call. The user data pointer is also passed to all handler callback functions associated with the event source. The `userdata` parameter specifies the new user data pointer to set, the function returns the previous user data pointer. Note that `NULL` is a valid user data pointer. `sd_event_source_get_userdata()` may be used to query the current user data pointer assigned to the event source object `source`. # Return Value On success, `sd_event_source_set_userdata()` and `sd_event_source_get_userdata()` return the previously set user data pointer. On failure, they return `NULL`. # History `sd_event_source_set_userdata()` and `sd_event_source_get_userdata()` were added in version 229. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_description(3)` # sd_event_source_unref systemd sd_event_source_unref 3 sd_event_source_unref sd_event_source_unrefp sd_event_source_ref sd_event_source_disable_unref sd_event_source_disable_unrefp Increase or decrease event source reference counters \#include \ sd_event_source\* sd_event_source_unref sd_event_source \* source void sd_event_source_unrefp sd_event_source \*\* source sd_event_source\* sd_event_source_ref sd_event_source \* source sd_event_source\* sd_event_source_disable_unref sd_event_source \* source void sd_event_source_disable_unrefp sd_event_source \*\* source # Description `sd_event_source_unref()` may be used to decrement by one the internal reference counter of the event source object specified as `source`. The reference counter is initially set to one, when the event source is created with calls such as `sd_event_add_io(3)` or `sd_event_add_time(3)`. When the reference counter reaches zero, the object is detached from the event loop object and destroyed. `sd_event_source_unrefp()` is similar to `sd_event_source_unref()` but takes a pointer to a pointer to an `sd_event_source` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). Note that this function is defined as inline function. `sd_event_source_ref()` may be used to increase by one the internal reference counter of the event source object specified as `source`. `sd_event_source_ref()` and `sd_event_source_unref()` execute no operation if the passed event source object is `NULL`. `sd_event_source_unrefp()` will first dereference its argument, which must not be `NULL`, and will execute no operation if *that* is `NULL`. Note that event source objects stay alive and may be dispatched as long as they have a reference counter greater than zero. In order to drop a reference of an event source and make sure the associated event source handler function is not called anymore it is recommended to combine a call of `sd_event_source_unref()` with a prior call to `sd_event_source_set_enabled()` with `SD_EVENT_OFF` or call `sd_event_source_disable_unref()`, see below. `sd_event_source_disable_unref()` combines a call to `sd_event_source_set_enabled()` with `SD_EVENT_OFF` with `sd_event_source_unref()`. This ensures that the source is disabled before the local reference to it is lost. The `source` parameter is allowed to be `NULL`. `sd_event_source_disable_unrefp()` is similar to `sd_event_source_unrefp()`, but in addition disables the source first. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). Note that this function is defined as inline function. # Return Value `sd_event_source_unref()` and `sd_event_source_disable_unref()` always return `NULL`. `sd_event_source_ref()` always returns the event source object passed in. # History `sd_event_source_unref()`, `sd_event_source_unrefp()`, and `sd_event_source_ref()` were added in version 229. `sd_event_source_disable_unref()` and `sd_event_source_disable_unrefp()` were added in version 243. # See Also `sd-event(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_source_set_enabled(3)` # sd_event_wait systemd sd_event_wait 3 sd_event_wait sd_event_prepare sd_event_dispatch sd_event_get_state sd_event_get_iteration SD_EVENT_INITIAL SD_EVENT_PREPARING SD_EVENT_ARMED SD_EVENT_PENDING SD_EVENT_RUNNING SD_EVENT_EXITING SD_EVENT_FINISHED Low-level event loop operations \#include \ enum { SD_EVENT_INITIAL , SD_EVENT_PREPARING , SD_EVENT_ARMED , SD_EVENT_PENDING , SD_EVENT_RUNNING , SD_EVENT_EXITING , SD_EVENT_FINISHED , }; int sd_event_prepare sd_event \* event int sd_event_wait sd_event \* event uint64_t usec int sd_event_dispatch sd_event \* event int sd_event_get_state sd_event \* event int sd_event_get_iteration sd_event \* event uint64_t \* ret # Description The low-level `sd_event_prepare()`, `sd_event_wait()` and `sd_event_dispatch()` functions may be used to execute specific phases of an event loop. See `sd_event_run(3)` and `sd_event_loop(3)` for higher-level functions that execute individual but complete iterations of an event loop or run it continuously. `sd_event_prepare()` checks for pending events and arms necessary timers. If any events are ready to be processed ("pending"), it returns a positive, non-zero value, and the caller should process these events with `sd_event_dispatch()`. `sd_event_dispatch()` dispatches the highest priority event source that has a pending event. On success, `sd_event_dispatch()` returns either zero, which indicates that no further event sources may be dispatched and exiting of the event loop was requested via `sd_event_exit(3)`; or a positive non-zero value, which means that an event source was dispatched and the loop returned to its initial state, and the caller should initiate the next event loop iteration by invoking `sd_event_prepare()` again. In case `sd_event_prepare()` returned zero, `sd_event_wait()` should be called to wait for further events or a timeout. If any events are ready to be processed, it returns a positive, non-zero value, and the events should be dispatched with `sd_event_dispatch()`. Otherwise, the event loop returned to its initial state and the next event loop iteration should be initiated by invoking `sd_event_prepare()` again. `sd_event_get_state()` may be used to determine the state the event loop is currently in. It returns one of the states described below. `sd_event_get_iteration()` may be used to determine the current iteration of the event loop. It returns an unsigned 64-bit integer containing a counter that increases monotonically with each iteration of the event loop, starting with 0. The counter is increased at the time of the `sd_event_prepare()` invocation. All five functions take, as the first argument, the event loop object `event` that has been created with `sd_event_new()`. The timeout for `sd_event_wait()` is specified in `usec` in microseconds. `(uint64_t) -1` may be used to specify an infinite timeout. # State Machine The event loop knows the following states, that may be queried with `sd_event_get_state()`. `SD_EVENT_INITIAL` The initial state the event loop is in, before each event loop iteration. Use `sd_event_prepare()` to transition the event loop into the `SD_EVENT_ARMED` or `SD_EVENT_PENDING` states. `SD_EVENT_PREPARING` An event source is currently being prepared, i.e. the preparation handler is currently being executed, as set with `sd_event_source_set_prepare(3)`. This state is only seen in the event source preparation handler that is invoked from the `sd_event_prepare()` call and is immediately followed by `SD_EVENT_ARMED` or `SD_EVENT_PENDING`. `SD_EVENT_ARMED` `sd_event_prepare()` has been called and no event sources were ready to be dispatched. Use `sd_event_wait()` to wait for new events, and transition into `SD_EVENT_PENDING` or back into `SD_EVENT_INITIAL`. `SD_EVENT_PENDING` `sd_event_prepare()` or `sd_event_wait()` have been called and there were event sources with events pending. Use `sd_event_dispatch()` to dispatch the highest priority event source and transition back to `SD_EVENT_INITIAL`, or `SD_EVENT_FINISHED`. `SD_EVENT_RUNNING` A regular event source is currently being dispatched. This state is only seen in the event source handler that is invoked from the `sd_event_dispatch()` call, and is immediately followed by `SD_EVENT_INITIAL` or `SD_EVENT_FINISHED` as soon the event source handler returns. Note that during dispatching of exit event sources the `SD_EVENT_EXITING` state is seen instead. `SD_EVENT_EXITING` Similar to `SD_EVENT_RUNNING` but is the state in effect while dispatching exit event sources. It is followed by `SD_EVENT_INITIAL` or `SD_EVENT_FINISHED` as soon as the event handler returns. `SD_EVENT_FINISHED` The event loop has exited. All exit event sources have run. If the event loop is in this state it serves no purpose anymore, and should be freed. A simplified flow chart of the states and the calls to transition between them is shown below. Note that `SD_EVENT_PREPARING`, `SD_EVENT_RUNNING` and `SD_EVENT_EXITING` are not shown here. INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\ | | | ^ | | v ret == 0 | sd_event_prepare() >--->--->--->--->- ARMED | | | ^ | ret > 0 | | | | | v v ret == 0 | PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+ | ret > 0 ^ | | | | v | sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/ | ret > 0 | ret == 0 | v FINISHED # Return Value On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. In case of `sd_event_prepare()` and `sd_event_wait()`, a positive, non-zero return code indicates that events are ready to be processed and zero indicates that no events are ready. In case of `sd_event_dispatch()`, a positive, non-zero return code indicates that the event loop returned to its initial state and zero indicates the event loop has exited. `sd_event_get_state()` returns a positive or zero state on success. ## Errors Returned errors may indicate the following problems: `-EINVAL` The `event` parameter is invalid or `NULL`. `-EBUSY` The event loop object is not in the right state. `-ESTALE` The event loop is already terminated. `-ECHILD` The event loop has been created in a different process, library or module instance. Other errors are possible, too. # History `sd_event_prepare()`, `sd_event_wait()`, `sd_event_dispatch()`, and `sd_event_get_state()` were added in version 221. `sd_event_get_iteration()` was added in version 231. # See Also `systemd(1)`, `sd_event_new(3)`, `sd_event_add_io(3)`, `sd_event_add_time(3)`, `sd_event_add_signal(3)`, `sd_event_add_child(3)`, `sd_event_add_inotify(3)`, `sd_event_add_defer(3)`, `sd_event_run(3)`, `sd_event_get_fd(3)`, `sd_event_source_set_prepare(3)` # sd_get_seats systemd sd_get_seats 3 sd_get_seats sd_get_sessions sd_get_uids sd_get_machine_names Determine available seats, sessions, logged in users and virtual machines/containers \#include \ int sd_get_seats char \*\*\* seats int sd_get_sessions char \*\*\* sessions int sd_get_uids uid_t \*\* users int sd_get_machine_names char \*\*\* machines # Description `sd_get_seats()` may be used to determine all currently available local seats. Returns the number of seat identifiers and if the input pointer is non-`NULL`, a `NULL`-terminated array of seat identifiers is stored at the address. The returned array and all strings it references need to be freed with the libc `free(3)` call after use. Note that instead of an empty array `NULL` may be returned and should be considered equivalent to an empty array. Similarly, `sd_get_sessions()` may be used to determine all current login sessions. Similarly, `sd_get_uids()` may be used to determine all Unix users who currently have login sessions. Similarly, `sd_get_machine_names()` may be used to determine all current virtual machines and containers on the system. Note that the returned lists are not sorted and in an undefined order. # Return Value On success, `sd_get_seats()`, `sd_get_sessions()`, `sd_get_uids()` and `sd_get_machine_names()` return the number of entries in the arrays. On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENOMEM` Memory allocation failed. # History `sd_get_machine_names()` was added in version 203. # See Also `systemd(1)`, `sd-login(3)`, `sd_session_get_seat(3)` # sd_hwdb_get systemd sd_hwdb_get 3 sd_hwdb_get sd_hwdb_seek sd_hwdb_enumerate SD_HWDB_FOREACH_PROPERTY Seek to a location in hwdb or access entries \#include \ int sd_hwdb_get sd_hwdb \* hwdb const char \* modalias const char \* key const char \*\* value int sd_hwdb_seek sd_hwdb \* hwdb const char \* modalias int sd_hwdb_enumerate sd_hwdb \* hwdb const char \*\* key const char \*\* value SD_HWDB_FOREACH_PROPERTY hwdb modalias key value # Description `sd_hwdb_get()` queries the `hwdb` object created earlier with `sd_hwdb_new(3)` for entries matching the specified string `modalias`, and returns the value corresponding to the key `key`. The value is returned as a `NUL`-terminated string in `value`. It must not be modified by the caller and is valid as long as a reference to `hwdb` is kept. When multiple patterns in the database match `modalias`, the one with the highest priority is used. See `hwdb(7)` for details. `sd_hwdb_seek()` selects entries matching the specified string `modalias`. Subsequent queries with `sd_hwdb_enumerate()` will access the key-value pairs for that string. `sd_hwdb_enumerate()` returns (in turn) all the key-value pairs defined for the string used with `sd_hwdb_seek()`. Each pair is returned as `NUL`-terminated strings in `key` and `value`. The strings must not be modified by the caller and are valid as long as a reference to `hwdb` is kept. When multiple patterns in the database match `modalias`, the combination of all matching key-value pairs is used. See `hwdb(7)` for details. The `SD_HWDB_FOREACH_PROPERTY()` macro combines `sd_hwdb_seek()` and `sd_hwdb_enumerate()`. No error handling is performed and iteration simply stops on error. See the example below. # Return Value On success, `sd_hwdb_get()` and `sd_hwdb_seek()` return a non-negative integer. On failure, they return a negative errno-style error code. `sd_hwdb_enumerate()` returns a positive integer if another key-value pair was found or zero if all entries have already been enumerated. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` A parameter is `NULL`. `-ENOENT` An entry for the specified `modalias` was not found. `-EAGAIN` `sd_hwdb_seek()` was not called before `sd_hwdb_enumerate()`. # Examples
Look up hwdb entries for a USB device
The effect is similar to calling `systemd-hwdb query usb:v046DpC534`.
# History `sd_hwdb_get()`, `sd_hwdb_seek()`, `sd_hwdb_enumerate()`, and `SD_HWDB_FOREACH_PROPERTY()` were added in version 246. # See Also `systemd(1)`, `systemd-udevd.service(8)`, `sd-hwdb(3)`, `systemd-hwdb(8)` # sd_hwdb_new systemd sd_hwdb_new 3 sd_hwdb_new sd_hwdb_new_from_path sd_hwdb_ref sd_hwdb_unref Create a new hwdb object and create or destroy references to it \#include \ int sd_hwdb_new sd_hwdb \*\* hwdb int sd_hwdb_new_from_path const char \* path sd_hwdb \*\* hwdb sd_hwdb\* sd_hwdb_ref sd_hwdb \* hwdb sd_hwdb\* sd_hwdb_unref sd_hwdb \* hwdb # Description `sd_hwdb_new()` creates a new hwdb object to access the binary hwdb database. Upon initialization, the file containing the binary representation of the hardware database is located and opened. The new object is returned in `hwdb`. `sd_hwdb_new_from_path()` may be used to specify the path from which the binary hardware database should be opened. The `hwdb` object is reference counted. `sd_hwdb_ref()` and `sd_hwdb_unref()` may be used to get a new reference or destroy an existing reference to an object. The caller must dispose of the reference acquired with `sd_hwdb_new()` by calling `sd_hwdb_unref()` when done with the object. Use `sd_hwdb_seek(3)`, `sd_hwdb_get(3)`, and `sd_hwdb_enumerate(3)` to access entries. # Return Value On success, `sd_hwdb_new()` and `sd_hwdb_new_from_path()` return a non-negative integer. On failure, a negative errno-style error code is returned. `sd_hwdb_ref()` always returns the argument. `sd_hwdb_unref()` always returns `NULL`. ## Errors Returned errors may indicate the following problems: `-ENOENT` The binary hardware database file could not be located. See `systemd-hwdb(8)` for more information. `-EINVAL` The located binary hardware database file is in an incompatible format. `-ENOMEM` Memory allocation failed. # History `sd_hwdb_new()`, `sd_hwdb_ref()`, and `sd_hwdb_unref()` were added in version 246. `sd_hwdb_new_from_path()` was added in version 252. # See Also `systemd(1)`, `systemd-udevd.service(8)`, `sd-hwdb(3)`, `systemd-hwdb(8)` # sd_id128_get_machine systemd sd_id128_get_machine 3 sd_id128_get_machine sd_id128_get_app_specific sd_id128_get_machine_app_specific sd_id128_get_boot sd_id128_get_boot_app_specific sd_id128_get_invocation Retrieve 128-bit IDs \#include \ int sd_id128_get_machine sd_id128_t \* ret int sd_id128_get_app_specific sd_id128_t base sd_id128_t app_id sd_id128_t \* ret int sd_id128_get_machine_app_specific sd_id128_t app_id sd_id128_t \* ret int sd_id128_get_boot sd_id128_t \* ret int sd_id128_get_boot_app_specific sd_id128_t app_id sd_id128_t \* ret int sd_id128_get_invocation sd_id128_t \* ret int sd_id128_get_invocation_app_specific sd_id128_t app_id sd_id128_t \* ret # Description `sd_id128_get_machine()` returns the machine ID of the executing host. This reads and parses the `machine-id(5)` file. This function caches the machine ID internally to make retrieving the machine ID a cheap operation. This ID may be used wherever a unique identifier for the local system is needed. However, it is recommended to use this ID as-is only in trusted environments. In untrusted environments it is recommended to derive an application specific ID from this machine ID, in an irreversible (cryptographically secure) way. To make this easy `sd_id128_get_machine_app_specific()` is provided, see below. `sd_id128_get_app_specific()` returns a machine ID that is a combination of the `base` and `app_id` parameters. Internally, this function calculates HMAC-SHA256 of the `app_id` parameter keyed by the `base` parameter, and truncates this result to fit in sd_id128_t and turns it into a valid Variant 1 Version 4 UUID, in accordance with [RFC 4122](https://tools.ietf.org/html/rfc4122). Neither of the two input parameters can be calculated from the output parameter `ret`. `sd_id128_get_machine_app_specific()` is similar to `sd_id128_get_machine()`, but retrieves a machine ID that is specific to the application that is identified by the indicated application ID. It is recommended to use this function instead of `sd_id128_get_machine()` when passing an ID to untrusted environments, in order to make sure that the original machine ID may not be determined externally. This way, the ID used by the application remains stable on a given machine, but cannot be easily correlated with IDs used in other applications on the same machine. The application-specific ID should be generated via a tool like `systemd-id128 new`, and may be compiled into the application. This function will return the same application-specific ID for each combination of machine ID and application ID. Internally, this function calls `sd_id128_get_app_specific()` with the result from `sd_id128_get_machine()` and the `app_id` parameter. `sd_id128_get_boot()` returns the boot ID of the executing kernel. This reads and parses the `/proc/sys/kernel/random/boot_id` file exposed by the kernel. It is randomly generated early at boot and is unique for every running kernel instance. See `random(4)` for more information. This function also internally caches the returned ID to make this call a cheap operation. It is recommended to use this ID as-is only in trusted environments. In untrusted environments it is recommended to derive an application specific ID using `sd_id128_get_boot_app_specific()`, see below. `sd_id128_get_boot_app_specific()` is analogous to `sd_id128_get_machine_app_specific()`, but returns an ID that changes between boots. Some machines may be used for a long time without rebooting, hence the boot ID may remain constant for a long time, and has properties similar to the machine ID during that time. `sd_id128_get_invocation()` returns the invocation ID of the currently executed service. In its current implementation, this tries to read and parse the following: - The `$INVOCATION_ID` environment variable that the service manager sets when activating a service. - An entry in the kernel keyring that the system service manager sets when activating a service. See `systemd.exec(5)` for details. The ID is cached internally. In future a different mechanism to determine the invocation ID may be added. `sd_id128_get_invocation_app_specific()` derives an application-specific ID from the invocation ID. Note that `sd_id128_get_machine_app_specific()`, `sd_id128_get_boot()`, `sd_id128_get_boot_app_specific()`, `sd_id128_get_invocation()` and `sd_id128_get_invocation_app_specific` always return UUID Variant 1 Version 4 compatible IDs. `sd_id128_get_machine()` will also return a UUID Variant 1 Version 4 compatible ID on new installations but might not on older. It is possible to convert the machine ID non-reversibly into a UUID Variant 1 Version 4 compatible one. For more information, see `machine-id(5)`. It is hence guaranteed that these functions will never return the ID consisting of all zero or all one bits (`SD_ID128_NULL`, `SD_ID128_ALLF`) — with the possible exception of `sd_id128_get_machine()`, as mentioned. For more information about the `sd_id128_t` type see `sd-id128(3)`. # Return Value Those calls return 0 on success (in which case `ret` is filled in), or a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENOENT` Returned by `sd_id128_get_machine()` and `sd_id128_get_machine_app_specific()` when `/etc/machine-id` is missing. `-ENOMEDIUM` Returned by `sd_id128_get_machine()` and `sd_id128_get_machine_app_specific()` when `/etc/machine-id` is empty or all zeros. Also returned by `sd_id128_get_invocation()` when the invocation ID is all zeros. `-ENOPKG` Returned by `sd_id128_get_machine()` and `sd_id128_get_machine_app_specific()` when the content of `/etc/machine-id` is `uninitialized`. `-ENOSYS` Returned by `sd_id128_get_boot()` and `sd_id128_get_boot_app_specific()` when `/proc/` is not mounted. `-ENXIO` Returned by `sd_id128_get_invocation()` if no invocation ID is set. Also returned by `sd_id128_get_app_specific()`, `sd_id128_get_machine_app_specific()`, and `sd_id128_get_boot_app_specific()` when the `app_id` parameter is all zeros. `-EUCLEAN` Returned by any of the functions described here when the configured value has invalid format. `-EPERM` Requested information could not be retrieved because of insufficient permissions. # Examples
Application-specific machine ID
First, generate the application ID: $ systemd-id128 -p new As string: c273277323db454ea63bb96e79b53e97 As UUID: c2732773-23db-454e-a63b-b96e79b53e97 As man:sd-id128(3) macro: #define MESSAGE_XYZ SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97) ... Then use the new identifier in an example application:
# History `sd_id128_get_machine()` and `sd_id128_get_boot()` were added in version 187. `sd_id128_get_invocation()` was added in version 232. `sd_id128_get_machine_app_specific()` was added in version 233. `sd_id128_get_boot_app_specific()` was added in version 240. `sd_id128_get_app_specific()` was added in version 255. `sd_id128_get_invocation_app_specific()` was added in version 256. # See Also `systemd(1)`, `systemd-id128(1)`, `sd-id128(3)`, `machine-id(5)`, `systemd.exec(5)`, `sd_id128_randomize(3)`, `random(4)` # sd_id128_randomize systemd sd_id128_randomize 3 sd_id128_randomize Generate 128-bit IDs \#include \ int sd_id128_randomize sd_id128_t \* ret # Description `sd_id128_randomize()` generates a new randomized 128-bit ID and returns it in `ret`. Every invocation returns a new randomly generated ID. This uses the `getrandom(2)` kernel random number generator. Note that `sd_id128_randomize()` always returns a UUID Variant 1 Version 4 compatible ID. It is hence guaranteed that this function will never return the ID consisting of all zero or all one bits (`SD_ID128_NULL`, `SD_ID128_ALLF`). For more information about the `sd_id128_t` type, see `sd-id128(3)`. `systemd-id128(1)`'s `new` command may be used as a command line front-end for `sd_id128_randomize()`. # Return Value The call returns 0 on success (in which case `ret` is filled in), or a negative errno-style error code. # History `sd_id128_randomize()` was added in version 187. # See Also `systemd(1)`, `sd-id128(3)`, `machine-id(5)`, `getrandom(2)`, `random(4)`, `sd_id128_get_machine(3)` # sd_id128_to_string systemd sd_id128_to_string 3 sd_id128_to_string SD_ID128_TO_STRING SD_ID128_STRING_MAX sd_id128_to_uuid_string SD_ID128_TO_UUID_STRING SD_ID128_UUID_STRING_MAX sd_id128_from_string Format or parse 128-bit IDs as strings \#include \ \#define SD_ID128_STRING_MAX 33U \#define SD_ID128_UUID_STRING_MAX 37U \#define SD_ID128_TO_STRING(id) … \#define SD_ID128_TO_UUID_STRING(id) … char \* sd_id128_to_string sd_id128_t id , char s \[static SD_ID128_STRING_MAX\] char \* sd_id128_to_uuid_string sd_id128_t id , char s \[static SD_ID128_UUID_STRING_MAX\] int sd_id128_from_string const char \* s , sd_id128_t \* ret # Description `sd_id128_to_string()` formats a 128-bit ID as a character string. It expects the ID and a string array capable of storing 33 characters (`SD_ID128_STRING_MAX`). The ID will be formatted as 32 lowercase hexadecimal digits and be terminated by a `NUL` byte. `SD_ID128_TO_STRING()` is a macro that wraps `sd_id128_to_string()` and passes an appropriately sized buffer as second argument, allocated as C99 compound literal. Each use will thus implicitly acquire a suitable buffer on the stack which remains valid until the end of the current code block. This is usually the simplest way to acquire a string representation of a 128-bit ID in a buffer that is valid in the current code block. `sd_id128_to_uuid_string()` and `SD_ID128_TO_UUID_STRING()` are similar to these two functions/macros, but format the 128-bit values as RFC4122 UUIDs, i.e. a series of 36 lowercase hexadecimal digits and dashes, terminated by a `NUL` byte. `sd_id128_from_string()` implements the reverse operation: it takes a 33 character string with 32 hexadecimal digits (either lowercase or uppercase, terminated by `NUL`) and parses them back into a 128-bit ID returned in `ret`. Alternatively, this call can also parse a 37-character string with a 128-bit ID formatted as RFC UUID, and a 46-character string consisting of the 9-character `urn:uuid:` prefix, a 36-character RFC UUID, and a terminating `NUL`. If `ret` is passed as `NULL` the function will validate the passed ID string, but not actually return it in parsed form. Note that when formatting and parsing 36 character UUIDs this is done strictly in Big Endian byte order, i.e. according to [RFC4122](https://tools.ietf.org/html/rfc4122) Variant 1 rules, even if the UUID encodes a different variant. This matches behaviour in various other Linux userspace tools. It's probably wise to avoid UUIDs of other variant types. For more information about the `sd_id128_t` type see `sd-id128(3)`. Note that these calls operate the same way on all architectures, i.e. the results do not depend on endianness. When formatting a 128-bit ID into a string, it is often easier to use a format string for `printf(3)`. This is easily done using the `SD_ID128_FORMAT_STR` and `SD_ID128_FORMAT_VAL()` macros. For more information see `sd-id128(3)`. # Return Value `sd_id128_to_string()` always succeeds and returns a pointer to the string array passed in. `sd_id128_from_string()` returns 0 on success, in which case `ret` is filled in, or a negative errno-style error code. # History `sd_id128_to_string()` and `sd_id128_from_string()` were added in version 187. `sd_id128_to_uuid_string()` was added in version 251. # See Also `systemd(1)`, `sd-id128(3)`, `printf(3)` # sd_is_fifo systemd sd_is_fifo 3 sd_is_fifo sd_is_socket sd_is_socket_inet sd_is_socket_unix sd_is_socket_sockaddr sd_is_mq sd_is_special Check the type of a file descriptor \#include \ int sd_is_fifo int fd const char \* path int sd_is_socket int fd int family int type int listening int sd_is_socket_inet int fd int family int type int listening uint16_t port int sd_is_socket_sockaddr int fd int type const struct sockaddr \* addr unsigned addr_len int listening int sd_is_socket_unix int fd int type int listening const char \* path size_t length int sd_is_mq int fd const char \* path int sd_is_special int fd const char \* path # Description `sd_is_fifo()` may be called to check whether the specified file descriptor refers to a FIFO or pipe. If the `path` parameter is not `NULL`, it is checked whether the FIFO is bound to the specified file system path. `sd_is_socket()` may be called to check whether the specified file descriptor refers to a socket. If the `family` parameter is not `AF_UNSPEC`, it is checked whether the socket is of the specified family (`AF_UNIX`, `AF_INET`, …). If the `type` parameter is not 0, it is checked whether the socket is of the specified type (`SOCK_STREAM`, `SOCK_DGRAM`, …). If the `listening` parameter is positive, it is checked whether the socket is in accepting mode, i.e. `listen()` has been called for it. If `listening` is 0, it is checked whether the socket is not in this mode. If the parameter is negative, no such check is made. The `listening` parameter should only be used for stream sockets and should be set to a negative value otherwise. `sd_is_socket_inet()` is similar to `sd_is_socket()`, but optionally checks the IPv4 or IPv6 port number the socket is bound to, unless `port` is zero. For this call `family` must be passed as either `AF_UNSPEC`, `AF_INET`, or `AF_INET6`. `sd_is_socket_sockaddr()` is similar to `sd_is_socket_inet()`, but checks if the socket is bound to the address specified by `addr`. The family specified by `addr` must be either `AF_INET` or `AF_INET6` and `addr_len` must be large enough for that family. If `addr` specifies a non-zero port, it is also checked if the socket is bound to this port. In addition, for IPv6, if `addr` specifies non-zero sin6_flowinfo or sin6_scope_id, it is checked if the socket has the same values. `sd_is_socket_unix()` is similar to `sd_is_socket()` but optionally checks the `AF_UNIX` path the socket is bound to, unless the `path` parameter is `NULL`. For normal file system `AF_UNIX` sockets, set the `length` parameter to 0. For Linux abstract namespace sockets, set the `length` to the size of the address, including the initial 0 byte, and set the `path` to the initial 0 byte of the socket address. `sd_is_mq()` may be called to check whether the specified file descriptor refers to a POSIX message queue. If the `path` parameter is not `NULL`, it is checked whether the message queue is bound to the specified name. `sd_is_special()` may be called to check whether the specified file descriptor refers to a special file. If the `path` parameter is not `NULL`, it is checked whether the file descriptor is bound to the specified filename. Special files in this context are character device nodes and files in `/proc/` or `/sys/`. # Return Value On failure, these calls return a negative errno-style error code. If the file descriptor is of the specified type and bound to the specified address, a positive return value is returned, otherwise zero. # Notes Internally, these functions use a combination of `fstat(2)` and `getsockname(2)` to check the file descriptor type and where it is bound to. # History `sd_is_special()` was added in version 209. `sd_is_socket_sockaddr()` was added in version 233. # See Also `systemd(1)`, `sd-daemon(3)`, `sd_listen_fds(3)`, `systemd.service(5)`, `systemd.socket(5)`, `ip(7)`, `ipv6(7)`, `unix(7)`, `fifo(7)`, `mq_overview(7)`, `socket(7)`. # sd_journal_add_match systemd sd_journal_add_match 3 sd_journal_add_match sd_journal_add_disjunction sd_journal_add_conjunction sd_journal_flush_matches Add or remove entry matches \#include \ int sd_journal_add_match sd_journal \* j const void \* data size_t size int sd_journal_add_disjunction sd_journal \* j int sd_journal_add_conjunction sd_journal \* j void sd_journal_flush_matches sd_journal \* j # Description `sd_journal_add_match()` adds a match by which to filter the entries of the journal file. Matches applied with this call will filter what can be iterated through and read from the journal file via calls like `sd_journal_next(3)` and `sd_journal_get_data(3)`. Parameter `data` must be of the form `FIELD=value`, where the \ part is a short uppercase string consisting only of 0–9, A–Z and the underscore; it may not begin with two underscores or be the empty string. The \ part may be anything, including binary. Parameter `size` specifies the number of bytes in `data` (i.e. the length of \, plus one, plus the length of \). Parameter `size` may also be specified as `0`, in which case `data` must be a `NUL`-terminated string, and the bytes before the terminating zero are used as the match. If a match is applied, only entries with this field set will be iterated. Multiple matches may be active at the same time: If they apply to different fields, only entries with both fields set like this will be iterated. If they apply to the same fields, only entries where the field takes one of the specified values will be iterated. Well known fields are documented in `systemd.journal-fields(7)`. Whenever a new match is added the current entry position is reset, and `sd_journal_next(3)` (or a similar call) needs to be called before entries can be read again. `sd_journal_add_disjunction()` may be used to insert a disjunction (i.e. logical OR) in the match list. If this call is invoked, all previously added matches since the last invocation of `sd_journal_add_disjunction()` or `sd_journal_add_conjunction()` are combined in an OR with all matches added afterwards, until `sd_journal_add_disjunction()` or `sd_journal_add_conjunction()` is invoked again to begin the next OR or AND term. `sd_journal_add_conjunction()` may be used to insert a conjunction (i.e. logical AND) in the match list. If this call is invoked, all previously added matches since the last invocation of `sd_journal_add_conjunction()` are combined in an AND with all matches added afterwards, until `sd_journal_add_conjunction()` is invoked again to begin the next AND term. The combination of `sd_journal_add_match()`, `sd_journal_add_disjunction()` and `sd_journal_add_conjunction()` may be used to build complex search terms, even though full logical expressions are not available. Note that `sd_journal_add_conjunction()` operates one level 'higher' than `sd_journal_add_disjunction()`. It is hence possible to build an expression of AND terms, consisting of OR terms, consisting of AND terms, consisting of OR terms of matches (the latter OR expression is implicitly created for matches with the same field name, see above). `sd_journal_flush_matches()` may be used to flush all matches, disjunction and conjunction terms again. After this call all filtering is removed and all entries in the journal will be iterated again. Note that filtering via matches only applies to the way the journal is read, it has no effect on storage on disk. # Return Value `sd_journal_add_match()`, `sd_journal_add_disjunction()` and `sd_journal_add_conjunction()` return 0 on success or a negative errno-style error code. `sd_journal_flush_matches()` returns nothing. # Examples The following example adds matches to a journal context object to iterate only through messages generated by the Avahi service at the four error log levels, plus all messages of the message ID 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any service (this example lacks the necessary error checking): … int add_matches(sd_journal *j) { sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0); sd_journal_add_match(j, "PRIORITY=0", 0); sd_journal_add_match(j, "PRIORITY=1", 0); sd_journal_add_match(j, "PRIORITY=2", 0); sd_journal_add_match(j, "PRIORITY=3", 0); sd_journal_add_disjunction(j); sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0); } # History `sd_journal_add_match()`, `sd_journal_add_disjunction()`, and `sd_journal_flush_matches()` were added in version 187. `sd_journal_add_conjunction()` was added in version 202. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_next(3)`, `sd_journal_get_data(3)`, `systemd.journal-fields(7)` # sd_journal_enumerate_fields systemd sd_journal_enumerate_fields 3 sd_journal_enumerate_fields sd_journal_restart_fields SD_JOURNAL_FOREACH_FIELD Read used field names from the journal \#include \ int sd_journal_enumerate_fields sd_journal \* j const char \*\* field void sd_journal_restart_fields sd_journal \* j SD_JOURNAL_FOREACH_FIELD sd_journal \* j const char \* field # Description `sd_journal_enumerate_fields()` may be used to iterate through all field names used in the opened journal files. On each invocation the next field name is returned. The order of the returned field names is not defined. It takes two arguments: the journal context object, plus a pointer to a constant string pointer where the field name is stored in. The returned data is in a read-only memory map and is only valid until the next invocation of `sd_journal_enumerate_fields()`. Note that this call is subject to the data field size threshold as controlled by `sd_journal_set_data_threshold()`. `sd_journal_restart_fields()` resets the field name enumeration index to the beginning of the list. The next invocation of `sd_journal_enumerate_fields()` will return the first field name again. The `SD_JOURNAL_FOREACH_FIELD()` macro may be used as a handy wrapper around `sd_journal_restart_fields()` and `sd_journal_enumerate_fields()`. These functions currently are not influenced by matches set with `sd_journal_add_match()` but this might change in a later version of this software. To retrieve the possible values a specific field can take use `sd_journal_query_unique(3)`. # Return Value `sd_journal_enumerate_fields()` returns a positive integer if the next field name has been read, 0 when no more field names are known, or a negative errno-style error code. `sd_journal_restart_fields()` returns nothing. # Notes # Examples Use the `SD_JOURNAL_FOREACH_FIELD()` macro to iterate through all field names in use in the current journal. # History `sd_journal_enumerate_fields()`, `sd_journal_restart_fields()`, and `SD_JOURNAL_FOREACH_FIELD()` were added in version 229. # See Also `systemd(1)`, `systemd.journal-fields(7)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_query_unique(3)`, `sd_journal_get_data(3)`, `sd_journal_add_match(3)` # sd_journal_get_catalog systemd sd_journal_get_catalog 3 sd_journal_get_catalog sd_journal_get_catalog_for_message_id Retrieve message catalog entry \#include \ int sd_journal_get_catalog sd_journal \* j char \*\* ret int sd_journal_get_catalog_for_message_id sd_id128_t id char \*\* ret # Description `sd_journal_get_catalog()` retrieves a message catalog entry for the current journal entry. This will look up an entry in the message catalog by using the `MESSAGE_ID=` field of the current journal entry. Before returning the entry all journal field names in the catalog entry text enclosed in "@" will be replaced by the respective field values of the current entry. If a field name referenced in the message catalog entry does not exist, in the current journal entry, the "@" will be removed, but the field name otherwise left untouched. `sd_journal_get_catalog_for_message_id()` works similar to `sd_journal_get_catalog()` but the entry is looked up by the specified message ID (no open journal context is necessary for this), and no field substitution is performed. For more information about the journal message catalog please refer to the [Journal Message Catalogs](https://systemd.io/CATALOG) documentation page. # Return Value `sd_journal_get_catalog()` and `sd_journal_get_catalog_for_message_id()` return 0 on success or a negative errno-style error code. If no matching message catalog entry is found, -ENOENT is returned. On successful return, `ret` points to a new string, which must be freed with `free(3)`. # Notes Function `sd_journal_get_catalog()` is thread-agnostic and only a single thread may operate on a given object at any given time. Multiple independent objects may be used from different threads in parallel. Function `sd_journal_get_catalog_for_message_id()` is thread-safe and may be called from multiple threads in parallel. # History `sd_journal_get_catalog()` and `sd_journal_get_catalog_for_message_id()` were added in version 196. # See Also `systemd(1)`, `systemd.journal-fields(7)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_next(3)`, `sd_journal_get_data(3)`, `malloc(3)` # sd_journal_get_cursor systemd sd_journal_get_cursor 3 sd_journal_get_cursor sd_journal_test_cursor Get cursor string for or test cursor string against the current journal entry \#include \ int sd_journal_get_cursor sd_journal \* j char \*\* ret_cursor int sd_journal_test_cursor sd_journal \* j const char \* cursor # Description `sd_journal_get_cursor()` returns a cursor string for the current journal entry. A cursor is a serialization of the current journal position formatted as text. The string only contains printable characters and can be passed around in text form. The cursor identifies a journal entry globally and in a stable way and may be used to later seek to it via `sd_journal_seek_cursor(3)`. The cursor string should be considered opaque and not be parsed by clients. Seeking to a cursor position without the specific entry being available locally will seek to the next closest (in terms of time) available entry. The call takes two arguments: a journal context object and a pointer to a string pointer where the cursor string will be placed. The string is allocated via libc `malloc(3)` and should be freed after use with `free(3)`. The `ret_cursor` parameter may be passed as `NULL` in which case the cursor string is not generated, however the return value will indicate whether the journal context is currently positioned on an entry, and thus has a cursor associated. `sd_journal_test_cursor()` may be used to check whether the current position in the journal matches the specified cursor. This is useful since cursor strings do not uniquely identify an entry: the same entry might be referred to by multiple different cursor strings, and hence string comparing cursors is not possible. Use this call to verify after an invocation of `sd_journal_seek_cursor(3)`, whether the entry being sought to was actually found in the journal or the next closest entry was used instead. Note that `sd_journal_get_cursor()` and `sd_journal_test_cursor()` will not work before `sd_journal_next(3)` (or one of the other functions which move to an entry) has been called at least once to position the read pointer at a valid entry. # Return Value `sd_journal_get_cursor()` returns 0 on success or a negative errno-style error code. `sd_journal_test_cursor()` returns positive if the current entry matches the specified cursor, 0 if it does not match the specified cursor or a negative errno-style error code on failure. ## Errors Returned errors may indicate the following problems: `-EADDRNOTAVAIL` The journal context is currently not positioned on any entry, and hence no cursor string can be generated. `-EINVAL` The journal context parameter is `NULL`. `-ECHILD` The journal context object has been allocated in a different process than it is being used in now. # Notes # History `sd_journal_get_cursor()` was added in version 187. `sd_journal_test_cursor()` was added in version 195. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_seek_cursor(3)` # sd_journal_get_cutoff_realtime_usec systemd sd_journal_get_cutoff_realtime_usec 3 sd_journal_get_cutoff_realtime_usec sd_journal_get_cutoff_monotonic_usec Read cut-off timestamps from the current journal entry \#include \ int sd_journal_get_cutoff_realtime_usec sd_journal \* j uint64_t \* from uint64_t \* to int sd_journal_get_cutoff_monotonic_usec sd_journal \* j sd_id128_t boot_id uint64_t \* from uint64_t \* to # Description `sd_journal_get_cutoff_realtime_usec()` retrieves the realtime (wallclock) timestamps of the first and last entries accessible in the journal. It takes three arguments: the journal context object `j` and two pointers `from` and `to` pointing at 64-bit unsigned integers to store the timestamps in. The timestamps are in microseconds since the epoch, i.e. `CLOCK_REALTIME`. Either one of the two timestamp arguments may be passed as `NULL` in case the timestamp is not needed, but not both. `sd_journal_get_cutoff_monotonic_usec()` retrieves the monotonic timestamps of the first and last entries accessible in the journal. It takes three arguments: the journal context object `j`, a 128-bit identifier for the boot `boot_id`, and two pointers to 64-bit unsigned integers to store the timestamps, `from` and `to`. The timestamps are in microseconds since boot-up of the specific boot, i.e. `CLOCK_MONOTONIC`. Since the monotonic clock begins new with every reboot it only defines a well-defined point in time when used together with an identifier identifying the boot, see `sd_id128_get_boot(3)` for more information. The function will return the timestamps for the boot identified by the passed boot ID. Either one of the two timestamp arguments may be passed as `NULL` in case the timestamp is not needed, but not both. # Return Value `sd_journal_get_cutoff_realtime_usec()` and `sd_journal_get_cutoff_monotonic_usec()` return 1 on success, 0 if not suitable entries are in the journal or a negative errno-style error code. Locations pointed to by parameters `from` and `to` will be set only if the return value is positive, and obviously, the parameters are non-null. # Notes # History `sd_journal_get_cutoff_realtime_usec()` and `sd_journal_get_cutoff_monotonic_usec()` were added in version 187. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_get_realtime_usec(3)`, `sd_id128_get_boot(3)`, `clock_gettime(2)` # sd_journal_get_data systemd sd_journal_get_data 3 sd_journal_get_data sd_journal_get_data_to_fd sd_journal_enumerate_data sd_journal_enumerate_available_data sd_journal_restart_data SD_JOURNAL_FOREACH_DATA sd_journal_set_data_threshold sd_journal_get_data_threshold SD_JOURNAL_DATA_SKIP_FIELD Read data fields from the current journal entry \#include \ int sd_journal_get_data sd_journal \* j const char \* field const void \*\* data size_t \* length int sd_journal_get_data_to_fd sd_journal \* j const char \* field sd_journal_data_flags_t flags int fd size_t \* ret_size int sd_journal_enumerate_data sd_journal \* j const void \*\* data size_t \* length int sd_journal_enumerate_available_data sd_journal \* j const void \*\* data size_t \* length void sd_journal_restart_data sd_journal \* j SD_JOURNAL_FOREACH_DATA sd_journal \* j const void \* data size_t length int sd_journal_set_data_threshold sd_journal \* j size_t sz int sd_journal_get_data_threshold sd_journal \* j size_t \* sz # Description `sd_journal_get_data()` gets the data object associated with a specific field from the current journal entry. It takes four arguments: the journal context object, a string with the field name to request, plus a pair of optional pointers to pointer/size variables where the data object and its size shall be stored in. Either pointer may be `NULL`, in which case the corresponding value is not returned (this is supported since version 261). The field name should be an entry field name. Well-known field names are listed in `systemd.journal-fields(7)`, but any field can be specified. The returned data is in a read-only memory map and is only valid until the next invocation of `sd_journal_get_data()`, `sd_journal_enumerate_data()`, `sd_journal_enumerate_available_data()`, or when the read pointer is altered. Note that the data returned will be prefixed with the field name and `=`. `sd_journal_get_data_to_fd()` is similar to `sd_journal_get_data()`, but writes the result data to the file descriptor specified by the `fd` argument. If the `ret_size` argument is non-`NULL`, the number of bytes written to the file descriptor is stored there. Data is written starting at the `fd`'s current offset, and the `fd` is never rewound. On failure, the `fd` may already contain partially written data. `sd_journal_enumerate_data()` may be used to iterate through all fields of the current entry. On each invocation the data for the next field is returned. The order of these fields is not defined. The data returned is in the same format as with `sd_journal_get_data()` and also follows the same life-time semantics. `sd_journal_enumerate_available_data()` is similar to `sd_journal_enumerate_data()`, but silently skips any fields which may be valid, but are too large or not supported by current implementation. `sd_journal_restart_data()` resets the data enumeration index to the beginning of the entry. The next invocation of `sd_journal_enumerate_data()` will return the first field of the entry again. Note that the `SD_JOURNAL_FOREACH_DATA()` macro may be used as a handy wrapper around `sd_journal_restart_data()` and `sd_journal_enumerate_available_data()`. Note that these functions will not work before `sd_journal_next(3)` (or related call) has been called at least once, in order to position the read pointer at a valid entry. `sd_journal_set_data_threshold()` may be used to change the data field size threshold for data returned by `sd_journal_enumerate_fields()`. This threshold is a hint only: it indicates that the client program is interested only in the initial parts of the data fields, up to the threshold in size — but the library might still return larger data objects. That means applications should not rely exclusively on this setting to limit the size of the data fields returned, but need to apply an explicit size limit on the returned data as well. This threshold defaults to 64K by default. To retrieve the complete data fields this threshold should be turned off by setting it to 0, so that the library always returns the complete data objects. It is recommended to set this threshold as low as possible since this relieves the library from having to decompress large compressed data objects in full. `sd_journal_get_data_threshold()` returns the currently configured data field size threshold. The `flags` argument is a bitmask of zero or more of the following flags: `SD_JOURNAL_DATA_SKIP_FIELD` By default, the result data is prefixed with the field name and `=`, matching the format returned by `sd_journal_get_data()`. When this flag is specified, the prefix is omitted and only the field's value is written to the file descriptor. # Return Value `sd_journal_get_data()` returns 0 on success or a negative errno-style error code. `sd_journal_enumerate_data()` and `sd_journal_enumerate_available_data()` return a positive integer if the next field has been read, 0 when no more fields remain, or a negative errno-style error code. `sd_journal_restart_data()` does not return anything. `sd_journal_set_data_threshold()` and `sd_journal_get_threshold()` return 0 on success or a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` One of the required parameters is `NULL` or invalid. For `sd_journal_get_data()`, only the journal context object and field name are required non-`NULL`. For `sd_journal_enumerate_data()` and `sd_journal_enumerate_available_data()`, `ret_data` and `ret_size` are required as well. `-ECHILD` The journal object was created in a different process, library or module instance. `-EADDRNOTAVAIL` The read pointer is not positioned at a valid entry; `sd_journal_next(3)` or a related call has not been called at least once. `-ENOENT` The current entry does not include the specified field. `-ENOMEM` Memory allocation failed. `-ENOBUFS` A compressed entry is too large. `-E2BIG` The data field is too large for this computer architecture (e.g. above 4 GB on a 32-bit architecture). `-EPROTONOSUPPORT` The journal is compressed with an unsupported method or the journal uses an unsupported feature. `-EBADMSG` The journal is corrupted (possibly just the entry being iterated over). `-EIO` An I/O error was reported by the kernel. `-EBADF` An invalid file descriptor is passed to `sd_journal_get_data_to_fd()`. # Notes # Examples See `sd_journal_next(3)` for a complete example how to use `sd_journal_get_data()`. Use the `SD_JOURNAL_FOREACH_DATA()` macro to iterate through all fields of the current journal entry: … int print_fields(sd_journal *j) { const void *data; size_t length; SD_JOURNAL_FOREACH_DATA(j, data, length) printf("%.*s\n", (int) length, data); } … # History `sd_journal_get_data()`, `sd_journal_enumerate_data()`, `sd_journal_restart_data()`, and `SD_JOURNAL_FOREACH_DATA()` were added in version 187. `sd_journal_set_data_threshold()` and `sd_journal_get_data_threshold()` were added in version 196. `sd_journal_enumerate_available_data()` was added in version 246. `sd_journal_get_data_to_fd()` was added in version 263. # See Also `systemd(1)`, `systemd.journal-fields(7)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_next(3)`, `sd_journal_get_realtime_usec(3)`, `sd_journal_query_unique(3)` # sd_journal_get_fd systemd sd_journal_get_fd 3 sd_journal_get_fd sd_journal_get_events sd_journal_get_timeout sd_journal_process sd_journal_wait sd_journal_reliable_fd SD_JOURNAL_NOP SD_JOURNAL_APPEND SD_JOURNAL_INVALIDATE Journal change notification interface \#include \ int sd_journal_get_fd sd_journal \* j int sd_journal_get_events sd_journal \* j int sd_journal_get_timeout sd_journal \* j uint64_t \* timeout_usec int sd_journal_process sd_journal \* j int sd_journal_wait sd_journal \* j uint64_t timeout_usec int sd_journal_reliable_fd sd_journal \* j # Description `sd_journal_get_fd()` returns a file descriptor that may be asynchronously polled in an external event loop and is signaled as soon as the journal changes, because new entries or files were added, rotation took place, or files have been deleted, and similar. The file descriptor is suitable for usage in `poll(2)`. Use `sd_journal_get_events()` for an events mask to watch for. The call takes one argument: the journal context object. Note that not all file systems are capable of generating the necessary events for wakeups from this file descriptor for changes to be noticed immediately. In particular network files systems do not generate suitable file change events in all cases. Cases like this can be detected with `sd_journal_reliable_fd()`, below. `sd_journal_get_timeout()` will ensure in these cases that wake-ups happen frequently enough for changes to be noticed, although with a certain latency. `sd_journal_get_events()` will return the `poll()` mask to wait for. This function will return a combination of `POLLIN` and `POLLOUT` and similar to fill into the `.events` field of `struct pollfd`. `sd_journal_get_timeout()` will return a timeout value for usage in `poll()`. This returns a value in microseconds since the epoch of `CLOCK_MONOTONIC` for timing out `poll()` in `timeout_usec`. See `clock_gettime(2)` for details about `CLOCK_MONOTONIC`. If there is no timeout to wait for, this will fill in `(uint64_t) -1` instead. Note that `poll()` takes a relative timeout in milliseconds rather than an absolute timeout in microseconds. To convert the absolute 'us' timeout into relative 'ms', use code like the following: uint64_t t; int msec; sd_journal_get_timeout(m, &t); if (t == (uint64_t) -1) msec = -1; else { struct timespec ts; uint64_t n; clock_gettime(CLOCK_MONOTONIC, &ts); n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; msec = t > n ? (int) ((t - n + 999) / 1000) : 0; } The code above does not do any error checking for brevity's sake. The calculated `msec` integer can be passed directly as `poll()`'s timeout parameter. After each `poll()` wake-up `sd_journal_process()` needs to be called to process events. This call will also indicate what kind of change has been detected (see below; note that spurious wake-ups are possible). A synchronous alternative for using `sd_journal_get_fd()`, `sd_journal_get_events()`, `sd_journal_get_timeout()` and `sd_journal_process()` is `sd_journal_wait()`. It will synchronously wait until the journal gets changed. The maximum time this call sleeps may be controlled with the `timeout_usec` parameter. Pass `(uint64_t) -1` to wait indefinitely. Internally this call simply combines `sd_journal_get_fd()`, `sd_journal_get_events()`, `sd_journal_get_timeout()`, `poll()` and `sd_journal_process()` into one. `sd_journal_reliable_fd()` may be used to check whether the wake-up events from the file descriptor returned by `sd_journal_get_fd()` are known to be quickly triggered. On certain file systems where file change events from the OS are not available (such as NFS) changes need to be polled for repeatedly, and hence are detected only with a considerable latency. This call will return a positive value if the journal changes are detected quickly and zero when they need to be polled for. Note that there is usually no need to invoke this function directly as `sd_journal_get_timeout()` will request appropriate timeouts anyway. Note that all of the above change notification interfaces do not report changes instantly. Latencies are introduced for multiple reasons: as mentioned certain storage backends require time-based polling, in other cases wake-ups are optimized by coalescing events, and the OS introduces additional IO/CPU scheduling latencies. # Return Value `sd_journal_get_fd()` returns a valid file descriptor on success or a negative errno-style error code. `sd_journal_get_events()` returns a combination of `POLLIN`, `POLLOUT` and suchlike on success or a negative errno-style error code. `sd_journal_reliable_fd()` returns a positive integer if the file descriptor returned by `sd_journal_get_fd()` will generate wake-ups immediately for all journal changes. Returns 0 if there might be a latency involved. `sd_journal_process()` and `sd_journal_wait()` return a negative errno-style error code, or one of `SD_JOURNAL_NOP`, `SD_JOURNAL_APPEND` or `SD_JOURNAL_INVALIDATE` on success: - If `SD_JOURNAL_NOP` is returned, the journal did not change since the last invocation. - If `SD_JOURNAL_APPEND` is returned, new entries have been appended to the end of the journal. In this case, it is sufficient to simply continue reading at the previous end location of the journal, to read the newly added entries. - If `SD_JOURNAL_INVALIDATE`, journal files were added to or removed from the set of journal files watched (e.g. due to rotation or vacuuming), and thus entries might have appeared or disappeared at arbitrary places in the log stream, possibly before or after the previous end of the log stream. If `SD_JOURNAL_INVALIDATE` is returned, live-view UIs that want to reflect on screen the precise state of the log data on disk should probably refresh their entire display (relative to the cursor of the log entry on the top of the screen). Programs only interested in a strictly sequential stream of log data may treat `SD_JOURNAL_INVALIDATE` the same way as `SD_JOURNAL_APPEND`, thus ignoring any changes to the log view earlier than the old end of the log stream. # Signal safety In general, `sd_journal_get_fd()`, `sd_journal_get_events()`, and `sd_journal_get_timeout()` are *not* "async signal safe" in the meaning of `signal-safety(7)`. Nevertheless, only the first call to any of those three functions performs unsafe operations, so subsequent calls *are* safe. `sd_journal_process()` and `sd_journal_wait()` are not safe. `sd_journal_reliable_fd()` is safe. # Notes # Examples Iterating through the journal, in a live view tracking all changes: Waiting with `poll()` (this example lacks all error checking for the sake of simplicity): # History `sd_journal_get_fd()`, `sd_journal_process()`, and `sd_journal_wait()` were added in version 187. `sd_journal_reliable_fd()` was added in version 196. `sd_journal_get_events()` and `sd_journal_get_timeout()` were added in version 201. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_next(3)`, `poll(2)`, `clock_gettime(2)` # sd_journal_get_realtime_usec systemd sd_journal_get_realtime_usec 3 sd_journal_get_realtime_usec sd_journal_get_monotonic_usec Read timestamps from the current journal entry \#include \ int sd_journal_get_realtime_usec sd_journal \* j uint64_t \* usec int sd_journal_get_monotonic_usec sd_journal \* j uint64_t \* usec sd_id128_t \* boot_id # Description `sd_journal_get_realtime_usec()` gets the realtime (wallclock) timestamp of the current journal entry. It takes two arguments: the journal context object and a pointer to a 64-bit unsigned integer to store the timestamp in. The timestamp is in microseconds since the epoch, i.e. `CLOCK_REALTIME`. `sd_journal_get_monotonic_usec()` gets the monotonic timestamp of the current journal entry. It takes three arguments: the journal context object, a pointer to a 64-bit unsigned integer to store the timestamp in, as well as a 128-bit ID buffer to store the boot ID of the monotonic timestamp. The timestamp is in microseconds since boot-up of the specific boot, i.e. `CLOCK_MONOTONIC`. Since the monotonic clock begins new with every reboot, it only defines a well-defined point in time when used together with an identifier identifying the boot. See `sd_id128_get_boot(3)` for more information. If the boot ID parameter is passed `NULL`, the function will fail if the monotonic timestamp of the current entry is not of the current system boot. Note that these functions will not work before `sd_journal_next(3)` (or related call) has been called at least once, in order to position the read pointer at a valid entry. # Return Value `sd_journal_get_realtime_usec()` and `sd_journal_get_monotonic_usec()` returns 0 on success or a negative errno-style error code. If the boot ID parameter was passed `NULL` and the monotonic timestamp of the current journal entry is not of the current system boot, `-ESTALE` is returned by `sd_journal_get_monotonic_usec()`. # Notes # History `sd_journal_get_realtime_usec()` and `sd_journal_get_monotonic_usec()` were added in version 187. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_next(3)`, `sd_journal_get_data(3)`, `sd_journal_get_seqnum(3)`, `sd_id128_get_boot(3)`, `clock_gettime(2)`, `sd_journal_get_cutoff_realtime_usec(3)` # sd_journal_get_seqnum systemd sd_journal_get_seqnum 3 sd_journal_get_seqnum Read sequence number from the current journal entry \#include \ int sd_journal_get_seqnum sd_journal \* j uint64_t \* ret_seqnum sd_id128_t \* ret_seqnum_id # Description `sd_journal_get_seqnum()` returns the sequence number of the current journal entry. It takes three arguments: the journal context object, a pointer to a 64-bit unsigned integer to store the sequence number in, and a buffer to return the 128-bit sequence number ID in. When writing journal entries to disk each `systemd-journald` instance will number them sequentially, starting from 1 for the first entry written after subsystem initialization. Each such series of sequence numbers is associated with a 128-bit sequence number ID which is initialized randomly, once at `systemd-journal` initialization. Thus, while multiple instances of `systemd-journald` will assign the same sequence numbers to their written journal entries, they will have a distinct sequence number IDs. The sequence number is assigned at the moment of writing the entry to disk. If log entries are rewritten (for example because the volatile logs from `/run/log/` are flushed to `/var/log/` via `systemd-journald-flush.service`) they will get new sequence numbers assigned. Sequence numbers may be used to order entries (entries associated with the same sequence number ID and lower sequence numbers should be ordered chronologically before those with higher sequence numbers), and to detect lost entries. Note that journal service instances typically write to multiple journal files in parallel (for example because `SplitMode=` is used), in which case each journal file will only contain a subset of the sequence numbers. To recover the full stream of journal entries the files must be combined ("interleaved"), a process that primarily relies on the sequence numbers. When journal files are rotated (due to size or time limits), the series of sequence numbers is continued in the replacement files. All journal files generated from the same journal instance will carry the same sequence number ID. As the sequence numbers are assigned at the moment of writing the journal entries to disk they do not exist if storage is disabled via `SplitMode=`. The `ret_seqnum` and `ret_seqnum_id` parameters may be specified as `NULL` in which case the relevant data is not returned (but the call will otherwise succeed). Note that these functions will not work before `sd_journal_next(3)` (or related call) has been called at least once, in order to position the read pointer at a valid entry. # Return Value `sd_journal_get_seqnum()` returns 0 on success or a negative errno-style error code.. # Notes # History `sd_journal_get_seqnum()` was added in version 254. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_next(3)`, `sd_journal_get_data(3)`, `sd_journal_get_monotonic_usec(3)` # sd_journal_get_usage systemd sd_journal_get_usage 3 sd_journal_get_usage Journal disk usage \#include \ int sd_journal_get_usage sd_journal \* j uint64_t \* bytes # Description `sd_journal_get_usage()` determines the total disk space currently used by journal files (in bytes). If `SD_JOURNAL_LOCAL_ONLY` was passed when opening the journal, this value will only reflect the size of journal files of the local host, otherwise of all hosts. # Return Value `sd_journal_get_usage()` returns 0 on success or a negative errno-style error code. # Notes # History `sd_journal_get_usage()` was added in version 190. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_open(3)` # sd_journal_has_runtime_files systemd sd_journal_has_runtime_files 3 sd_journal_has_runtime_files sd_journal_has_persistent_files Query availability of runtime or persistent journal files \#include \ int sd_journal_has_runtime_files sd_journal \* j int sd_journal_has_persistent_files sd_journal \* j # Description `sd_journal_has_runtime_files()` returns a positive value if runtime journal files (present in /run/systemd/journal/) have been found. Otherwise, returns 0. `sd_journal_has_persistent_files()` returns a positive value if persistent journal files (present in /var/log/journal/) have been found. Otherwise, returns 0. # Return value Both `sd_journal_has_runtime_files()` and `sd_journal_has_persistent_files()` return -EINVAL if their argument is `NULL`. # Notes # History `sd_journal_has_runtime_files()` and `sd_journal_has_persistent_files()` were added in version 229. # See Also `systemd(1)`, `sd-journal(3)` # sd_journal_next systemd sd_journal_next 3 sd_journal_next sd_journal_previous sd_journal_step_one sd_journal_next_skip sd_journal_previous_skip SD_JOURNAL_FOREACH SD_JOURNAL_FOREACH_BACKWARDS Advance or set back the read pointer in the journal \#include \ int sd_journal_next sd_journal \* j int sd_journal_previous sd_journal \* j int sd_journal_step_one sd_journal \* j int advanced int sd_journal_next_skip sd_journal \* j uint64_t skip int sd_journal_previous_skip sd_journal \* j uint64_t skip SD_JOURNAL_FOREACH sd_journal \* j SD_JOURNAL_FOREACH_BACKWARDS sd_journal \* j # Description `sd_journal_next()` advances the read pointer into the journal by one entry. The only argument taken is a journal context object as allocated via `sd_journal_open(3)`. After successful invocation the entry may be read with functions such as `sd_journal_get_data(3)`. Similarly, `sd_journal_previous()` sets the read pointer back one entry. `sd_journal_step_one()` also moves the read pointer. If the current location is the head of the journal, e.g. when this is called following `sd_journal_seek_head()`, then this is equivalent to `sd_journal_next()`, and the argument `advanced` will be ignored. Similarly, if the current location is the tail of the journal, e.g. when this is called following `sd_journal_seek_tail()`, then this is equivalent to `sd_journal_previous()`, and `advanced` will be ignored. Otherwise, this is equivalent to `sd_journal_next()` when `advanced` is non-zero, and `sd_journal_previous()` when `advanced` is zero. `sd_journal_next_skip()` and `sd_journal_previous_skip()` advance/set back the read pointer by multiple entries at once, as specified in the `skip` parameter. The `skip` parameter must be less than or equal to 2147483647 (2³¹-1). The journal is strictly ordered by reception time, and hence advancing to the next entry guarantees that the entry then pointing to is later in time than then previous one, or has the same timestamp. Note that `sd_journal_get_data(3)` and related calls will fail unless `sd_journal_next()` has been invoked at least once in order to position the read pointer on a journal entry. Note that the `SD_JOURNAL_FOREACH()` macro may be used as a wrapper around `sd_journal_seek_head(3)` and `sd_journal_next()` in order to make iterating through the journal easier. See below for an example. Similarly, `SD_JOURNAL_FOREACH_BACKWARDS()` may be used for iterating the journal in reverse order. # Return Value The four calls return the number of entries advanced/set back on success or a negative errno-style error code. When the end or beginning of the journal is reached, a number smaller than requested is returned. More specifically, if `sd_journal_next()` or `sd_journal_previous()` reach the end/beginning of the journal they will return 0, instead of 1 when they are successful. This should be considered an EOF marker. # Notes # Examples Iterating through the journal: # History `sd_journal_next()`, `sd_journal_previous()`, `sd_journal_next_skip()`, `sd_journal_previous_skip()`, `SD_JOURNAL_FOREACH()`, and `SD_JOURNAL_FOREACH_BACKWARDS()` were added in version 187. `sd_journal_step_one()` was added in version 254. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_get_data(3)`, `sd_journal_get_realtime_usec(3)`, `sd_journal_get_cursor(3)` # sd_journal_open systemd sd_journal_open 3 sd_journal_open sd_journal_open_directory sd_journal_open_directory_fd sd_journal_open_files sd_journal_open_files_fd sd_journal_open_namespace sd_journal_close sd_journal SD_JOURNAL_LOCAL_ONLY SD_JOURNAL_RUNTIME_ONLY SD_JOURNAL_SYSTEM SD_JOURNAL_CURRENT_USER SD_JOURNAL_OS_ROOT SD_JOURNAL_ALL_NAMESPACES SD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE SD_JOURNAL_TAKE_DIRECTORY_FD Open the system journal for reading \#include \ int sd_journal_open sd_journal \*\* ret int flags int sd_journal_open_namespace sd_journal \*\* ret const char \* namespace int flags int sd_journal_open_directory sd_journal \*\* ret const char \* path int flags int sd_journal_open_directory_fd sd_journal \*\* ret int fd int flags int sd_journal_open_files sd_journal \*\* ret const char \*\* paths int flags int sd_journal_open_files_fd sd_journal \*\* ret int fds\[\] unsigned n_fds int flags void sd_journal_close sd_journal \* j # Description `sd_journal_open()` opens the log journal for reading. It will find all journal files automatically and interleave them automatically when reading. As first argument it takes a pointer to a `sd_journal` pointer, which, on success, will contain a journal context object. The second argument is a flags field, which may consist of the following flags ORed together: `SD_JOURNAL_LOCAL_ONLY` makes sure only journal files generated on the local machine will be opened. `SD_JOURNAL_RUNTIME_ONLY` makes sure only volatile journal files will be opened, excluding those which are stored on persistent storage. `SD_JOURNAL_SYSTEM` will cause journal files of system services and the kernel (in opposition to user session processes) to be opened. `SD_JOURNAL_CURRENT_USER` will cause journal files of the current user to be opened. If neither `SD_JOURNAL_SYSTEM` nor `SD_JOURNAL_CURRENT_USER` are specified, all journal file types will be opened. `sd_journal_open_namespace()` is similar to `sd_journal_open()` but takes an additional `namespace` parameter that specifies which journal namespace to operate on. If specified as `NULL` the call is identical to `sd_journal_open()`. If non-`NULL` only data from the namespace identified by the specified parameter is accessed. This call understands two additional flags: if `SD_JOURNAL_ALL_NAMESPACES` is specified the `namespace` parameter is ignored and all defined namespaces are accessed simultaneously; if `SD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE` the specified namespace and the default namespace are accessed but no others (this flag has no effect when `namespace` is passed as `NULL`). For details about journal namespaces see `systemd-journald.service(8)`. `sd_journal_open_directory()` is similar to `sd_journal_open()` but takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved automatically. This call also takes a flags argument. The flags parameters accepted by this call are `SD_JOURNAL_OS_ROOT`, `SD_JOURNAL_SYSTEM`, and `SD_JOURNAL_CURRENT_USER`. If `SD_JOURNAL_OS_ROOT` is specified, journal files are searched for below the usual `/var/log/journal` and `/run/log/journal` relative to the specified path, instead of directly beneath it. The other two flags limit which files are opened, the same as for `sd_journal_open()`. `sd_journal_open_directory_fd()` is similar to `sd_journal_open_directory()`, but takes a file descriptor referencing a directory in the file system instead of an absolute file system path. In addition to the flags accepted by `sd_journal_open_directory()`, this function also accepts `SD_JOURNAL_TAKE_DIRECTORY_FD`. If `SD_JOURNAL_TAKE_DIRECTORY_FD` is specified, the function will take the ownership of the specified file descriptor on success, and it will be closed by `sd_journal_close()`, hence the caller of the function must not close the file descriptor. When the flag is not specified, `sd_journal_close()` will not close the file descriptor, so the caller should close it after `sd_journal_close()`. `sd_journal_open_files()` is similar to `sd_journal_open()` but takes a `NULL`-terminated list of file paths to open. All files will be opened and interleaved automatically. This call also takes a flags argument, but it must be passed as 0 as no flags are currently understood for this call. Please note that in the case of a live journal, this function is only useful for debugging, because individual journal files can be rotated at any moment, and the opening of specific files is inherently racy. `sd_journal_open_files_fd()` is similar to `sd_journal_open_files()` but takes an array of open file descriptors that must reference journal files, instead of an array of file system paths. Pass the array of file descriptors as second argument, and the number of array entries in the third. The flags parameter must be passed as 0. `sd_journal` objects cannot be used in the child after a fork. Functions which take a journal object as an argument (`sd_journal_next()` and others) will return `-ECHILD` after a fork. `sd_journal_close()` will close the journal context allocated with `sd_journal_open()` or `sd_journal_open_directory()` and free its resources. When opening the journal only journal files accessible to the calling user will be opened. If journal files are not accessible to the caller, this will be silently ignored. See `sd_journal_next(3)` for an example of how to iterate through the journal after opening it with `sd_journal_open()`. A journal context object returned by `sd_journal_open()` references a specific journal entry as *current* entry, similar to a file seek index in a classic file system file, but without absolute positions. It may be altered with `sd_journal_next(3)` and `sd_journal_seek_head(3)` and related calls. The current entry position may be exported in *cursor* strings, as accessible via `sd_journal_get_cursor(3)`. Cursor strings may be used to globally identify a specific journal entry in a stable way and then later to seek to it (or if the specific entry is not available locally, to its closest entry in time) `sd_journal_seek_cursor(3)`. Notification of journal changes is available via `sd_journal_get_fd()` and related calls. # Return Value The `sd_journal_open()`, `sd_journal_open_directory()`, and `sd_journal_open_files()` calls return 0 on success or a negative errno-style error code. `sd_journal_close()` returns nothing. # Notes # History `sd_journal_open()`, `sd_journal_open_directory()`, and `sd_journal_close()` were added in version 187. `sd_journal_open_files()` was added in version 205. `sd_journal_open_directory_fd()` and `sd_journal_open_files_fd()` were added in version 230. `sd_journal_open_namespace()` was added in version 245. # See Also `systemd(1)`, `sd-journal(3)`, `systemd-journald.service(8)`, `sd_journal_next(3)`, `sd_journal_get_data(3)` # sd_journal_print systemd sd_journal_print 3 sd_journal_print sd_journal_printv sd_journal_send sd_journal_sendv sd_journal_perror SD_JOURNAL_SUPPRESS_LOCATION sd_journal_print_with_location sd_journal_printv_with_location sd_journal_send_with_location sd_journal_sendv_with_location sd_journal_perror_with_location Submit log entries to the journal \#include \ int sd_journal_print int priority const char \* format … int sd_journal_printv int priority const char \* format va_list ap int sd_journal_send const char \* format … int sd_journal_sendv const struct iovec \* iov int n int sd_journal_perror const char \* message int sd_journal_print_with_location int priority const char \* file const char \* line const char \* func const char \* format … int sd_journal_printv_with_location int priority const char \* file const char \* line const char \* func const char \* format va_list ap int sd_journal_send_with_location const char \* file const char \* line const char \* func const char \* format … int sd_journal_sendv_with_location const char \* file const char \* line const char \* func const struct iovec \* iov int n int sd_journal_perror_with_location const char \* file const char \* line const char \* func const char \* message # Description `sd_journal_print()` may be used to submit simple, plain text log entries to the system journal. The first argument is a priority value. This is followed by a format string and its parameters, similar to `printf(3)` or `syslog(3)`. Note that currently the resulting message will be truncated to `LINE_MAX - 8`. The priority value is one of `LOG_EMERG`, `LOG_ALERT`, `LOG_CRIT`, `LOG_ERR`, `LOG_WARNING`, `LOG_NOTICE`, `LOG_INFO`, `LOG_DEBUG`, as defined in `syslog.h`, see `syslog(3)` for details. It is recommended to use this call to submit log messages in the application locale or system locale and in UTF-8 format, but no such restrictions are enforced. Note that log messages written using this function are generally not expected to end in a new-line character. However, as all trailing whitespace (including spaces, new-lines, tabulators and carriage returns) are automatically stripped from the logged string, it is acceptable to specify one (or more). Empty lines (after trailing whitespace removal) are suppressed. On non-empty lines, leading whitespace (as well as inner whitespace) is left unmodified. `sd_journal_printv()` is similar to `sd_journal_print()` but takes a variable argument list encapsulated in an object of type `va_list` (see `stdarg(3)` for more information) instead of the format string. It is otherwise equivalent in behavior. `sd_journal_send()` may be used to submit structured log entries to the system journal. It takes a series of format strings, each immediately followed by their associated parameters, terminated by `NULL`. The strings passed should be of the format `VARIABLE=value`. The variable name must be in uppercase and consist only of characters, numbers and underscores, and may not begin with an underscore. (All assignments that do not follow this syntax will be ignored.) The value can be of any size and format. It is highly recommended to submit text strings formatted in the UTF-8 character encoding only, and submit binary fields only when formatting in UTF-8 strings is not sensible. A number of well-known fields are defined, see `systemd.journal-fields(7)` for details, but additional application defined fields may be used. A variable may be assigned more than one value per entry. If this function is used, trailing whitespace is automatically removed from each formatted field. `sd_journal_sendv()` is similar to `sd_journal_send()` but takes an array of `struct iovec` (as defined in `uio.h`, see `readv(3)` for details) instead of the format string. Each structure should reference one field of the entry to submit. The second argument specifies the number of structures in the array. `sd_journal_sendv()` is particularly useful to submit binary objects to the journal where that is necessary. Note that this function will not strip trailing whitespace of the passed fields, but passes the specified data along unmodified. This is different from both `sd_journal_print()` and `sd_journal_send()` described above, which are based on format strings, and do strip trailing whitespace. `sd_journal_perror()` is similar to `perror(3)` and writes a message to the journal that consists of the passed string, suffixed with ": " and a human-readable representation of the current error code stored in `errno(3)`. If the message string is passed as `NULL` or empty string, only the error string representation will be written, prefixed with nothing. An additional journal field ERRNO= is included in the entry containing the numeric error code formatted as decimal string. The log priority used is `LOG_ERR` (3). Note that `sd_journal_send()` is a wrapper around `sd_journal_sendv()` to make it easier to use when only text strings shall be submitted. Also, the following two calls are mostly equivalent: sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid()); sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(), "PRIORITY=%i", LOG_INFO, NULL); Note that these calls implicitly add fields for the source file, function name and code line where invoked. This is implemented with macros. If this is not desired, it can be turned off by defining `SD_JOURNAL_SUPPRESS_LOCATION` before including `sd-journal.h`. `sd_journal_print_with_location()`, `sd_journal_printv_with_location()`, `sd_journal_send_with_location()`, `sd_journal_sendv_with_location()`, and `sd_journal_perror_with_location()` are similar to their counterparts without `_with_location`, but accept additional parameters to explicitly set the source file name, function, and line. The arguments `file` and `line` must contain valid journal entries including the variable name, e.g. `CODE_FILE=src/foo.c` and `CODE_LINE=666`, while `func` must only contain the function name, i.e. the value without `CODE_FUNC=`. These variants are primarily useful when writing custom wrappers, for example in bindings for a different language. `syslog(3)` and `sd_journal_print()` may largely be used interchangeably functionality-wise. However, note that log messages logged via the former take a different path to the journal server than the later, and hence global chronological ordering between the two streams cannot be guaranteed. Using `sd_journal_print()` has the benefit of logging source code line, filenames, and functions as metadata along all entries, and guaranteeing chronological ordering with structured log entries that are generated via `sd_journal_send()`. Using `syslog()` has the benefit of being more portable. These functions implement a client to the [Native Journal Protocol](https://systemd.io/JOURNAL_NATIVE_PROTOCOL). # Return Value The ten functions return 0 on success or a negative errno-style error code. The `errno(3)` variable itself is not altered. If `systemd-journald(8)` is not running (the socket is not present), those functions do nothing, and also return 0. # Thread safety `sd_journal_sendv()` and `sd_journal_sendv_with_location()` are "async signal safe" in the meaning of `signal-safety(7)`. `sd_journal_print()`, `sd_journal_printv()`, `sd_journal_send()`, `sd_journal_perror()`, and their counterparts with `_with_location` are not async signal safe. # History `sd_journal_print()`, `sd_journal_printv()`, `sd_journal_send()`, and `sd_journal_sendv()` were added in version 187. `sd_journal_perror()` was added in version 188. `sd_journal_print_with_location()`, `sd_journal_printv_with_location()`, `sd_journal_send_with_location()`, `sd_journal_sendv_with_location()`, and `sd_journal_perror_with_location()` were added in version 246. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_stream_fd(3)`, `syslog(3)`, `perror(3)`, `errno(3)`, `systemd.journal-fields(7)`, `signal(7)`, `socket(7)` # sd_journal_query_unique systemd sd_journal_query_unique 3 sd_journal_query_unique sd_journal_enumerate_unique sd_journal_enumerate_available_unique sd_journal_restart_unique SD_JOURNAL_FOREACH_UNIQUE Read unique data fields from the journal \#include \ int sd_journal_query_unique sd_journal \* j const char \* field int sd_journal_enumerate_available_unique sd_journal \* j const void \*\* data size_t \* length int sd_journal_enumerate_unique sd_journal \* j const void \*\* data size_t \* length void sd_journal_restart_unique sd_journal \* j SD_JOURNAL_FOREACH_UNIQUE sd_journal \* j const void \* data size_t length # Description `sd_journal_query_unique()` queries the journal for all unique values the specified field can take. It takes two arguments: the journal to query and the field name to look for. Well-known field names are listed on `systemd.journal-fields(7)`, but any field can be specified. Field names must be specified without a trailing `=`. After this function has been executed successfully the field values may be queried using `sd_journal_enumerate_unique()` and `sd_journal_enumerate_available_unique()`. Invoking one of those calls will change the field name being queried and reset the enumeration index to the first field value that matches. `sd_journal_enumerate_unique()` may be used to iterate through all data fields which match the previously selected field name as set with `sd_journal_query_unique()`. On each invocation the next field data matching the field name is returned. The order of the returned data fields is not defined. It takes three arguments: the journal object, plus a pair of pointers to pointer/size variables where the data object and its size shall be stored. The returned data is in a read-only memory map and is only valid until the next invocation of `sd_journal_enumerate_unique()`. Note that the data returned will be prefixed with the field name and `=`. An error is returned for fields which cannot be retrieved. See the error list below for details. `sd_journal_enumerate_available_unique()` is similar to `sd_journal_enumerate_unique()`, but silently skips any fields which may be valid, but are too large or not supported by current implementation. `sd_journal_restart_unique()` resets the data enumeration index to the beginning of the list. The next invocation of `sd_journal_enumerate_unique()` will return the first field data matching the field name again. Note that the `SD_JOURNAL_FOREACH_UNIQUE()` macro may be used as a handy wrapper around `sd_journal_restart_unique()` and `sd_journal_enumerate_available_unique()`. Note that these functions currently are not influenced by matches set with `sd_journal_add_match()` but this might change in a later version of this software. To enumerate all field names currently in use (and thus all suitable field parameters for `sd_journal_query_unique()`), use the `sd_journal_enumerate_fields(3)` call. # Return Value `sd_journal_query_unique()` returns 0 on success or a negative errno-style error code. `sd_journal_enumerate_unique()` and `sd_journal_enumerate_available_unique()` return a positive integer if the next field data has been read, 0 when no more fields remain, or a negative errno-style error code. `sd_journal_restart_unique()` does not return anything. ## Errors Returned errors may indicate the following problems: # Notes # Examples Use the `SD_JOURNAL_FOREACH_UNIQUE()` macro to iterate through all values a field of the journal can take (and which can be accessed on the given architecture and are not compressed with an unsupported mechanism). The following example lists all unit names referenced in the journal: # History `sd_journal_query_unique()`, `sd_journal_enumerate_unique()`, `sd_journal_restart_unique()`, and `SD_JOURNAL_FOREACH_UNIQUE()` were added in version 195. `sd_journal_enumerate_available_unique()` was added in version 246. # See Also `systemd(1)`, `systemd.journal-fields(7)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_enumerate_fields(3)`, `sd_journal_get_data(3)`, `sd_journal_add_match(3)` # sd_journal_seek_head systemd sd_journal_seek_head 3 sd_journal_seek_head sd_journal_seek_tail sd_journal_seek_monotonic_usec sd_journal_seek_realtime_usec sd_journal_seek_cursor Seek to a position in the journal \#include \ int sd_journal_seek_head sd_journal \* j int sd_journal_seek_tail sd_journal \* j int sd_journal_seek_monotonic_usec sd_journal \* j sd_id128_t boot_id uint64_t usec int sd_journal_seek_realtime_usec sd_journal \* j uint64_t usec int sd_journal_seek_cursor sd_journal \* j const char \* cursor # Description `sd_journal_seek_head()` seeks to the beginning of the journal, i.e. to the position before the oldest available entry. Similarly, `sd_journal_seek_tail()` may be used to seek to the end of the journal, i.e. the position after the most recent available entry. `sd_journal_seek_monotonic_usec()` seeks to a position with the specified monotonic timestamp, i.e. `CLOCK_MONOTONIC`. Since monotonic time restarts on every reboot a boot ID needs to be specified as well. `sd_journal_seek_realtime_usec()` seeks to a position with the specified realtime (wallclock) timestamp, i.e. `CLOCK_REALTIME`. Note that the realtime clock is not necessarily monotonic. If a realtime timestamp is ambiguous, it is not defined which position is sought to. `sd_journal_seek_cursor()` seeks to the position at the specified cursor string. For details on cursors, see `sd_journal_get_cursor(3)`. If no entry matching the specified cursor is found the call will seek to the next closest entry (in terms of time) instead. Note that these calls do not actually make any entry the new current entry, this needs to be done in a separate step with a subsequent `sd_journal_next(3)` invocation (or a similar call). Only then, entry data may be retrieved via `sd_journal_get_data(3)` or an entry cursor be retrieved via `sd_journal_get_cursor(3)`. If no entry exists that matches exactly the specified seek address, the next closest is sought to. If `sd_journal_next(3)` is used, the closest following entry will be sought to, if `sd_journal_previous(3)` is used the closest preceding entry is sought to. After the seek is done, and `sd_journal_next(3)` or a similar call has been made, `sd_journal_test_cursor(3)` may be used to verify whether the newly selected entry actually matches the cursor. # Return Value The functions return 0 on success or a negative errno-style error code. # Notes # History `sd_journal_seek_head()`, `sd_journal_seek_tail()`, `sd_journal_seek_monotonic_usec()`, `sd_journal_seek_realtime_usec()`, and `sd_journal_seek_cursor()` were added in version 187. # See Also `systemd(1)`, `sd-journal(3)`, `sd_journal_open(3)`, `sd_journal_next(3)`, `sd_journal_get_data(3)`, `sd_journal_get_cursor(3)`, `sd_journal_get_realtime_usec(3)` # sd_journal_stream_fd systemd sd_journal_stream_fd 3 sd_journal_stream_fd sd_journal_stream_fd_with_namespace Create log stream file descriptor to the journal \#include \ int sd_journal_stream_fd const char \* identifier int priority int level_prefix int sd_journal_stream_fd_with_namespace const char \* name_space const char \* identifier int priority int level_prefix # Description `sd_journal_stream_fd()` may be used to create a log stream file descriptor. Log messages written to this file descriptor as simple newline-separated text strings are written to the journal. This file descriptor can be used internally by applications or be made standard output or standard error of other processes executed. `sd_journal_stream_fd()` takes a short program identifier string as first argument, which will be written to the journal as SYSLOG_IDENTIFIER= field for each log entry (see `systemd.journal-fields(7)` for more information). The second argument shall be the default priority level for all messages. The priority level is one of `LOG_EMERG`, `LOG_ALERT`, `LOG_CRIT`, `LOG_ERR`, `LOG_WARNING`, `LOG_NOTICE`, `LOG_INFO`, `LOG_DEBUG`, as defined in `syslog.h`, see `syslog(3)` for details. The third argument is a boolean: if true kernel-style log level prefixes (such as `SD_WARNING`) are interpreted, see `sd-daemon(3)` for more information. `sd_journal_stream_fd_with_namespace()` is similar to `sd_journal_stream_fd()`, but takes an additional `name_space` parameter that specifies which journal namespace to operate on. If specified as `NULL` the call is identical to `sd_journal_stream_fd()`. For details about journal namespaces, see `systemd-journald.service(8)`. It is recommended that applications log UTF-8 messages only with this API, but this is not enforced. Each invocation of these functions allocates a new log stream file descriptor, that is not shared with prior or later invocations. The file descriptor is write-only (its reading direction is shut down), and `O_NONBLOCK` is turned off initially. # Return Value The call returns a valid write-only file descriptor on success or a negative errno-style error code. # Signal safety `sd_journal_stream_fd()` and `sd_journal_stream_fd_with_namespace()` are "async signal safe" in the meaning of `signal-safety(7)`. # Notes # Examples Creating a log stream suitable for `fprintf(3)`: # History `sd_journal_stream_fd()` was added in version 187. `sd_journal_stream_fd_with_namespace()` was added in version 256. # See Also `systemd(1)`, `sd-journal(3)`, `sd-daemon(3)`, `sd_journal_print(3)`, `syslog(3)`, `fprintf(3)`, `systemd.journal-fields(7)` # sd_json_dispatch_string systemd sd_json_dispatch_string 3 sd_json_dispatch_string sd_json_dispatch_const_string sd_json_dispatch_strv sd_json_dispatch_stdbool sd_json_dispatch_intbool sd_json_dispatch_tristate sd_json_dispatch_variant sd_json_dispatch_variant_noref sd_json_dispatch_int64 sd_json_dispatch_int32 sd_json_dispatch_int16 sd_json_dispatch_int8 sd_json_dispatch_uint64 sd_json_dispatch_uint32 sd_json_dispatch_uint16 sd_json_dispatch_uint8 sd_json_dispatch_double sd_json_dispatch_uid_gid sd_json_dispatch_id128 sd_json_dispatch_signal sd_json_dispatch_unsupported Decode JSON variant values and write them to the specified memory \#include \ int sd_json_dispatch_string const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_const_string const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_strv const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_stdbool const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_intbool const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_tristate const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_variant const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_variant_noref const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_int64 const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_int32 const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_int16 const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_int8 const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_uint64 const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_uint32 const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_uint16 const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_uint8 const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_double const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_uid_gid const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_id128 const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_signal const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata int sd_json_dispatch_unsupported const char \* name sd_json_variant \* variant sd_dispatch_flags flags void \* userdata # Description The various functions described here are intended for use in the `sd_json_dispatch_field` structure arrays the `sd_json_dispatch(3)` and `sd_varlink_dispatch(3)` functions accept; they decode the provided JSON variant object's value, and write it to the memory indicated by the `userdata` pointer. The `name` parameter contains the field name (in the JSON object it is contained in) of the value being decoded. For details on the `flags` parameter see the `sd_json_dispatch()` documentation. Note that all these functions not only accept the native JSON type they are intended for, but also accept null JSON values, in which case they assign an appropriate invalid/unset/null value, as appropriate for the type (for details see below). `sd_json_dispatch_string()` decodes a JSON string value, and allocates a `NUL` terminated copy in dynamic memory. The `userdata` pointer must point to a pointer to a string, which is freed if non-`NULL`, and then replaced by the newly allocated one. If a JSON null value is passed, the existing string is freed and `NULL` is assigned. `sd_json_dispatch_const_string()` is very similar to `sd_json_dispatch_string()`, but does not allocate a string in dynamic memory. Instead, it just writes a pointer into the JSON object into the indicated memory (or `NULL` in case a JSON null object is passed). The memory remains valid only as long as the indicated variant object is kept allocated (which can happen via direct reference, or via an indirect one via an object that references the specified variant). The memory `userdata` points to on input is *not* freed before the new value is assigned. `sd_json_dispatch_stdbool()` and `sd_json_dispatch_intbool()` decode JSON boolean values and write them to the indicated memory. The former expects a variable of the C99 `bool` type in the indicated memory, the latter an `int` (which will only receive the values 0 and 1). The JSON null value is treated equivalent to a JSON false. `sd_json_dispatch_tristate()` is very similar to`sd_json_dispatch_intbool()`, but will assign -1 if a JSON null value is passed. Or in other words, the integer will have a value \> 0, == 0 or \< 0, for the cases true, false or invalid/unset/null. `sd_json_dispatch_variant()` takes an additional reference to the passed JSON object (via `sd_json_variant_ref()`) and writes the pointer to the indicated memory. No decoding is done. If the indicated pointer is non-`NULL` on input it is freed (via `sd_json_variant_unref()`) before the new pointer is written. `sd_json_dispatch_variant_noref()` is similar, but does *not* take a new reference to the JSON variant object. The pointer hence only remains valid as long as the original object stays referenced. If the indicated pointer is non-`NULL` on input it is *not* freed before the new pointer is written. The `sd_json_dispatch_int64()`, `sd_json_dispatch_int32()`, `sd_json_dispatch_int16()`, `sd_json_dispatch_int8()`, `sd_json_dispatch_uint64()`, `sd_json_dispatch_uint32()`, `sd_json_dispatch_uint16()` and `sd_json_dispatch_uint8()` functions decode a JSON integer value, and write the value to the indicated memory. The function names indicate the word width and signedness of the integers being parsed. If the JSON null value is passed the functions for the unsigned integer types will assign the maximum value the type takes (i.e. `UINT64_MAX`, `UINT32_MAX` …), and the signed versions assign -1. If the `SD_JSON_NULL_TO_ZERO` flag is passed, then all of the functions will instead assign 0 when JSON null is passed. Instead of a JSON integer value these functions also accept JSON strings that contain formatted decimal numbers, in order to improve compatibility for encoding integer values that cannot be represented in 64bit double precision floating point numbers in other programming languages that encode JSON numerals this way. The `sd_json_dispatch_double()` function decodes a 64bit double precision floating point number. If a JSON null value is passed, assigns NaN. The `sd_json_dispatch_uid_gid()` function is similar to `sd_json_dispatch_uint32()`, and is intended to decode 32bit UNIX UID/GID numbers, as used on Linux. It will decode a JSON null value as 4294967295 (i.e. `(uid_t) -1`), and will refuse the values 65535 and 4294967295 when passed as JSON numerals (i.e. both the 16bit and 32bit "invalid" UID/GID, as these values have special meaning for various UNIX syscalls, on different OSes and file systems). `sd_json_dispatch_id128()` decodes a 128bit ID formatted as a JSON string. It supports both RFC9562 UUID formatting, as well as 64 hexadecimal characters without separators, the same way as `sd_id128_from_string(3)`. If the JSON null value is passed, the all-zero ID is assigned. `sd_json_dispatch_signal()` decodes a UNIX process signal specification. It expects either an JSON string containing a signal name such as `SIGINT` or `SIGTERM`, or an unsigned JSON integer value with the signal number (in the Linux definition). The indicated memory must point to an `int` variable to write the signal number to. If the JSON null value is passed a negative value will be written to the memory. `sd_json_dispatch_unsupported()` will always fail with the -`EINVAL` error. # Return Value On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. `-ENOMEM` Memory allocation failed. # History `sd_json_dispatch_string()`, `sd_json_dispatch_const_string()`, `sd_json_dispatch_strv()`, `sd_json_dispatch_stdbool()`, `sd_json_dispatch_intbool()`, `sd_json_dispatch_tristate()`, `sd_json_dispatch_variant()`, `sd_json_dispatch_variant_noref()`, `sd_json_dispatch_int64()`, `sd_json_dispatch_int32()`, `sd_json_dispatch_int16()`, `sd_json_dispatch_int8()`, `sd_json_dispatch_uint64()`, `sd_json_dispatch_uint32()`, `sd_json_dispatch_uint16()`, `sd_json_dispatch_uint8()`, `sd_json_dispatch_double()`, `sd_json_dispatch_uid_gid()`, `sd_json_dispatch_id128()`, `sd_json_dispatch_signal()`, `sd_json_dispatch_unsupported()` were added in version 257. # See Also `systemd(1)`, `sd-json(3)`, `sd-varlink(3)`, `sd_json_dispatch(3)`, `sd_variant_dispatch(3)` # sd_json_parse systemd sd_json_parse 3 sd_json_parse sd_json_parse_continue sd_json_parse_with_source sd_json_parse_with_source_continue sd_json_parse_file sd_json_parse_file_at sd_json_parse_fd SD_JSON_PARSE_SENSITIVE SD_JSON_PARSE_MUST_BE_OBJECT SD_JSON_PARSE_MUST_BE_ARRAY SD_JSON_PARSE_SEEK0 SD_JSON_PARSE_DONATE_FD SD_JSON_PARSE_REOPEN_FD Parse JSON strings and files into JSON variant objects \#include \ int sd_json_parse const char \* string sd_json_parse_flags_t flags sd_json_variant \*\* ret unsigned \* reterr_line unsigned \* reterr_column int sd_json_parse_continue const char \*\* p sd_json_parse_flags_t flags sd_json_variant \*\* ret unsigned \* reterr_line unsigned \* reterr_column int sd_json_parse_with_source const char \* string const char \* source sd_json_parse_flags_t flags sd_json_variant \*\* ret unsigned \* reterr_line unsigned \* reterr_column int sd_json_parse_with_source_continue const char \*\* p const char \* source sd_json_parse_flags_t flags sd_json_variant \*\* ret unsigned \* reterr_line unsigned \* reterr_column int sd_json_parse_file FILE \* f const char \* path sd_json_parse_flags_t flags sd_json_variant \*\* ret unsigned \* reterr_line unsigned \* reterr_column int sd_json_parse_file_at FILE \* f int dir_fd const char \* path sd_json_parse_flags_t flags sd_json_variant \*\* ret unsigned \* reterr_line unsigned \* reterr_column int sd_json_parse_fd const char \* path int fd sd_json_parse_flags_t flags sd_json_variant \*\* ret unsigned \* reterr_line unsigned \* reterr_column # Description `sd_json_parse()` parses the JSON string in `string` and returns the resulting JSON variant object in `ret`. The input must contain exactly one JSON value (object, array, string, number, boolean, or null); any trailing non-whitespace content after the first parsed value is considered an error. If parsing fails, the `reterr_line` and `reterr_column` arguments are set to the line and column (both one-based) where the parse error occurred. One or both may be passed as `NULL` if the caller is not interested in error location information. On success, the return value is non-negative and `ret` is set to a newly allocated JSON variant object (which must be freed with `sd_json_variant_unref(3)` when no longer needed). `ret` may be passed as `NULL`, in which case the input is validated but no object is returned. `sd_json_parse_continue()` is similar, but is intended for parsing a sequence of concatenated JSON values from a single input string. Instead of taking a `const char *` string directly, it takes a pointer to a `const char *` pointer. After each successful parse, the pointer is advanced past the consumed input, so that subsequent calls will parse the next JSON value. This is useful for parsing newline-delimited JSON (NDJSON) streams or similar concatenated JSON formats. Unlike `sd_json_parse()`, trailing content after the first JSON value is not considered an error — it is expected to be the beginning of the next value. `sd_json_parse_with_source()` and `sd_json_parse_with_source_continue()` are similar to `sd_json_parse()` and `sd_json_parse_continue()`, respectively, but take an additional `source` argument. This is a human-readable string (typically a file name or other origin identifier) that is attached to the parsed JSON variant object and can later be retrieved via `sd_json_variant_get_source(3)`. If `source` is `NULL`, no source information is attached. `sd_json_parse()` and `sd_json_parse_continue()` are equivalent to calling their `_with_source` counterparts with `source` set to `NULL`. `sd_json_parse_file()` reads and parses a JSON value from a file. If the `f` argument is non-`NULL`, the JSON text is read from the specified `FILE` stream. If `f` is `NULL`, the file indicated by `path` is opened and read instead. The `path` argument serves a dual purpose: it is both used for opening the file (if `f` is `NULL`) and recorded as source information in the resulting JSON variant (see above). `sd_json_parse_file_at()` is similar to `sd_json_parse_file()`, but takes an additional `dir_fd` argument which specifies a file descriptor referring to the directory to resolve relative paths specified in `path` against. If set to `AT_FDCWD`, relative paths are resolved against the current working directory, which is the default behaviour of `sd_json_parse_file()`. `sd_json_parse_fd()` reads and parses a JSON value from the file referenced by the file descriptor `fd`. By default the file descriptor is internally duplicated and the caller's descriptor is left untouched (the current file offset will be shared with the original file descriptor however); the JSON text is read starting at the descriptor's current file offset. This behaviour may be modified via the `SD_JSON_PARSE_SEEK0`, `SD_JSON_PARSE_DONATE_FD` and `SD_JSON_PARSE_REOPEN_FD` flags, see below. The `path` argument is not used to open anything in this case; it is only recorded as source information in the resulting JSON variant (see above) and may be passed as `NULL`. The `flags` argument is a bitmask of zero or more of the following flags: `SD_JSON_PARSE_SENSITIVE` Marks the resulting JSON variant as "sensitive", indicating that it contains secret key material or similar confidential data. Sensitive variants are erased from memory when freed and are excluded from certain debug logging and introspection operations. See `sd_json_variant_sensitive(3)` for details. `SD_JSON_PARSE_MUST_BE_OBJECT` Requires that the top-level JSON value be a JSON object (i.e. `{…}`). If the top-level value is an array, string, number, boolean, or null, parsing fails with `-EINVAL`. `SD_JSON_PARSE_MUST_BE_ARRAY` Requires that the top-level JSON value be a JSON array (i.e. `[…]`). If the top-level value is an object, string, number, boolean, or null, parsing fails with `-EINVAL`. `SD_JSON_PARSE_SEEK0` Before reading, seek the input to its beginning (i.e. file offset 0). This flag has no effect when parsing from a string. When used together with `SD_JSON_PARSE_REOPEN_FD` in `sd_json_parse_fd()` it is redundant, since a freshly reopened file descriptor starts at offset 0 anyway. `SD_JSON_PARSE_DONATE_FD` Only has an effect on `sd_json_parse_fd()`. If set, ownership of the file descriptor passed in `fd` is transferred into the call: the descriptor is consumed and closed before the function returns, including in the error path. If not set (the default), the caller retains ownership of `fd` and the function operates on an internally duplicated descriptor instead. This flag may not be combined with `SD_JSON_PARSE_REOPEN_FD`. `SD_JSON_PARSE_REOPEN_FD` Only has an effect on `sd_json_parse_fd()`. If set, the file descriptor passed in `fd` is reopened (read-only) before reading, instead of being duplicated. This is primarily useful to obtain an independent file offset (positioned at the beginning of the file) and a clean, read-only access mode, even if the original descriptor was opened differently (for example with `O_PATH`). The caller retains ownership of the original descriptor, which is left untouched. This flag may not be combined with `SD_JSON_PARSE_DONATE_FD`. If both `SD_JSON_PARSE_MUST_BE_OBJECT` and `SD_JSON_PARSE_MUST_BE_ARRAY` are set, both objects and arrays are accepted, but non-container values (strings, numbers, booleans, null) are still refused. # Return Value On success, these functions return 0. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The input is not valid JSON, the input contains trailing content after the parsed value (only for non-`_continue` variants), or a top-level type constraint specified via `SD_JSON_PARSE_MUST_BE_OBJECT` or `SD_JSON_PARSE_MUST_BE_ARRAY` was violated. `-ENODATA` The input string is empty or `NULL`. `-ENOMEM` Memory allocation failed. # History `sd_json_parse()`, `sd_json_parse_continue()`, `sd_json_parse_with_source()`, `sd_json_parse_with_source_continue()`, `sd_json_parse_file()`, and `sd_json_parse_file_at()` were added in version 257. `sd_json_parse_fd()` and the `SD_JSON_PARSE_MUST_BE_OBJECT`, `SD_JSON_PARSE_MUST_BE_ARRAY`, `SD_JSON_PARSE_SEEK0`, `SD_JSON_PARSE_DONATE_FD` and `SD_JSON_PARSE_REOPEN_FD` flags were added in version 261. # See Also `systemd(1)`, `sd-json(3)`, `sd_json_variant_unref(3)`, `sd_json_variant_get_source(3)`, `sd_json_dispatch(3)` # sd_listen_fds systemd sd_listen_fds 3 sd_listen_fds sd_listen_fds_with_names SD_LISTEN_FDS_START Check for file descriptors passed by the system manager \#include \ \#define SD_LISTEN_FDS_START 3 int sd_listen_fds int unset_environment int sd_listen_fds_with_names int unset_environment char\*\*\* names # Description `sd_listen_fds()` may be invoked by a daemon to check for file descriptors passed by the service manager as part of the socket-based activation and file descriptor store logic. It returns the number of received file descriptors. If no file descriptors have been received, zero is returned. The first file descriptor may be found at file descriptor number 3 (i.e. `SD_LISTEN_FDS_START`), the remaining descriptors follow at 4, 5, 6, …, if any. The file descriptors passed this way may be closed at will by the processes receiving them: it is up to the processes themselves to close them after use or whether to leave them open until the process exits (in which case the kernel closes them automatically). Note that the file descriptors received by daemons are duplicates of the file descriptors the service manager originally allocated and bound and of which it continuously keeps a copy (except if `Accept=yes` is used). This means any socket option changes and other changes made to the sockets will be visible to the service manager too. Most importantly this means it is generally not a good idea to invoke `shutdown(2)` on such sockets, since it will shut down communication on the file descriptor the service manager holds for the same socket too. Also note that if a daemon is restarted (and its associated sockets are not) it will receive file descriptors to the very same sockets as the earlier invocations, thus all socket options applied then will still apply. If a daemon receives more than one file descriptor, they will be passed in the same order as configured in the systemd socket unit file (see `systemd.socket(5)` for details) — if there's only one such file (see below). Nonetheless, it is recommended to verify the correct socket types before using them. To simplify this checking, the functions `sd_is_fifo(3)`, `sd_is_socket(3)`, `sd_is_socket_inet(3)`, `sd_is_socket_unix(3)` are provided. In order to maximize flexibility, it is recommended to make these checks as loose as possible without allowing incorrect setups. i.e. often, the actual port number a socket is bound to matters little for the service to work, hence it should not be verified. On the other hand, whether a socket is a datagram or stream socket matters a lot for the most common program logics and should be checked. This function call will set the `FD_CLOEXEC` flag for all passed file descriptors to avoid further inheritance to children of the calling process. If multiple socket units activate the same service, the order of the file descriptors passed to its main process is undefined. If additional file descriptors have been passed to the service manager using `sd_pid_notify_with_fds(3)`'s `FDSTORE=1` messages, these file descriptors are passed last, in arbitrary order, and with duplicates removed. If the `unset_environment` parameter is non-zero, `sd_listen_fds()` will unset the `$LISTEN_FDS`, `$LISTEN_PID`, `$LISTEN_PIDFDID`, and `$LISTEN_FDNAMES` environment variables before returning (regardless of whether the function call itself succeeded or not). Further calls to `sd_listen_fds()` will then return zero, but the variables are no longer inherited by child processes. `sd_listen_fds_with_names()` is like `sd_listen_fds()`, but optionally also returns an array of strings with identification names for the passed file descriptors, if that is available and the `names` parameter is non-`NULL`. This information is read from the `$LISTEN_FDNAMES` variable, which may contain a colon-separated list of names. For socket-activated services, these names may be configured with the `FileDescriptorName=` setting in socket unit files, see `systemd.socket(5)` for details. For file descriptors pushed into the file descriptor store (see above), the name is set via the `FDNAME=` field transmitted via `sd_pid_notify_with_fds()`. The primary use case for these names are services which accept a variety of file descriptors which are not recognizable with functions like `sd_is_socket()` alone, and thus require identification via a name. It is recommended to rely on named file descriptors only if identification via `sd_is_socket()` and related calls is not sufficient. Note that the names used are not unique in any way. The returned array of strings has as many entries as file descriptors have been received, plus a final `NULL` pointer terminating the array. The caller needs to free the array itself and each of its elements with libc's `free()` call after use. If the `names` parameter is `NULL`, the call is entirely equivalent to `sd_listen_fds()`. Under specific conditions, the following automatic file descriptor names are returned: | Name | Description | |----|----| | `unknown` | The process received no name for the specific file descriptor from the service manager. | | `stored` | The file descriptor originates in the service manager's per-service file descriptor store, and the `FDNAME=` field was absent when the file descriptor was submitted to the service manager. | | `connection` | The service was activated in per-connection style using `Accept=yes` in the socket unit file, and the file descriptor is the connection socket. | `Special names` For further information on the file descriptor store see the [File Descriptor Store](https://systemd.io/FILE_DESCRIPTOR_STORE) overview. # Return Value On failure, these calls returns a negative errno-style error code. If `$LISTEN_FDS`/`$LISTEN_PID` was not set, or one of those variables or `$LISTEN_PIDFDID` was not correctly set for this daemon, no file descriptors were received and 0 is returned. Otherwise, the number of file descriptors passed is returned. The application may find them starting with file descriptor SD_LISTEN_FDS_START, i.e. file descriptor 3. # Notes Internally, `sd_listen_fds()` checks whether the `$LISTEN_PID` environment variable equals the daemon PID. If not, it returns immediately. Since version 259, if the `$LISTEN_PIDFDID` environment variable is set, it also checks whether it matches the inode of this process' pidfd. If both of these checks pass, it parses the number passed in the `$LISTEN_FDS` environment variable, then sets the FD_CLOEXEC flag for the parsed number of file descriptors starting from SD_LISTEN_FDS_START. Finally, it returns the parsed number. `sd_listen_fds_with_names()` does the same but also parses `$LISTEN_FDNAMES` if set. These functions are not designed for services that specify `StandardInput=socket` as the `$LISTEN_FDS` variable is not set in their environment. # Environment `$LISTEN_PID`; `$LISTEN_PIDFDID`; `$LISTEN_FDS`; `$LISTEN_FDNAMES` Set by the service manager for supervised processes that use socket-based activation. This environment variable specifies the data `sd_listen_fds()` and `sd_listen_fds_with_names()` parses. See above for details. # History `sd_listen_fds_with_names()` was added in version 227. # See Also `systemd(1)`, `sd-daemon(3)`, `sd_is_fifo(3)`, `sd_is_socket(3)`, `sd_is_socket_inet(3)`, `sd_is_socket_unix(3)`, `sd_pid_notify_with_fds(3)`, `daemon(7)`, `systemd.service(5)`, `systemd.socket(5)` # sd_login_monitor_new systemd sd_login_monitor_new 3 sd_login_monitor_new sd_login_monitor_unref sd_login_monitor_unrefp sd_login_monitor_flush sd_login_monitor_get_fd sd_login_monitor_get_events sd_login_monitor_get_timeout sd_login_monitor Monitor login sessions, seats, users and virtual machines/containers \#include \ int sd_login_monitor_new const char \* category sd_login_monitor \*\* ret sd_login_monitor \* sd_login_monitor_unref sd_login_monitor \* m void sd_login_monitor_unrefp sd_login_monitor \*\* m int sd_login_monitor_flush sd_login_monitor \* m int sd_login_monitor_get_fd sd_login_monitor \* m int sd_login_monitor_get_events sd_login_monitor \* m int sd_login_monitor_get_timeout sd_login_monitor \* m uint64_t \* timeout_usec # Description `sd_login_monitor_new()` may be used to monitor login sessions, users, seats, and virtual machines/containers. Via a monitor object a file descriptor can be integrated into an application defined event loop which is woken up each time a user logs in, logs out or a seat is added or removed, or a session, user, seat or virtual machine/container changes state otherwise. The first parameter takes a string which can be `seat` (to get only notifications about seats being added, removed or changed), `session` (to get only notifications about sessions being created or removed or changed), `uid` (to get only notifications when a user changes state in respect to logins) or `machine` (to get only notifications when a virtual machine or container is started or stopped). If notifications shall be generated in all these conditions, `NULL` may be passed. Note that in the future additional categories may be defined. The second parameter returns a monitor object and needs to be freed with the `sd_login_monitor_unref()` call after use. `sd_login_monitor_unref()` may be used to destroy a monitor object. Note that this will invalidate any file descriptor returned by `sd_login_monitor_get_fd()`. `sd_login_monitor_unrefp()` is similar to `sd_login_monitor_unref()` but takes a pointer to a pointer to an `sd_login_monitor` object. This call is useful in conjunction with GCC's and LLVM's [Clean-up Variable Attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html). Note that this function is defined as inline function. Use a declaration like the following, in order to allocate a login monitor object that is freed automatically as the code block is left: { __attribute__((cleanup(sd_login_monitor_unrefp))) sd_login_monitor *m = NULL; int r; … r = sd_login_monitor_new(NULL, &m); if (r < 0) { errno = -r; fprintf(stderr, "Failed to allocate login monitor object: %m\n"); } … } `sd_login_monitor_flush()` may be used to reset the wakeup state of the monitor object. Whenever an event causes the monitor to wake up the event loop via the file descriptor this function needs to be called to reset the wake-up state. If this call is not invoked, the file descriptor will immediately wake up the event loop again. `sd_login_monitor_unref()` and `sd_login_monitor_unrefp()` execute no operation if the passed in monitor object is `NULL`. `sd_login_monitor_get_fd()` may be used to retrieve the file descriptor of the monitor object that may be integrated in an application defined event loop, based around `poll(2)` or a similar interface. The application should include the returned file descriptor as wake-up source for the events mask returned by `sd_login_monitor_get_events()`. It should pass a timeout value as returned by `sd_login_monitor_get_timeout()`. Whenever a wake-up is triggered the file descriptor needs to be reset via `sd_login_monitor_flush()`. An application needs to reread the login state with a function like `sd_get_seats(3)` or similar to determine what changed. `sd_login_monitor_get_events()` will return the `poll()` mask to wait for. This function will return a combination of `POLLIN`, `POLLOUT` and similar to fill into the `.events` field of `struct pollfd`. `sd_login_monitor_get_timeout()` will return a timeout value for usage in `poll()`. This returns a value in microseconds since the epoch of `CLOCK_MONOTONIC` for timing out `poll()` in `timeout_usec`. See `clock_gettime(2)` for details about `CLOCK_MONOTONIC`. If there is no timeout to wait for this will fill in `(uint64_t) -1` instead. Note that `poll()` takes a relative timeout in milliseconds rather than an absolute timeout in microseconds. To convert the absolute 'μs' timeout into relative 'ms', use code like the following: uint64_t t; int msec; sd_login_monitor_get_timeout(m, &t); if (t == (uint64_t) -1) msec = -1; else { struct timespec ts; uint64_t n; clock_gettime(CLOCK_MONOTONIC, &ts); n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; msec = t > n ? (int) ((t - n + 999) / 1000) : 0; } The code above does not do any error checking for brevity's sake. The calculated `msec` integer can be passed directly as `poll()`'s timeout parameter. # Return Value On success, `sd_login_monitor_new()`, `sd_login_monitor_flush()` and `sd_login_monitor_get_timeout()` return 0 or a positive integer. On success, `sd_login_monitor_get_fd()` returns a Unix file descriptor. On success, `sd_login_monitor_get_events()` returns a combination of `POLLIN`, `POLLOUT` and suchlike. On failure, these calls return a negative errno-style error code. `sd_login_monitor_unref()` always returns `NULL`. ## Errors Returned errors may indicate the following problems: `-EINVAL` An input parameter was invalid (out of range, or `NULL`, where that is not accepted). The specified category to watch is not known. `-ENOMEM` Memory allocation failed. # History `sd_login_monitor_get_events()` and `sd_login_monitor_get_timeout()` were added in version 201. `sd_login_monitor_unrefp()` was added in version 229. # See Also `systemd(1)`, `sd-login(3)`, `sd_get_seats(3)`, `poll(2)`, `clock_gettime(2)` # sd_machine_get_class systemd sd_machine_get_class 3 sd_machine_get_class sd_machine_get_ifindices Determine the class and network interface indices of a locally running virtual machine or container \#include \ int sd_machine_get_class const char\* machine char \*\* class int sd_machine_get_ifindices const char\* machine int \*\* ret_ifindices # Description `sd_machine_get_class()` may be used to determine the class of a locally running virtual machine or container that is registered with `systemd-machined.service(8)`. The string returned is either `vm` or `container`. The returned string needs to be freed with the libc `free(3)` call after use. `sd_machine_get_ifindices()` may be used to determine the numeric indices of the network interfaces on the host that are pointing towards the specified locally running virtual machine or container. The vm or container must be registered with `systemd-machined.service(8)`. The output parameter `ret_ifindices` may be passed as `NULL` when the output value is not needed. The returned array needs to be freed with the libc `free(3)` call after use. # Return Value On success, these functions return a non-negative integer. `sd_machine_get_ifindices()` returns the number of the relevant network interfaces. On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENXIO` The specified machine does not exist or is currently not running. `-EINVAL` An input parameter was invalid (out of range, or `NULL`, where that is not accepted). `-ENOMEM` Memory allocation failed. # History `sd_machine_get_class()` and `sd_machine_get_ifindices()` were added in version 217. # See Also `systemd(1)`, `sd-login(3)`, `systemd-machined.service(8)`, `sd_pid_get_machine_name(3)` # sd_notify systemd sd_notify 3 sd_notify sd_notifyf sd_pid_notify sd_pid_notifyf sd_pid_notify_with_fds sd_pid_notifyf_with_fds sd_notify_barrier sd_pid_notify_barrier Notify service manager about start-up completion and other service status changes \#include \ int sd_notify int unset_environment const char \* state int sd_notifyf int unset_environment const char \* format … int sd_pid_notify pid_t pid int unset_environment const char \* state int sd_pid_notifyf pid_t pid int unset_environment const char \* format … int sd_pid_notify_with_fds pid_t pid int unset_environment const char \* state const int \* fds unsigned n_fds int sd_pid_notifyf_with_fds pid_t pid int unset_environment const int \* fds size_t n_fds const char \* format … int sd_notify_barrier int unset_environment uint64_t timeout int sd_pid_notify_barrier pid_t pid int unset_environment uint64_t timeout # Description `sd_notify()` may be called by a service to notify the service manager about state changes. It can be used to send arbitrary information, encoded in an environment-block-like string. Most importantly, it can be used for start-up or reload completion notifications. If the `unset_environment` parameter is non-zero, `sd_notify()` will unset the `$NOTIFY_SOCKET` environment variable before returning (regardless of whether the function call itself succeeded or not). Further calls to `sd_notify()` will then silently do nothing, and the variable is no longer inherited by child processes. The `state` parameter should contain a newline-separated list of variable assignments, similar in style to an environment block. A trailing newline is implied if none is specified. The string may contain any kind of variable assignments, but see the next section for a list of assignments understood by the service manager. Note that systemd will accept status data sent from a service only if the `NotifyAccess=` option is correctly set in the service definition file. See `systemd.service(5)` for details. Note that `sd_notify()` notifications may be attributed to units correctly only if either the sending process is still around at the time PID 1 processes the message, or if the sending process is explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked off the process, i.e. on all processes that match `NotifyAccess=``main` or `NotifyAccess=``exec`. Conversely, if an auxiliary process of the unit sends an `sd_notify()` message and immediately exits, the service manager might not be able to properly attribute the message to the unit, and thus will ignore it, even if `NotifyAccess=``all` is set for it. Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications to units correctly, `sd_notify_barrier()` may be used. This call acts as a synchronization point and ensures all notifications sent before this call have been picked up by the service manager when it returns successfully. Use of `sd_notify_barrier()` is needed for clients which are not invoked by the service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the unit. `sd_notifyf()` is similar to `sd_notify()` but takes a `printf()`-like format string plus arguments. `sd_pid_notify()` and `sd_pid_notifyf()` are similar to `sd_notify()` and `sd_notifyf()` but take a process ID (PID) to use as originating PID for the message as first argument. This is useful to send notification messages on behalf of other processes, provided the appropriate privileges are available. Effectively, this means that a privileged invocation of `sd_pid_notify()` may circumvent `NotifyAccess=main` or `NotifyAccess=exec` restrictions enforced for a service. If the PID argument is specified as 0, the process ID of the calling process is used, in which case the calls are fully equivalent to `sd_notify()` and `sd_notifyf()`. `sd_pid_notify_with_fds()` is similar to `sd_pid_notify()` but takes an additional array of file descriptors. These file descriptors are sent along the notification message to the service manager. This is particularly useful for sending `FDSTORE=1` messages, as described above. The additional arguments are a pointer to the file descriptor array plus the number of file descriptors in the array. If the number of file descriptors is passed as 0, the call is fully equivalent to `sd_pid_notify()`, i.e. no file descriptors are passed. Note that file descriptors sent to the service manager on a message without `FDSTORE=1` are immediately closed on reception. `sd_pid_notifyf_with_fds()` is a combination of `sd_pid_notify_with_fds()` and `sd_notifyf()`, i.e. it accepts both a PID and a set of file descriptors as input, and processes a format string to generate the state string. `sd_notify_barrier()` allows the caller to synchronize against reception of previously sent notification messages and uses the `BARRIER=1` command. It takes a relative `timeout` value in microseconds which is passed to `ppoll(2)`. A value of UINT64_MAX is interpreted as infinite timeout. `sd_pid_notify_barrier()` is just like `sd_notify_barrier()`, but allows specifying the originating PID for the notification message. # Well-known assignments The following assignments have a defined meaning: READY=1 Tells the service manager that service startup is finished, or the service finished re-loading its configuration. This is only used by systemd if the service definition file has `Type=notify` or `Type=notify-reload` set. Since there is little value in signaling non-readiness, the only value services should send is `READY=1` (i.e. `READY=0` is not defined). RELOADING=1 Tells the service manager that the service is beginning to reload its configuration. This is useful to allow the service manager to track the service's internal state, and present it to the user. Note that a service that sends this notification must also send a `READY=1` notification when it completed reloading its configuration. Reloads the service manager is notified about with this mechanisms are propagated in the same way as they are when originally initiated through the service manager. This message is particularly relevant for `Type=notify-reload` services, to inform the service manager that the request to reload the service has been received and is now being processed. STOPPING=1 Tells the service manager that the service is beginning its shutdown. This is useful to allow the service manager to track the service's internal state, and present it to the user. Starting with version 259, transitioning to the STOPPING state is final and cannot be undone with another notification. If after sending `STOPPING=1` the service doesn't terminate within the stop timeout, all remaining processes in the unit will be killed. MONOTONIC_USEC=… A field carrying the monotonic timestamp (as per `CLOCK_MONOTONIC`) formatted in decimal in μs, when the notification message was generated by the client. This is typically used in combination with `RELOADING=1`, to allow the service manager to properly synchronize reload cycles. See `systemd.service(5)` for details, specifically `Type=notify-reload`. STATUS=… Passes a single-line UTF-8 status string back to the service manager that describes the service state. This is free-form and can be used for various purposes: general state feedback, fsck-like programs could pass completion percentages and failing programs could pass a human-readable error message. Example: `STATUS=Completed 66% of file system check…` NOTIFYACCESS=… Reset the access to the service status notification socket during runtime, overriding `NotifyAccess=` setting in the service unit file. See `systemd.service(5)` for details, specifically `NotifyAccess=` for a list of accepted values. ERRNO=… If a service fails, the errno-style error code, formatted as string. Example: `ERRNO=2` for ENOENT. BUSERROR=… If a service fails, the D-Bus error-style error code. Example: `BUSERROR=org.freedesktop.DBus.Error.TimedOut`. VARLINKERROR=… If a service fails, the Varlink error-style error code. Example: `VARLINKERROR=org.varlink.service.InvalidParameter`. EXIT_STATUS=… The exit status of a service or the manager itself. Note that `systemd` currently does not consume this value when sent by services, so this assignment is only informational. The manager will send this notification to *its* notification socket, which may be used to collect an exit status from the system (a container or VM) as it shuts down. For example, `mkosi(1)` makes use of this. The value to return may be set via the `systemctl(1)` `exit` verb. MAINPID=… Change the main process ID (PID) of the service. This is especially useful in the case where the real main process is not directly forked off by the service manager. Example: `MAINPID=4711`. MAINPIDFDID=… The pidfd inode number of the new main process (specified through `MAINPID=`). This information can be acquired through `sd_pidfd_get_inode_id(3)` on the pidfd and is used to identify the process in a race-free fashion. Alternatively, a pidfd can be sent directly to the service manager (see `MAINPIDFD=1` below). MAINPIDFD=1 Similar to `MAINPID=` with `MAINPIDFDID=`, but the process is referenced directly by the pidfd passed to the service manager. This is useful if pidfd id is not supported on the system. Exactly one fd is expected for this notification. WATCHDOG=1 Tells the service manager to update the watchdog timestamp. This is the keep-alive ping that services need to issue in regular intervals if `WatchdogSec=` is enabled for it. See `systemd.service(5)` for information how to enable this functionality and `sd_watchdog_enabled(3)` for the details of how the service can check whether the watchdog is enabled. WATCHDOG=trigger Tells the service manager that the service detected an internal error that should be handled by the configured watchdog options. This will trigger the same behaviour as if `WatchdogSec=` is enabled and the service did not send `WATCHDOG=1` in time. Note that `WatchdogSec=` does not need to be enabled for `WATCHDOG=trigger` to trigger the watchdog action. See `systemd.service(5)` for information about the watchdog behavior. WATCHDOG_USEC=… Reset `watchdog_usec` value during runtime. Notice that this is not available when using `sd_event_set_watchdog()` or `sd_watchdog_enabled()`. Example : `WATCHDOG_USEC=20000000` EXTEND_TIMEOUT_USEC=… Tells the service manager to extend the startup, runtime or shutdown service timeout corresponding the current state. The value specified is a time in microseconds during which the service must send a new message. A service timeout will occur if the message is not received, but only if the runtime of the current state is beyond the original maximum times of `TimeoutStartSec=`, `RuntimeMaxSec=`, and `TimeoutStopSec=`. See `systemd.service(5)` for effects on the service timeouts. RESTART_RESET=1 Reset the restart counter of the service, which has the effect of restoring the restart duration to `RestartSec=` if `RestartSteps=` and `RestartMaxDelaySec=` are in use. For more information, refer to `systemd.service(5)`. FDSTORE=1 Store file descriptors in the service manager. File descriptors sent this way will be held for the service by the service manager and will later be handed back using the usual file descriptor passing logic at the next start or restart of the service, see `sd_listen_fds(3)`. Any open sockets and other file descriptors which should not be closed during a restart may be stored this way. When a service is stopped, its file descriptor store is discarded and all file descriptors in it are closed, except when overridden with `FileDescriptorStorePreserve=`, see `systemd.service(5)`. The service manager will accept messages for a service only if its `FileDescriptorStoreMax=` setting is non-zero (defaults to zero, see `systemd.service(5)`). The service manager will set the `$FDSTORE` environment variable for services that have the file descriptor store enabled, see `systemd.exec(5)`. If `FDPOLL=0` is not set and the file descriptors are pollable (see `epoll_ctl(2)`), then any `EPOLLHUP` or `EPOLLERR` event seen on them will result in their automatic removal from the store. Multiple sets of file descriptors may be sent in separate messages, in which case the sets are combined. The service manager removes duplicate file descriptors (those pointing to the same object) before passing them to the service. This functionality should be used to implement services that can restart after an explicit request or a crash without losing state. Application state can either be serialized to a file in `/run/`, or better, stored in a `memfd_create(2)` memory file descriptor. Use `sd_pid_notify_with_fds()` to send messages with `FDSTORE=1`. It is recommended to combine `FDSTORE=` with `FDNAME=` to make it easier to manage the stored file descriptors. For further information on the file descriptor store see the [File Descriptor Store](https://systemd.io/FILE_DESCRIPTOR_STORE) overview. On kernels that support the [Live Update Orchestrator](https://docs.kernel.org/userspace-api/liveupdate.html), compatible file descriptors stored this way (such as `memfd_create(2)`) are additionally preserved across `kexec`-based reboots and handed back to the service on the other side, provided `FileDescriptorStorePreserve=yes` is set on the service (see `systemd.service(5)`). See the [File Descriptor Store](https://systemd.io/FILE_DESCRIPTOR_STORE) overview for details. FDSTOREREMOVE=1 Removes file descriptors from the file descriptor store. This field needs to be combined with `FDNAME=` to specify the name of the file descriptors to remove. FDNAME=… When used in combination with `FDSTORE=1`, specifies a name for the submitted file descriptors. When used with `FDSTOREREMOVE=1`, specifies the name for the file descriptors to remove. This name is passed to the service during activation, and may be queried using `sd_listen_fds_with_names(3)`. File descriptors submitted without this field will be called `stored`. The name may consist of arbitrary ASCII characters except control characters or `:`. It may not be longer than 255 characters. If a submitted name does not follow these restrictions, it is ignored. Note that if multiple file descriptors are submitted in a single message, the specified name will be used for all of them. In order to assign different names to submitted file descriptors, submit them in separate messages. FDPOLL=0 When used in combination with `FDSTORE=1`, disables polling of the submitted file descriptors regardless of whether or not they are pollable. As this option disables automatic cleanup of the submitted file descriptors on EPOLLERR and EPOLLHUP, care must be taken to ensure proper manual cleanup. Use of this option is not generally recommended except for when automatic cleanup has unwanted behavior such as prematurely discarding file descriptors from the store. BARRIER=1 Tells the service manager that the client is explicitly requesting synchronization by means of closing the file descriptor sent with this command. The service manager guarantees that the processing of a `BARRIER=1` command will only happen after all previous notification messages sent before this command have been processed. Hence, this command accompanied with a single file descriptor can be used to synchronize against reception of all previous status messages. Note that this command cannot be mixed with other notifications, and has to be sent in a separate message to the service manager, otherwise all assignments will be ignored. Note that sending 0 or more than 1 file descriptor with this command is a violation of the protocol. The notification messages sent by services are interpreted by the service manager. Unknown assignments are ignored. Thus, it is safe (but often without effect) to send assignments which are not in this list. The protocol is extensible, but care should be taken to ensure private extensions are recognizable as such. Specifically, it is recommend to prefix them with `X_` followed by some namespace identifier. The service manager also sends some messages to *its* notification socket, which may then consumed by a supervising machine or container manager further up the stack. The service manager sends a number of extension fields, for example `X_SYSTEMD_UNIT_ACTIVE=`, for details see `systemd(1)`. # Return Value On failure, these calls return a negative errno-style error code. If `$NOTIFY_SOCKET` was not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a positive value. In order to support both service managers that implement this scheme and those which do not, it is generally recommended to ignore the return value of this call. Note that the return value simply indicates whether the notification message was enqueued properly, it does not reflect whether the message could be processed successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using `FDSTORE=1` but the service is not actually configured to permit storing of file descriptors (see above). ## Errors Returned errors may indicate the following problems: `-E2BIG` More file descriptors passed at once than the system allows. On Linux the number of file descriptors that may be passed across `AF_UNIX` sockets at once is 253, see `unix(7)` for details. # Notes These functions send a single datagram with the state string as payload to the socket referenced in the `$NOTIFY_SOCKET` environment variable. If the first character of `$NOTIFY_SOCKET` is `/` or `@`, the string is understood as an `AF_UNIX` or Linux abstract namespace socket (respectively), and in both cases the datagram is accompanied by the process credentials of the sending service, using SCM_CREDENTIALS. If the string starts with `vsock:` then the string is understood as an `AF_VSOCK` address, which is useful for hypervisors/VMMs or other processes on the host to receive a notification when a virtual machine has finished booting. Note that in case the hypervisor does not support `SOCK_DGRAM` over `AF_VSOCK`, `SOCK_SEQPACKET` will be used instead. `vsock-stream`, `vsock-dgram` and `vsock-seqpacket` can be used instead of `vsock` to force usage of the corresponding socket type. The address should be in the form: `vsock:CID:PORT`. Note that unlike other uses of vsock, the CID is mandatory and cannot be `VMADDR_CID_ANY`. Note that PID1 will send the VSOCK packets from a privileged port (i.e.: lower than 1024), as an attempt to address concerns that unprivileged processes in the guest might try to send malicious notifications to the host, driving it to make destructive decisions based on them. ## Standalone Implementations Note that, while using this library should be preferred in order to avoid code duplication, it is also possible to reimplement the simple readiness notification protocol without external dependencies, as demonstrated in the following self-contained examples from several languages: ### C ### Python # Environment `$NOTIFY_SOCKET` Set by the service manager for supervised processes for status and start-up completion notification. This environment variable specifies the socket `sd_notify()` talks to. See above for details. # Examples
Start-up Notification
When a service finished starting up, it might issue the following call to notify the service manager: sd_notify(0, "READY=1");
Extended Start-up Notification
A service could send the following after completing initialization: sd_notifyf(0, "READY=1\n" "STATUS=Processing requests…\n" "MAINPID=%lu", (unsigned long) getpid());
Error Cause Notification
A service could send the following shortly before exiting, on failure: sd_notifyf(0, "STATUS=Failed to start up: %s\n" "ERRNO=%i", strerror_r(errnum, (char[1024]){}, 1024), errnum);
Store a File Descriptor in the Service Manager
To store an open file descriptor in the service manager, in order to continue operation after a service restart without losing state, use `FDSTORE=1`: sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);
Eliminating race conditions
When the client sending the notifications is not spawned by the service manager, it may exit too quickly and the service manager may fail to attribute them correctly to the unit. To prevent such races, use `sd_notify_barrier()` to synchronize against reception of all notifications sent before this call is made. sd_notify(0, "READY=1"); /* set timeout to 5 seconds */ sd_notify_barrier(0, 5 * 1000000);
# History `sd_pid_notify()`, `sd_pid_notifyf()`, and `sd_pid_notify_with_fds()` were added in version 219. `sd_notify_barrier()` was added in version 246. `sd_pid_notifyf_with_fds()` and `sd_pid_notify_barrier()` were added in version 254. # See Also `systemd(1)`, `sd-daemon(3)`, `sd_listen_fds(3)`, `sd_listen_fds_with_names(3)`, `sd_watchdog_enabled(3)`, `daemon(7)`, `systemd.service(5)` # sd_path_lookup systemd sd_path_lookup 3 sd_path_lookup sd_path_lookup_strv Query well-known file system paths \#include \ enum { SD_PATH_TEMPORARY , SD_PATH_TEMPORARY_LARGE , SD_PATH_SYSTEM_BINARIES , SD_PATH_SYSTEM_INCLUDE , SD_PATH_SYSTEM_LIBRARY_PRIVATE , SD_PATH_SYSTEM_LIBRARY_ARCH , SD_PATH_SYSTEM_SHARED , SD_PATH_SYSTEM_CONFIGURATION_FACTORY , SD_PATH_SYSTEM_STATE_FACTORY , SD_PATH_SYSTEM_CONFIGURATION , SD_PATH_SYSTEM_SEARCH_CONFIGURATION , SD_PATH_SYSTEM_RUNTIME , SD_PATH_SYSTEM_RUNTIME_LOGS , SD_PATH_SYSTEM_STATE_PRIVATE , SD_PATH_SYSTEM_STATE_LOGS , SD_PATH_SYSTEM_STATE_CACHE , SD_PATH_SYSTEM_STATE_SPOOL , SD_PATH_USER_BINARIES , SD_PATH_USER_LIBRARY_PRIVATE , SD_PATH_USER_LIBRARY_ARCH , SD_PATH_USER_SHARED , SD_PATH_USER_CONFIGURATION , SD_PATH_USER_RUNTIME , SD_PATH_USER_STATE_PRIVATE , SD_PATH_USER_STATE_CACHE , SD_PATH_USER , SD_PATH_USER_DOCUMENTS , SD_PATH_USER_MUSIC , SD_PATH_USER_PICTURES , SD_PATH_USER_VIDEOS , SD_PATH_USER_DOWNLOAD , SD_PATH_USER_PUBLIC , SD_PATH_USER_TEMPLATES , SD_PATH_USER_DESKTOP , SD_PATH_USER_PROJECTS , SD_PATH_SEARCH_BINARIES , SD_PATH_SEARCH_BINARIES_DEFAULT , SD_PATH_SEARCH_LIBRARY_PRIVATE , SD_PATH_SEARCH_LIBRARY_ARCH , SD_PATH_SEARCH_SHARED , SD_PATH_SEARCH_CONFIGURATION_FACTORY , SD_PATH_SEARCH_STATE_FACTORY , SD_PATH_SEARCH_CONFIGURATION , SD_PATH_SYSTEMD_UTIL , SD_PATH_SYSTEMD_SYSTEM_UNIT , SD_PATH_SYSTEMD_SYSTEM_PRESET , SD_PATH_SYSTEMD_USER_UNIT , SD_PATH_SYSTEMD_USER_PRESET , SD_PATH_SYSTEMD_SYSTEM_CONF , SD_PATH_SYSTEMD_USER_CONF , SD_PATH_SYSTEMD_SEARCH_SYSTEM_UNIT , SD_PATH_SYSTEMD_SEARCH_USER_UNIT , SD_PATH_SYSTEMD_SYSTEM_GENERATOR , SD_PATH_SYSTEMD_USER_GENERATOR , SD_PATH_SYSTEMD_SEARCH_SYSTEM_GENERATOR , SD_PATH_SYSTEMD_SEARCH_USER_GENERATOR , SD_PATH_SYSTEMD_SLEEP , SD_PATH_SYSTEMD_SHUTDOWN , SD_PATH_TMPFILES , SD_PATH_SYSUSERS , SD_PATH_SYSCTL , SD_PATH_BINFMT , SD_PATH_MODULES_LOAD , SD_PATH_CATALOG , SD_PATH_SYSTEMD_SEARCH_NETWORK , SD_PATH_SYSTEMD_SYSTEM_ENVIRONMENT_GENERATOR , SD_PATH_SYSTEMD_USER_ENVIRONMENT_GENERATOR , SD_PATH_SYSTEMD_SEARCH_SYSTEM_ENVIRONMENT_GENERATOR , SD_PATH_SYSTEMD_SEARCH_USER_ENVIRONMENT_GENERATOR , }; int sd_path_lookup uint64_t type const char \* suffix char \*\* paths int sd_path_lookup_strv uint64_t type const char \* suffix char \*\*\* paths # Description `sd_path_lookup()` and `sd_bus_path_lookup_strv()` return a single path or set of file system paths specified by the argument `type`. In case of `sd_path_lookup()` a single `NUL`-terminated string is returned. When `type` specifies a set of paths, they are concatenated using `:` as a separator (as is traditionally done for e.g. `$PATH` or `$LD_LIBRARY_PATH`). In case of `sd_path_lookup_strv()` a `NULL`-terminated array of strings is returned (strv). If suffix `suffix` is given, it is concatenated to each of the paths after a slash (`/`). All returned paths are absolute. For paths which refer to user directories, the relevant XDG standard is followed, with support for environment variables like `$XDG_DOCUMENTS_DIR`, `$XDG_DESKTOP_DIR`, ..., and explicit configuration in `/etc/xdg/user-dirs.conf` or `${XDG_CONFIG_HOME}/user-dirs.dirs`. See [ XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) for details. `systemd-path(1)` is a wrapper around `sd_path_lookup()` and allows the same set of paths to be queried. # Return Value On success, `sd_path_lookup()` and `sd_path_lookup_strv()` return a non-negative integer. On failure, a negative errno-style error number is returned by either function. The returned string or string array (strv) must be `free(3)`'d by the caller. ## Errors Returned errors may indicate the following problems: `-EOPNOTSUPP` Unknown identifier `type`. `-EINVAL` Output argument is `NULL`. `-ENXIO` Query failed because of an undefined environment variable (e.g. for `SD_PATH_USER_RUNTIME` when `$XDG_RUNTIME_DIR` is not defined). `-ENOMEM` Memory allocation failed. # Examples ## Look up the location of ~/Documents Note that the default answer of `$HOME/Documents` may be overridden by `user-dirs.conf` or `$XDG_DOCUMENTS_DIR`. # History `sd_path_lookup()` and `sd_path_lookup_strv()` were added in version 246. # See Also `systemd(1)`, `sd-path(3)`, `systemd-path(1)` # sd_pid_get_owner_uid systemd sd_pid_get_owner_uid 3 sd_pid_get_owner_uid sd_pid_get_session sd_pid_get_user_unit sd_pid_get_unit sd_pid_get_machine_name sd_pid_get_slice sd_pid_get_user_slice sd_pid_get_cgroup sd_pidfd_get_owner_uid sd_pidfd_get_session sd_pidfd_get_user_unit sd_pidfd_get_unit sd_pidfd_get_machine_name sd_pidfd_get_slice sd_pidfd_get_user_slice sd_pidfd_get_cgroup sd_peer_get_owner_uid sd_peer_get_session sd_peer_get_user_unit sd_peer_get_unit sd_peer_get_machine_name sd_peer_get_slice sd_peer_get_user_slice sd_peer_get_cgroup Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to \#include \ int sd_pid_get_owner_uid pid_t pid uid_t \* uid int sd_pid_get_session pid_t pid char \*\* session int sd_pid_get_user_unit pid_t pid char \*\* unit int sd_pid_get_unit pid_t pid char \*\* unit int sd_pid_get_machine_name pid_t pid char \*\* name int sd_pid_get_slice pid_t pid char \*\* slice int sd_pid_get_user_slice pid_t pid char \*\* slice int sd_pid_get_cgroup pid_t pid char \*\* cgroup int sd_pidfd_get_owner_uid int pidfd uid_t \* uid int sd_pidfd_get_session int pidfd char \*\* session int sd_pidfd_get_user_unit int pidfd char \*\* unit int sd_pidfd_get_unit int pidfd char \*\* unit int sd_pidfd_get_machine_name int pidfd char \*\* name int sd_pidfd_get_slice int pidfd char \*\* slice int sd_pidfd_get_user_slice int pidfd char \*\* slice int sd_pidfd_get_cgroup int pidfd char \*\* cgroup int sd_peer_get_owner_uid int fd uid_t \* uid int sd_peer_get_session int fd char \*\* session int sd_peer_get_user_unit int fd char \*\* unit int sd_peer_get_unit int fd char \*\* unit int sd_peer_get_machine_name int fd char \*\* name int sd_peer_get_slice int fd char \*\* slice int sd_peer_get_user_slice int fd char \*\* slice int sd_peer_get_cgroup int fd char \*\* cgroup # Description `sd_pid_get_owner_uid()` may be used to determine the Unix UID (user identifier) which owns the login session or systemd user unit of a process identified by the specified PID. For processes which are not part of a login session and not managed by a user manager, this function will fail with `-ENODATA`. `sd_pid_get_session()` may be used to determine the login session identifier of a process identified by the specified process identifier. The session identifier is a short string, suitable for usage in file system paths. Please note the login session may be limited to a stub process or two. User processes may instead be started from their systemd user manager, e.g. GUI applications started using DBus activation, as well as service processes which are shared between multiple logins of the same user. For processes which are not part of a login session, this function will fail with `-ENODATA`. The returned string needs to be freed with the libc `free(3)` call after use. `sd_pid_get_user_unit()` may be used to determine the systemd user unit (i.e. user service or scope unit) identifier of a process identified by the specified PID. The unit name is a short string, suitable for usage in file system paths. For processes which are not managed by a user manager, this function will fail with `-ENODATA`. The returned string needs to be freed with the libc `free(3)` call after use. `sd_pid_get_unit()` may be used to determine the systemd system unit (i.e. system service or scope unit) identifier of a process identified by the specified PID. The unit name is a short string, suitable for usage in file system paths. Note that not all processes are part of a system unit/service. For processes not being part of a systemd system unit, this function will fail with `-ENODATA`. (More specifically, this call will not work for kernel threads.) The returned string needs to be freed with the libc `free(3)` call after use. `sd_pid_get_machine_name()` may be used to determine the name of the VM or container is a member of. The machine name is a short string, suitable for usage in file system paths. The returned string needs to be freed with the libc `free(3)` call after use. For processes not part of a VM or container, this function fails with `-ENODATA`. `sd_pid_get_slice()` may be used to determine the slice unit the process is a member of. See `systemd.slice(5)` for details about slices. The returned string needs to be freed with the libc `free(3)` call after use. Similarly, `sd_pid_get_user_slice()` returns the user slice (as managed by the user's systemd instance) of a process. `sd_pid_get_cgroup()` returns the control group path of the specified process, relative to the root of the hierarchy. Returns the path without trailing slash, except for processes located in the root control group, where "/" is returned. To find the actual control group path in the file system, the returned path needs to be prefixed with `/sys/fs/cgroup/`. If the `pid` parameter of any of these functions is passed as 0, the operation is executed for the calling process. The `sd_pidfd_get_owner_uid()`, `sd_pidfd_get_session()`, `sd_pidfd_get_user_unit()`, `sd_pidfd_get_unit()`, `sd_pidfd_get_machine_name()`, `sd_pidfd_get_slice()`, `sd_pidfd_get_user_slice()` and `sd_pidfd_get_cgroup()` calls operate similarly to their PID counterparts, but accept a `PIDFD` instead of a `PID`, which means they are not subject to recycle race conditions as the process is pinned by the file descriptor during the whole duration of the invocation. Note that these require a kernel that supports `PIDFD`. A suitable file descriptor may be acquired via `pidfd_open(2)`. The `sd_peer_get_owner_uid()`, `sd_peer_get_session()`, `sd_peer_get_user_unit()`, `sd_peer_get_unit()`, `sd_peer_get_machine_name()`, `sd_peer_get_slice()`, `sd_peer_get_user_slice()` and `sd_peer_get_cgroup()` calls operate similarly to their PID counterparts, but accept a connected `AF_UNIX` socket and retrieve information about the connected peer process. Note that these fields are retrieved via `/proc/`, and hence are not suitable for authorization purposes, as they are subject to races. # Return Value On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ESRCH` The specified PID does not refer to a running process. `-EBADF` The specified file descriptor is invalid. `-ENODATA` The given field is not specified for the described process or peer. `-EINVAL` An input parameter was invalid (out of range, or `NULL`, where that is not accepted). `-ENOMEM` Memory allocation failed. # Notes Note that the login session identifier as returned by `sd_pid_get_session()` is completely unrelated to the process session identifier as returned by `getsid(2)`. # History `sd_peer_get_cgroup()`, `sd_peer_get_machine_name()`, `sd_peer_get_owner_uid()`, `sd_peer_get_session()`, `sd_peer_get_slice()`, `sd_peer_get_unit()`, `sd_peer_get_user_slice()`, `sd_peer_get_user_unit()`, `sd_pid_get_cgroup()`, `sd_pid_get_machine_name()`, `sd_pid_get_owner_uid()`, `sd_pid_get_session()`, `sd_pid_get_slice()`, `sd_pid_get_unit()`, `sd_pid_get_user_slice()`, and `sd_pid_get_user_unit()` were added in version 236. `sd_pidfd_get_owner_uid()`, `sd_pidfd_get_session()`, `sd_pidfd_get_user_unit()`, `sd_pidfd_get_unit()`, `sd_pidfd_get_machine_name()`, `sd_pidfd_get_slice()`, `sd_pidfd_get_user_slice()`, and `sd_pidfd_get_cgroup()` were added in version 253. # See Also `systemd(1)`, `sd-login(3)`, `sd_session_is_active(3)`, `getsid(2)`, `systemd.slice(5)`, `systemd-machined.service(8)` # sd_pidfd_get_inode_id systemd sd_pidfd_get_inode_id 3 sd_pidfd_get_inode_id Acquire the 64-bit inode ID of a PID file descriptor (PIDFD) \#include \ int sd_pidfd_get_inode_id int pidfd uint64_t \* ret # Description `sd_pidfd_get_inode_id()` may be invoked to acquire the 64-bit inode ID of a PID file descriptor (PIDFD), which can be used to reliably identify a process for the current boot. As a typical example, the service manager sets `$MAINPIDFDID` and `$MANAGERPIDFDID` environment variables to the inode IDs of the service main process and the service manager itself, respectively, if such functionality is supported by the kernel. On 64-bit architectures, the inode ID can be directly obtained via a call to `fstat(2)` on a given pidfd. However, on 32-bit architectures struct stat's .st_ino field is also 32-bit, which similar to PIDs is subject to reuse. Therefore, a second mechanism leveraging `name_to_handle_at(2)` has been added to kernel in v6.14. This helper is added to simplify downstream handling of pidfd/pidfs internals. # Return Value On success, the function returns 0 or a positive integer. On failure, a negative errno-style error code is returned. ## Errors Returned errors may indicate the following problems: `-EOPNOTSUPP` The stable PIDFD inode ID is not supported by the running kernel, or the system is 32-bit and `name_to_handle_at()` is unavailable. `-EBADF` The specified file descriptor is invalid, or is not a PIDFD. # Notes # History `sd_pidfd_get_inode_id()` was added in version 258. # See Also `systemd(1)`, `sd-daemon(3)`, `sd_notify(3)`, `systemd.exec(5)` # sd_seat_get_active systemd sd_seat_get_active 3 sd_seat_get_active sd_seat_get_sessions sd_seat_can_tty sd_seat_can_graphical Determine state of a specific seat \#include \ int sd_seat_get_active const char \* seat char \*\* session uid_t \* uid int sd_seat_get_sessions const char \* seat char \*\*\* ret_sessions uid_t \*\* ret_uids unsigned int \* ret_n_uids int sd_seat_can_tty const char \* seat int sd_seat_can_graphical const char \* seat # Description `sd_seat_get_active()` may be used to determine which session is currently active on a seat, if there is any. Returns the session identifier and the user identifier of the Unix user the session is belonging to. Either the session or the user identifier parameter can be passed `NULL`, in case only one of the parameters shall be queried. The returned string needs to be freed with the libc `free(3)` call after use. `sd_seat_get_sessions()` may be used to determine all sessions on the specified seat. Returns two arrays, one (`NULL` terminated) with the session identifiers of the sessions and one with the user identifiers of the Unix users the sessions belong to. An additional parameter may be used to return the number of entries in the latter array. This value is the same as the return value if the return value is nonnegative. The output parameters may be passed as `NULL` in case these output values are not needed. The arrays and the strings referenced by them need to be freed with the libc `free(3)` call after use. Note that instead of an empty array `NULL` may be returned and should be considered equivalent to an empty array. `sd_seat_can_tty()` may be used to determine whether a specific seat provides TTY functionality, i.e. is useful as a text console. `sd_seat_can_graphical()` may be used to determine whether a specific seat provides graphics functionality, i.e. is useful as a graphics display. If the `seat` parameter of any of these functions is passed as `NULL`, the operation is executed for the seat of the session of the calling process, if there is any. # Return Value On success, `sd_seat_get_active()` returns 0 or a positive integer. On success, `sd_seat_get_sessions()` returns the number of entries in the session identifier array. If the test succeeds, `sd_seat_can_tty()` and `sd_seat_can_graphical()` return a positive integer, if it fails 0. On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENODATA` The given field is not specified for the described seat. `-ENXIO` The specified seat is unknown. `-EINVAL` An input parameter was invalid (out of range, or `NULL`, where that is not accepted). `-ENOMEM` Memory allocation failed. # History `sd_seat_can_tty()` and `sd_seat_can_graphical()` were added in version 186. # See Also `systemd(1)`, `sd-login(3)`, `sd_session_get_seat(3)` # sd_session_is_active systemd sd_session_is_active 3 sd_session_is_active sd_session_is_remote sd_session_get_state sd_session_get_uid sd_session_get_username sd_session_get_seat sd_session_get_start_time sd_session_get_service sd_session_get_type sd_session_get_class sd_session_get_desktop sd_session_get_display sd_session_get_tty sd_session_get_vt sd_session_get_remote_host sd_session_get_remote_user sd_session_get_leader sd_session_get_extra_device_access Determine state of a specific session \#include \ int sd_session_is_active const char \* session int sd_session_is_remote const char \* session int sd_session_get_state const char \* session char \*\* state int sd_session_get_uid const char \* session uid_t \* uid int sd_session_get_username const char \* session char \*\* username int sd_session_get_seat const char \* session char \*\* seat int sd_session_get_start_time const char \* session uint64_t \* usec int sd_session_get_service const char \* session char \*\* service int sd_session_get_type const char \* session char \*\* type int sd_session_get_class const char \* session char \*\* class int sd_session_get_desktop const char \* session char \*\* desktop int sd_session_get_display const char \* session char \*\* display int sd_session_get_leader const char \* session pid_t \* leader int sd_session_get_remote_host const char \* session char \*\* remote_host int sd_session_get_remote_user const char \* session char \*\* remote_user int sd_session_get_tty const char \* session char \*\* tty int sd_session_get_vt const char \* session unsigned int \* vt int sd_session_get_extra_device_access const char \* session char \*\*\* ret_ids # Description `sd_session_is_active()` may be used to determine whether the session identified by the specified session identifier is currently active (i.e. currently in the foreground and available for user input) or not. `sd_session_is_remote()` may be used to determine whether the session identified by the specified session identifier is a remote session (i.e. its remote host is known) or not. `sd_session_get_state()` may be used to determine the state of the session identified by the specified session identifier. The following states are currently known: `online` (session logged in, but session not active, i.e. not in the foreground), `active` (session logged in and active, i.e. in the foreground), `closing` (session nominally logged out, but some processes belonging to it are still around). In the future additional states might be defined, client code should be written to be robust in regards to additional state strings being returned. This function is a more generic version of `sd_session_is_active()`. The returned string needs to be freed with the libc `free(3)` call after use. `sd_session_get_uid()` may be used to determine the user identifier of the Unix user the session identified by the specified session identifier belongs to. `sd_session_get_username()` may be used to determine the name of the Unix user the session identified by the specified session identifier belongs to. The returned string needs to be freed with the libc `free(3)` call after use. `sd_session_get_seat()` may be used to determine the seat identifier of the seat the session identified by the specified session identifier belongs to. Note that not all sessions are attached to a seat, this call will fail (returning `-ENODATA`) for them. The returned string needs to be freed with the libc `free(3)` call after use. `sd_session_get_start_time()` may be used to determine the start time of the session identified by the specified session identifier belongs to. The `usec` is in microseconds since the epoch (`CLOCK_REALTIME`). `sd_session_get_service()` may be used to determine the name of the service (as passed during PAM session setup) that registered the session identified by the specified session identifier. The returned string needs to be freed with the libc `free(3)` call after use. `sd_session_get_type()` may be used to determine the type of the session identified by the specified session identifier. The returned string is one of `x11`, `wayland`, `tty`, `mir` or `unspecified` and needs to be freed with the libc `free(3)` call after use. `sd_session_get_class()` may be used to determine the class of the session identified by the specified session identifier. The returned string is one of `user`, `user-early`, `user-light`, `user-early-light`, `user-incomplete`, `greeter`, `lock-screen`, `background`, `background-light`, `manager` or `manager-early` and needs to be freed with the libc `free(3)` call after use. `sd_session_get_desktop()` may be used to determine the brand of the desktop running on the session identified by the specified session identifier. This field can be set freely by desktop environments and does not follow any special formatting. However, desktops are strongly recommended to use the same identifiers and capitalization as for `$XDG_CURRENT_DESKTOP`, as defined by the [Desktop Entry Specification](https://standards.freedesktop.org/desktop-entry-spec/latest/). The returned string needs to be freed with the libc `free(3)` call after use. `sd_session_get_display()` may be used to determine the X11 display of the session identified by the specified session identifier. The returned string needs to be freed with the libc `free(3)` call after use. `sd_session_get_leader()` may be used to determine the PID of the leader of the session identified by the specified session identifier. `sd_session_get_remote_host()` may be used to determine the remote hostname of the session identified by the specified session identifier. The returned string needs to be freed with the libc `free(3)` call after use. `sd_session_get_remote_user()` may be used to determine the remote username of the session identified by the specified session identifier. The returned string needs to be freed with the libc `free(3)` call after use. Note that this value is rarely known to the system, and even then should not be relied on. `sd_session_get_tty()` may be used to determine the TTY device of the session identified by the specified session identifier. The returned string needs to be freed with the libc `free(3)` call after use. `sd_session_get_vt()` may be used to determine the VT number of the session identified by the specified session identifier. This function will return an error if the seat does not support VTs. `sd_session_get_extra_device_access()` may be used to determine which additional hardware devices the session is granted access to. For every `ID` in the list, the session is granted access to all devices tagged with `xaccess-ID` in udev. If the `session` parameter of any of these functions is passed as `NULL`, the operation is executed for the session the calling process is a member of, if there is any. # Return Value If the test succeeds, `sd_session_is_active()` and `sd_session_is_remote()` return a positive integer; if it fails, 0. On success, `sd_session_get_state()`, `sd_session_get_uid()`, `sd_session_get_username()`, `sd_session_get_seat()`, `sd_session_get_service()`, `sd_session_get_type()`, `sd_session_get_class()`, `sd_session_get_display()`, `sd_session_get_leader()`, `sd_session_get_remote_user()`, `sd_session_get_remote_host()`, `sd_session_get_tty()`, and `sd_session_get_extra_device_access()` return 0 or a positive integer. On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENXIO` The specified session does not exist. `-ENODATA` The given field is not specified for the described session. `-EINVAL` An input parameter was invalid (out of range, or `NULL`, where that is not accepted). `-ENOMEM` Memory allocation failed. # History `sd_session_get_state()` was added in version 186. `sd_session_get_tty()` was added in version 198. `sd_session_get_vt()` was added in version 207. `sd_session_is_remote()`, `sd_session_get_remote_host()`, and `sd_session_get_remote_user()` were added in version 209. `sd_session_get_desktop()` was added in version 217. `sd_session_get_username()`, `sd_session_get_start_time()`, and `sd_session_get_leader()` were added in version 254. `sd_session_get_extra_device_access()` was added in version 260. # See Also `systemd(1)`, `sd-login(3)`, `sd_pid_get_session(3)` # sd_uid_get_state systemd sd_uid_get_state 3 sd_uid_get_state sd_uid_is_on_seat sd_uid_get_sessions sd_uid_get_seats sd_uid_get_display sd_uid_get_login_time Determine login state of a specific Unix user ID \#include \ int sd_uid_get_state uid_t uid char \*\* state int sd_uid_is_on_seat uid_t uid int require_active const char \* seat int sd_uid_get_sessions uid_t uid int require_active char \*\*\* sessions int sd_uid_get_seats uid_t uid int require_active char \*\*\* seats int sd_uid_get_display uid_t uid char \*\* session int sd_uid_get_login_time uid_t uid uint64_t \* usec # Description `sd_uid_get_state()` may be used to determine the login state of a specific Unix user identifier. The following states are currently known: `offline` (user not logged in at all), `lingering` (user not logged in, but some user services running), `online` (user logged in, but not active, i.e. has no session in the foreground), `active` (user logged in, and has at least one active session, i.e. one session in the foreground), `closing` (user not logged in, and not lingering, but some processes are still around). In the future additional states might be defined, client code should be written to be robust in regards to additional state strings being returned. The returned string needs to be freed with the libc `free(3)` call after use. `sd_uid_is_on_seat()` may be used to determine whether a specific user is logged in or active on a specific seat. Accepts a Unix user identifier and a seat identifier string as parameters. The `require_active` parameter is a boolean value. If non-zero (true), this function will test if the user is active (i.e. has a session that is in the foreground and accepting user input) on the specified seat, otherwise (false) only if the user is logged in (and possibly inactive) on the specified seat. `sd_uid_get_sessions()` may be used to determine the current sessions of the specified user. Accepts a Unix user identifier as parameter. The `require_active` parameter controls whether the returned list shall consist of only those sessions where the user is currently active (\> 0), where the user is currently online but possibly inactive (= 0), or logged in but possibly closing the session (\< 0). The call returns a `NULL` terminated string array of session identifiers in `sessions` which needs to be freed by the caller with the libc `free(3)` call after use, including all the strings referenced. If the string array parameter is passed as `NULL`, the array will not be filled in, but the return code still indicates the number of current sessions. Note that instead of an empty array `NULL` may be returned and should be considered equivalent to an empty array. Similarly, `sd_uid_get_seats()` may be used to determine the list of seats on which the user currently has sessions. Similar semantics apply, however note that the user may have multiple sessions on the same seat as well as sessions with no attached seat and hence the number of entries in the returned array may differ from the one returned by `sd_uid_get_sessions()`. `sd_uid_get_display()` returns the name of the "primary" session of a user. If the user has graphical sessions, it will be the oldest graphical session. Otherwise, it will be the oldest open session. `sd_uid_get_login_time()` may be used to determine the time the user's service manager has been invoked, which is the time when the user's first active session, since which they stayed logged in continuously, began. The `usec` is in microseconds since the epoch (`CLOCK_REALTIME`). This call will fail with `-ENXIO` if the user is not currently logged in. # Return Value On success, `sd_uid_get_state()` and `sd_uid_get_login_time()` returns 0 or a positive integer. If the test succeeds, `sd_uid_is_on_seat()` returns a positive integer; if it fails, 0. `sd_uid_get_sessions()` and `sd_uid_get_seats()` return the number of entries in the returned arrays. `sd_uid_get_display()` returns a non-negative code on success. On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-ENODATA` The given field is not specified for the described user. `-ENXIO` The specified seat is unknown. `-EINVAL` An input parameter was invalid (out of range, or `NULL`, where that is not accepted). This is also returned if the passed user ID is `0xFFFF` or `0xFFFFFFFF`, which are undefined on Linux. `-ENOMEM` Memory allocation failed. # History `sd_uid_get_display()` was added in version 213. `sd_uid_get_login_time()` was added in version 254. # See Also `systemd(1)`, `sd-login(3)`, `sd_pid_get_owner_uid(3)` # sd_varlink_call_and_upgrade systemd sd_varlink_call_and_upgrade 3 sd_varlink_call_and_upgrade sd_varlink_call_and_upgradeb sd_varlink_call_and_upgradebo sd_varlink_invoke_and_upgrade sd_varlink_invoke_and_upgradeb sd_varlink_invoke_and_upgradebo Invoke a Varlink method and take over the connection for a raw protocol \#include \ int sd_varlink_call_and_upgrade sd_varlink \* link const char \* method sd_json_variant \* parameters sd_json_variant \*\* ret_parameters const char \*\* ret_error_id int \* ret_input_fd int \* ret_output_fd int sd_varlink_call_and_upgradeb sd_varlink \* link const char \* method sd_json_variant \*\* ret_parameters const char \*\* ret_error_id int \* ret_input_fd int \* ret_output_fd … int sd_varlink_call_and_upgradebo sd_varlink \* link const char \* method sd_json_variant \*\* ret_parameters const char \*\* ret_error_id int \* ret_input_fd int \* ret_output_fd … int sd_varlink_invoke_and_upgrade sd_varlink \* link const char \* method sd_json_variant \* parameters int sd_varlink_invoke_and_upgradeb sd_varlink \* link const char \* method … int sd_varlink_invoke_and_upgradebo sd_varlink \* link const char \* method … # Description These functions implement the client side of a Varlink *protocol upgrade*. They are the counterpart of the server-side `sd_varlink_reply_and_upgrade(3)` family. If a method call is issued this way, the connection may switch, after the reply, from the Varlink protocol to an arbitrary, non-Varlink ("raw") protocol spoken over the underlying socket or pipe file descriptors, in a manner similar to the `Upgrade:` mechanism of HTTP. `sd_varlink_call_and_upgrade()` synchronously invokes the method `method` on the connection `link`, requesting a protocol upgrade, and waits for the reply. It takes the Varlink connection object, the method name, a JSON object with the method call parameters (which may be `NULL`), two output pointers for the reply parameters and a possible error identifier, and two output pointers for the file descriptors. The reply parameters returned in `ret_parameters` and the error identifier returned in `ret_error_id` are borrowed references that remain valid only until the connection is closed or unreffed. Either of the two may be passed as `NULL` if the information is not needed. If the server replies with a regular reply (rather than a Varlink error) the connection is upgraded: it is disconnected from the Varlink protocol, and ownership of the underlying file descriptors is transferred to the caller via `ret_input_fd` and `ret_output_fd`, which is responsible for eventually closing them with `close(2)`. If the server replies with a Varlink error instead, the connection is *not* upgraded and no file descriptors are returned; the error identifier is reported in `ret_error_id` (if non-`NULL`), otherwise a negative errno-style error derived from it is returned. The returned file descriptors are switched to blocking mode. For bidirectional sockets a single underlying file descriptor carries both directions; in this case `ret_input_fd` and `ret_output_fd` are returned as two independent (duplicated) descriptors referring to the same socket, so they may be closed separately. For transports backed by a pair of pipes the two descriptors differ and refer to the distinct read and write ends. At least one of `ret_input_fd` or `ret_output_fd` must be non-`NULL`. `sd_varlink_call_and_upgradeb()` is similar to `sd_varlink_call_and_upgrade()`, but instead of expecting a fully constructed `sd_json_variant` object carrying the method call parameters, this object is constructed on-the-fly from the variadic argument list, in a style identical to `sd_json_build(3)`. `sd_varlink_call_and_upgradebo()` is identical to `sd_varlink_call_and_upgradeb()`, but an enclosing JSON object is added implicitly, so that the argument list is expected to consist of object field pairs only, in a style identical to `sd_json_buildo(3)`. This relationship mirrors that of `sd_varlink_call(3)` and its `sd_varlink_callb()`/`sd_varlink_callbo()` variants. `sd_varlink_invoke_and_upgrade()` is the asynchronous counterpart of `sd_varlink_call_and_upgrade()`, for connections attached to an event loop with `sd_varlink_attach_event(3)`. It enqueues the method call with the upgrade request and returns immediately. Once the reply arrives it is passed to the reply callback installed with `sd_varlink_bind_reply(3)`. If the server replied with a Varlink error, the connection stays in the Varlink protocol and may be used further. Otherwise the connection is upgraded on the next dispatch after the reply callback returned (i.e. the next invocation of `sd_varlink_process()`, typically by the event loop): it is detached from the event loop, disconnected from the Varlink protocol, and the underlying file descriptors are passed to the upgrade callback installed with `sd_varlink_bind_upgrade(3)`, with the same semantics as the descriptors returned by `sd_varlink_call_and_upgrade()`. The callback takes ownership of both descriptors. Unlike with regular method calls, no further method calls may be enqueued on the connection while an upgrade request is pending, since the connection leaves the Varlink protocol once the request has been answered. `sd_varlink_invoke_and_upgradeb()` and `sd_varlink_invoke_and_upgradebo()` relate to `sd_varlink_invoke_and_upgrade()` like the `…b()` and `…bo()` variants described above. # Return Value On success, `sd_varlink_call_and_upgrade()` and its variants return a positive integer if the connection was upgraded. If the server returns a Varlink error and `ret_error_id` was provided by the caller, it is set to the error identifier and zero is returned. Otherwise, the Varlink error is treated as a failure. `sd_varlink_invoke_and_upgrade()` and its variants return zero once the request has been enqueued. On failure, all functions return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. `-ENOTCONN` The Varlink connection object is not connected. `-EBUSY` Another method call is pending on the connection. Note that while a request enqueued with `sd_varlink_invoke_and_upgrade()` is pending, this error is also returned by any other function that enqueues a method call on the connection, such as `sd_varlink_call(3)` or `sd_varlink_invoke()`. `-EPROTO` A protocol error occurred, for example the server sent unexpected raw protocol data before the upgrade completed. `-ENOMEM` Memory allocation failed. # History `sd_varlink_call_and_upgrade()` was added in version 261. `sd_varlink_call_and_upgradeb()` and `sd_varlink_call_and_upgradebo()` were added in version 262. `sd_varlink_invoke_and_upgrade()`, `sd_varlink_invoke_and_upgradeb()` and `sd_varlink_invoke_and_upgradebo()` were added in version 263. # See Also `systemd(1)`, `sd-varlink(3)`, `sd_varlink_call(3)`, `sd_varlink_reply_and_upgrade(3)`, `sd_json_build(3)` # sd_varlink_connect_address systemd sd_varlink_connect_address 3 sd_varlink_connect_address sd_varlink_connect_exec sd_varlink_connect_url sd_varlink_connect_fd sd_varlink_connect_fd_pair Create a Varlink connection object and connect it to a service \#include \ struct ucred; /\* defined in \ \*/ int sd_varlink_connect_address sd_varlink \*\* ret const char \* address int sd_varlink_connect_exec sd_varlink \*\* ret const char \* command char \*\* argv int sd_varlink_connect_url sd_varlink \*\* ret const char \* url int sd_varlink_connect_fd sd_varlink \*\* ret int fd int sd_varlink_connect_fd_pair sd_varlink \*\* ret int input_fd int output_fd const struct ucred \* override_ucred # Description These five functions allocate a new client-side Varlink connection object and connect it to a Varlink service. They differ only in how the service to talk to is specified. On success, a reference to the new connection object is returned in `ret`; the caller owns this reference and must eventually release it with `sd_varlink_unref(3)`, `sd_varlink_close_unref(3)` or `sd_varlink_flush_close_unref(3)`. All five functions return immediately; none of them blocks waiting for the connection to be fully established. For socket-based connections the actual `connect()` may still be in progress when the function returns (see below); the connection object handles the completion transparently. The returned connection object is not attached to any event loop. There are three ways to drive it: attach it to an `sd-event(3)` loop with `sd_varlink_attach_event(3)`; run its I/O manually via `sd_varlink_process(3)` and `sd_varlink_wait(3)`; or simply issue blocking method calls. In particular it is perfectly fine to follow any of these connection functions directly with a synchronous, blocking call such as `sd_varlink_call(3)`, which internally drives the connection (including completing a still-pending `connect()`) and returns once the reply has been received. In that case no explicit event loop integration or manual processing is required. `sd_varlink_connect_address()` connects to an `AF_UNIX` stream socket whose address is given as a string in `address`. The address must begin either with `/` (to reference a socket in the file system) or with `@` (to reference a socket in the abstract namespace, with the remainder of the string used as the abstract name). It must be at least two characters long. No other forms are accepted (in particular, relative paths are refused). Abstract namespace names that embed `NUL` bytes cannot be expressed through this interface. If a file system socket path is too long to fit into a sockaddr_un structure, the connection is established transparently via an `O_PATH` indirection, so overlong paths work. `sd_varlink_connect_exec()` forks off a child process and speaks the Varlink protocol with it over a connected `AF_UNIX` `SOCK_STREAM` socket pair. `command` is the program to execute; it is looked up in `$PATH` in the usual way (i.e. via `execvp(3)`). `argv` is the argument vector (a `NULL`-terminated string array) to pass to the child as its `argv[]`; if it is `NULL` or empty, an argument vector consisting of just `command` is synthesized. The connected socket is handed to the child as file descriptor 3 using the `sd_listen_fds(3)` protocol, i.e. the child is invoked with `$LISTEN_FDS` set to `1`, `$LISTEN_FDNAMES` set to `varlink`, and the appropriate `$LISTEN_PID` (and, where available, `$LISTEN_PIDFDID`) variables. The `command` and `argv` strings are copied into the connection object, so the caller may free or modify them once the function returns. `sd_varlink_connect_url()` is a higher-level interface that parses a service address string with a leading scheme and dispatches to the appropriate transport. Despite the name, these strings are *not* Internet URLs in the sense of the relevant RFCs. The following schemes are understood natively: `unix:`\ Connects to an `AF_UNIX` socket, equivalent to passing \ to `sd_varlink_connect_address()`. \ must either be an absolute, normalized file system path, or begin with `@` for an abstract namespace socket (for which no path normalization checks are applied). `exec:`\ Forks off the executable at \, equivalent to passing it to `sd_varlink_connect_exec()` with no extra arguments. \ must be an absolute, normalized path. `ssh:`\`:`\; `ssh-unix:`\`:`\ Connects to an `AF_UNIX` socket at the absolute, normalized path \ on the remote SSH host \. This relies on OpenSSH 9.4 or newer on the server side. Abstract namespace sockets are not supported for this transport. `ssh:` and `ssh-unix:` are synonyms. `ssh-exec:`\`:`\ Invokes \ (a command line, split on whitespace with shell-style quoting and unescaping) on the remote SSH host \ and speaks the Varlink protocol over its standard input and output. If the scheme is none of the above but is otherwise a syntactically valid URL scheme, `sd_varlink_connect_url()` looks for a *bridge helper* binary of that name in the directory configured via `$SYSTEMD_VARLINK_BRIDGES_DIR` (see below). If found and executable, it is invoked like an `exec:` transport, with the complete, unmodified URL passed as its sole command line argument. This allows additional transports to be plugged in out of tree. For the natively supported schemes, URL parameterization using `;`, `?` or `#` is rejected (these are reserved for possible future use). A `vsock:` scheme is not currently supported. `sd_varlink_connect_fd()` turns an already existing, already connected file descriptor `fd` into a Varlink connection. The descriptor is used for both reading and writing. It may refer to a connected stream socket, but also to a pipe or other bidirectional file descriptor. `sd_varlink_connect_fd_pair()` is like `sd_varlink_connect_fd()`, but accepts a separate `input_fd` (used for reading from the peer) and `output_fd` (used for writing to the peer). This is useful when the two directions are backed by different descriptors, for example a pair of pipes, or the standard output and standard input of a co-process. The two descriptors may also be identical, which is exactly what `sd_varlink_connect_fd()` does internally. If `override_ucred` is non-`NULL`, the peer credentials reported for the connection (as returned e.g. by `sd_varlink_get_peer_uid(3)`) are taken from the supplied ucred structure instead of being queried from the socket via `SO_PEERCRED`. This is primarily useful when the descriptors are not sockets (and hence carry no kernel-supplied peer credentials), or when the credentials need to be overridden for other reasons. If `override_ucred` is `NULL`, peer credentials are determined from the socket as usual. `sd_varlink_connect_fd()` and `sd_varlink_connect_fd_pair()` take over ownership of the descriptors passed to them: the descriptors are closed automatically when the connection object is freed, and the caller must not close them itself. On failure ownership remains with the caller. The connection objects created by `sd_varlink_connect_exec()`, and by the `exec:`, `ssh:`/`ssh-unix:`, `ssh-exec:` and bridge-helper paths of `sd_varlink_connect_url()`, are bound to the lifetime of the spawned child process. When such a connection object is freed, the associated child process is sent `SIGTERM` and reaped. The child is also configured to receive `SIGTERM` if the calling process dies. # Return Value On success, these functions return a non-negative integer and store a pointer to the new connection object in `ret`. On failure, they return a negative errno-style error code and leave `ret` unchanged. ## Errors Returned errors may indicate the following problems: `-EINVAL` A required argument is `NULL`, or the supplied address, command, or URL is malformed. This includes addresses that do not begin with `/` or `@`, abstract namespace names that do not fit into a sockaddr_un structure, and — for `sd_varlink_connect_url()` — file system paths that are not absolute or not normalized. `-EBADF` For `sd_varlink_connect_fd()` and `sd_varlink_connect_fd_pair()`: a supplied file descriptor is negative. `-EPROTONOSUPPORT` For `sd_varlink_connect_url()`: the URL contains no `:` separator, uses an unsupported scheme for which no bridge helper binary is available, or makes use of the reserved `;`, `?` or `#` URL parameterization characters with a natively supported scheme. `-ENOMEM` Memory allocation failed. In addition, these functions may propagate any error returned by the underlying system calls they use, such as `socket(2)`, `connect(2)`, `fork(2)`, `pipe(2)` and the various execution helpers. # Environment `$SYSTEMD_SSH` Used by the `ssh:`/`ssh-unix:` and `ssh-exec:` transports of `sd_varlink_connect_url()` to override the `ssh` binary to invoke. May be a plain file name (looked up in `$PATH`) or an absolute path. `$SYSTEMD_VARLINK_BRIDGES_DIR` Overrides the directory in which `sd_varlink_connect_url()` looks up bridge helper binaries for non-native URL schemes. Defaults to `/usr/lib/systemd/varlink-bridges/`. # Files `/usr/lib/systemd/varlink-bridges/` Default directory searched for bridge helper binaries when `sd_varlink_connect_url()` encounters a URL with a scheme that is not natively supported. See `sd-varlink(3)` for details. # History `sd_varlink_connect_address()`, `sd_varlink_connect_exec()`, `sd_varlink_connect_url()`, `sd_varlink_connect_fd()` and `sd_varlink_connect_fd_pair()` were added in version 257. # See Also `systemd(1)`, `sd-varlink(3)`, `sd_varlink_attach_event(3)`, `sd_varlink_call(3)`, `sd_varlink_send(3)`, `sd_varlink_is_connected(3)`, `sd_listen_fds(3)`, `varlinkctl(1)` # sd_varlink_is_connected systemd sd_varlink_is_connected 3 sd_varlink_is_connected sd_varlink_is_idle Query if a Varlink connection object is currently connected or idle \#include \ int sd_varlink_is_connected sd_varlink \* link int sd_varlink_is_idle sd_varlink \* link # Description `sd_varlink_is_connected()` checks whether the specified Varlink connection object is currently connected or whether it has been fully disconnected already. `sd_varlink_is_idle()` checks whether the specified Varlink connection object is currently connected but idle, i.e. may accept a method call for enqueuing (if client side of a Varlink connection) or is waiting for more incoming method calls to arrive (if server side of a Varlink connection). # Return Value If the connection is currently connected `sd_varlink_is_connected()` returns a positive non-zero value. If disconnected it returns 0. If the connection currently is idle `sd_varlink_is_idle()` returns a positive non-zero integer. If not, returns 0. On failure, both functions return a negative `errno` error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` The specified Varlink connection is invalid. # History `sd_varlink_is_connected()` was added in version 259. `sd_varlink_is_idle()` was added in version 257. # See Also `systemd(1)`, `sd-varlink(3)` # sd_varlink_push_fd systemd sd_varlink_push_fd 3 sd_varlink_push_fd sd_varlink_push_dup_fd Submit a file descriptor to send along with the next outgoing Varlink message \#include \ int sd_varlink_push_fd sd_varlink \* link int fd int sd_varlink_push_dup_fd sd_varlink \* link int fd # Description `sd_varlink_push_fd()` submits a file descriptor to send along with the next outgoing Varlink message. Takes a Varlink connection object and a file descriptor as parameter. The file descriptor is not duplicated, and hence ownership of the file descriptor is passed to the Varlink connection object (only on success; on failure the caller retains ownership). Once the file descriptor has been written to the underlying transport socket it is automatically closed. The calling application code should not touch the file descriptor or close it on its own, otherwise it will interfere with the Varlink protocol implementation. This call is only supported if the backing transport supports file descriptor passing (effectively this means the functionality is supported on local `AF_UNIX` only), and the concept is not part of the Varlink protocol, but simply a feature of the underlying transport. `sd_varlink_push_dup_fd()` is identical to `sd_varlink_push_fd()`, except that the file descriptor is duplicated automatically, and the calling application code hence retains ownership of the provided file descriptor, and must close it on its own. Note that file descriptor passing is only permitted after a call to `sd_varlink_set_allow_fd_passing_output()` that enables it, otherwise these calls will fail with `-EPERM`. Note that on Linux a maximum of 253 file descriptors may be enqueued on `AF_UNIX` sockets at once. Attempting to enqueue more on a single Varlink message will fail with `-ENOBUFS`. # Return Value On success, `sd_varlink_push_fd()` and `sd_varlink_push_dup_fd()` return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. `-EBADF` The provided file descriptor is not valid. `-EPERM` File descriptor passing has not been enabled via `sd_varlink_set_allow_fd_passing_output()`. `-ENOBUFS` The maximum of 253 file descriptors have already been submitted for the next outgoing Varlink message, no further descriptors may be enqueued for this message. `-ENOMEM` Memory allocation failed. # History `sd_varlink_push_fd()` and `sd_varlink_push_dup_fd()` were added in version 257. # See Also `systemd(1)`, `sd-varlink(3)` # sd_varlink_reply_and_upgrade systemd sd_varlink_reply_and_upgrade 3 sd_varlink_reply_and_upgrade sd_varlink_respond_and_upgrade sd_varlink_respond_and_upgradeb sd_varlink_respond_and_upgradebo sd_varlink_bind_upgrade sd_varlink_upgrade_t Reply to a Varlink method call and take over the connection for a raw protocol \#include \ typedef int (\* sd_varlink_upgrade_t )(sd_varlink \* link , int input_fd , int output_fd , void \* userdata ); int sd_varlink_reply_and_upgrade sd_varlink \* link sd_json_variant \* parameters int \* ret_input_fd int \* ret_output_fd int sd_varlink_respond_and_upgrade sd_varlink \* link sd_json_variant \* parameters int sd_varlink_respond_and_upgradeb sd_varlink \* link … int sd_varlink_respond_and_upgradebo sd_varlink \* link … int sd_varlink_bind_upgrade sd_varlink \* link sd_varlink_upgrade_t callback # Description These functions implement the server side of a Varlink *protocol upgrade*. A Varlink client may request an upgrade when invoking a method (see `sd_varlink_call(3)` and the `SD_VARLINK_METHOD_UPGRADE` flag passed to method callbacks). If a method is invoked this way, the server may send one final reply and then abandon the Varlink protocol on the connection entirely, handing the underlying socket or pipe file descriptors back to the caller so that an arbitrary, non-Varlink ("raw") protocol may be spoken over them instead. This is useful for methods that negotiate a switch to a streaming or binary protocol, in a manner similar to the `Upgrade:` mechanism of HTTP. `sd_varlink_reply_and_upgrade()` sends a final reply to the currently processed method call and then takes over the connection's file descriptors *synchronously*. It takes the Varlink connection object, a JSON object with the reply parameters (which may be `NULL`), and two output pointers for the file descriptors. The `parameters` object is validated against the method's declared reply signature, if known. The reply is flushed to the connection before the file descriptors are returned, so that the client has received the full reply before the caller starts speaking the upgraded protocol. On success the connection is detached from its event loop (if any) and disconnected, and ownership of the file descriptors is transferred to the caller, which is responsible for eventually closing them with `close(2)`. The returned file descriptors are switched to blocking mode. For bidirectional sockets a single underlying file descriptor carries both directions; in this case `ret_input_fd` and `ret_output_fd` are returned as two independent (duplicated) descriptors referring to the same socket, so they may be closed separately. For transports backed by a pair of pipes the two descriptors differ and refer to the distinct read and write ends. Either `ret_input_fd` or `ret_output_fd` (but not both) may be `NULL`; in that case the unwanted direction is shut down (if they refer to the same socket, see `shutdown(2)`) or closed (if separate file descriptors) rather than returned. Note that `sd_varlink_reply_and_upgrade()` blocks synchronously until the reply has been flushed to the socket. A misbehaving or adversarial client that stops reading could stall the caller. It should hence not be used in servers that multiplex many Varlink connections in a single event loop, as one stalled connection would block progress on all others. Use `sd_varlink_respond_and_upgrade()` in that case instead. `sd_varlink_respond_and_upgrade()` is the *asynchronous* counterpart of `sd_varlink_reply_and_upgrade()`. It enqueues the final reply and returns immediately, without blocking and without returning the file descriptors directly. The reply is subsequently flushed by the event loop during regular `sd_varlink_process(3)` invocations. Once the reply has been fully flushed, the connection's file descriptors are handed to the upgrade callback previously registered with `sd_varlink_bind_upgrade()`, and the Varlink connection is disconnected. This variant is the right choice for servers that handle many connections concurrently, as it never blocks on a single client. `sd_varlink_respond_and_upgradeb()` is similar to `sd_varlink_respond_and_upgrade()`, but instead of expecting a fully constructed `sd_json_variant` object carrying the reply parameters, this object is constructed on-the-fly from the variadic argument list, in a style identical to `sd_json_build(3)`. `sd_varlink_respond_and_upgradebo()` is identical to `sd_varlink_respond_and_upgradeb()`, but an enclosing JSON object is added implicitly, so that the argument list is expected to consist of object field pairs only, in a style identical to `sd_json_buildo(3)`. `sd_varlink_bind_upgrade()` registers the upgrade `callback` that is invoked once a reply enqueued via `sd_varlink_respond_and_upgrade()` (or one of its variants) has been flushed to the connection. The callback is of type `sd_varlink_upgrade_t` and receives the Varlink connection object, the input and output file descriptors of the (now upgraded) connection, and the userdata pointer associated with the connection (see `sd_varlink_set_userdata(3)`). Ownership of the two file descriptors is transferred to the callback (regardless if the callback later fails or not). The descriptor semantics (blocking mode, duplication for bidirectional sockets, distinct ends for pipe pairs) match those described for `sd_varlink_reply_and_upgrade()` above. Passing `NULL` as `callback` removes a previously registered callback. # Return Value On success, `sd_varlink_reply_and_upgrade()`, `sd_varlink_respond_and_upgrade()`, `sd_varlink_respond_and_upgradeb()` and `sd_varlink_respond_and_upgradebo()` return a positive integer. `sd_varlink_bind_upgrade()` returns a non-negative integer on success. On failure, they all return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. `-ENOTCONN` The Varlink connection object is not connected. `-EBUSY` The connection is not currently processing a method call, so there is no reply to send. When returned by `sd_varlink_bind_upgrade()`, a different upgrade callback was already registered on the connection. `-EPROTO` The currently processed method call did not request a protocol upgrade, hence the connection may not be taken over. `-EBADMSG` The client sent unexpected data before the upgrade completed, i.e. it pipelined raw protocol data before receiving the upgrade reply. `-ENOMEM` Memory allocation failed. # History `sd_varlink_reply_and_upgrade()` was added in version 261. `sd_varlink_respond_and_upgrade()`, `sd_varlink_respond_and_upgradeb()`, `sd_varlink_respond_and_upgradebo()` and `sd_varlink_bind_upgrade()` were added in version 262. # See Also `systemd(1)`, `sd-varlink(3)`, `sd_varlink_reply(3)`, `sd_varlink_call(3)`, `sd_varlink_call_and_upgrade(3)`, `sd_varlink_process(3)`, `sd_varlink_set_userdata(3)`, `sd_json_build(3)` # sd_varlink_send systemd sd_varlink_send 3 sd_varlink_send sd_varlink_sendb sd_varlink_sendbo Enqueues a Varlink method call, not expecting a reply \#include \ int sd_varlink_send sd_varlink \* link const char \* method sd_json_variant \* parameters int sd_varlink_sendb sd_varlink \* link const char \* method … int sd_varlink_sendbo sd_varlink \* link const char \* method … # Description `sd_varlink_send()` submits a method call via a Varlink connection. It takes the Varlink connection object, a method name as string parameter, and a JSON object containing the parameters to pass as function parameters. This call is asynchronous: the message will not be delivered immediately but only once `sd_varlink_process(3)` is invoked (which will happen automatically in one of the following event loop iterations if the Varlink connection is attached to an even loop). `sd_varlink_sendb()` is similar to `sd_varlink_send()`, but instead of expecting a fully constructed `sd_json_variant` object carrying the parameters, this object is constructed on-the-fly directly from the parameter list, in a style identical to `sd_json_build(3)`. `sd_varlink_sendbo()` is identical to `sd_varlink_sendb()`, but an enclosing object is implicitly added, so that the parameter list is expected to consist of field pairs only. For details about the expected argument list, see `sd_json_buildo(3)`. Use `sd_varlink_send()`, `sd_varlink_sendb()` and `sd_varlink_sendbo()` only if no method call results are required, as they neither provide return parameters nor success/failure information. Use `sd_varlink_call(3)` (and related calls) to submit a method call synchronously, returning the server's response. # Return Value On success, `sd_varlink_send()`, `sd_varlink_sendb()` and `sd_varlink_sendbo()` return a non-negative integer. On failure, they return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. `-ENOMEM` Memory allocation failed. `-ENOTCONN` The Varlink connection object is not connected. `-EBUSY` The Varlink connection object is already used for other purposes, i.e. executing a method call or similar. `-ENOBUFS` The internal limit of queued messages for the Varlink connection has been reached. This limit is set very high, and hitting it typically indicates that the Varlink connection object is stalled — possibly because `sd_varlink_process()` has not been called regularly enough, or because the peer is not processing any queued messages. This limit is a safety precaution to ensure a stalled peer will not result in unbounded memory allocations on the client side. # History `sd_varlink_send()`, `sd_varlink_sendb()`, `sd_varlink_sendbo()` were added in version 257. # See Also `systemd(1)`, `sd-varlink(3)`, `sd_varlink_call(3)`, `sd_varlink_build(3)` # sd_varlink_server_listen_address systemd sd_varlink_server_listen_address 3 sd_varlink_server_listen_address sd_varlink_server_listen_fd sd_varlink_server_listen_name sd_varlink_server_listen_auto Bind a Varlink server object to listening sockets \#include \ \#define SD_VARLINK_SERVER_MODE_MKDIR_0755 … int sd_varlink_server_listen_address sd_varlink_server\* server const char\* address mode_t mode int sd_varlink_server_listen_fd sd_varlink_server\* server int fd int sd_varlink_server_listen_name sd_varlink_server\* server const char\* name int sd_varlink_server_listen_auto sd_varlink_server\* server # Description These functions add listening sockets to a Varlink server object, as previously allocated with `sd_varlink_server_new(3)`. Once the server object is attached to an event loop (see `sd_varlink_server_attach_event()`) it will accept incoming connections on the configured sockets and dispatch the registered method calls. `sd_varlink_server_listen_address()` allocates a new `AF_UNIX` socket, binds it to the specified `address`, and starts listening on it. The `address` is a file system path of the socket to bind to. (Use `sd_varlink_server_listen_fd()` below for sockets in the abstract namespace, in foreign address families, or that are otherwise already allocated.) The `mode` parameter specifies the file system access mode to apply to the socket inode, i.e. a bit mask of permission bits as in `chmod(2)`. Only the lower nine bits (`0777`) are permitted. The special value `(mode_t) -1` may be specified to pick a suitable default: this is `0666` in the general case, but `0644` if the server was allocated with the `SD_VARLINK_SERVER_ROOT_ONLY` or `SD_VARLINK_SERVER_MYSELF_ONLY` flags (the reason being that it is the `w` bit that controls `connect(2)` access, while leaving the `r` bit on permits other users to read the socket's extended attributes, which makes the socket recognizable as a Varlink entrypoint, see `sd-varlink(3)`). The constant `SD_VARLINK_SERVER_MODE_MKDIR_0755` may be OR-ed into the `mode` parameter (this is not supported if the mode is specified as `(mode_t) -1`). If specified, and `address` is an absolute path, the leading directories of the socket path are automatically created (with access mode `0755`) if they are missing. `sd_varlink_server_listen_fd()` adds an already allocated and listening socket to the server object, referenced by the file descriptor `fd`. This is typically used in conjunction with socket activation, to make use of a listening socket passed in from the service manager, see `sd_listen_fds(3)`. The file descriptor is automatically switched to non-blocking mode and the close-on-exec flag is set on it. `sd_varlink_server_listen_name()` picks up sockets passed in via the socket activation protocol whose name (as set via `$LISTEN_FDNAMES`, i.e. via the `FileDescriptorName=` setting of the `systemd.socket(5)` unit) matches the specified `name`. For each matching file descriptor that refers to a listening socket `sd_varlink_server_listen_fd()` is invoked; file descriptors that refer to an already accepted connection are added as connections via `sd_varlink_server_add_connection()` instead. `sd_varlink_server_listen_auto()` is a convenience wrapper that automatically determines the sockets to listen on. It first picks up all socket activation file descriptors named `varlink` (by calling `sd_varlink_server_listen_name()` with that name). In addition, if the `$SYSTEMD_VARLINK_LISTEN` environment variable is set, it is used as an additional address to listen on: if set to `-` the Varlink protocol is spoken on standard input and output (see `sd_varlink_server_add_connection_stdio()`), otherwise the value is passed to `sd_varlink_server_listen_address()`. This is the recommended way for a Varlink service to set up its listening sockets, as it transparently supports both socket activation and direct invocation (for testing and debugging). # Return Value On success, `sd_varlink_server_listen_address()` and `sd_varlink_server_listen_fd()` return a non-negative integer. `sd_varlink_server_listen_name()` and `sd_varlink_server_listen_auto()` return the number of sockets and file descriptors they added to the server object (which may be zero). On failure, these calls return a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. This is also returned by `sd_varlink_server_listen_address()` if the `mode` parameter contains bits other than the permission bits and `SD_VARLINK_SERVER_MODE_MKDIR_0755`. `-EBADF` The file descriptor passed to `sd_varlink_server_listen_fd()` is negative. # History `sd_varlink_server_listen_address()`, `sd_varlink_server_listen_fd()`, and `sd_varlink_server_listen_auto()` were added in version 257. `sd_varlink_server_listen_name()` was added in version 258. # See Also `systemd(1)`, `sd-varlink(3)`, `sd_varlink_server_new(3)`, `sd_listen_fds(3)`, `systemd.socket(5)`, `varlinkctl(1)` # sd_varlink_server_new systemd sd_varlink_server_new 3 sd_varlink_server_new Allocate Varlink server object \#include \ int sd_varlink_server_new sd_varlink_server\*\* ret sd_varlink_server_flags_t flags # Description `sd_varlink_server_new()` allocates a new Varlink server object. Initially the server does not listen on any socket or file descriptor. The newly allocated server object is returned in the `ret` parameter. Use `sd_varlink_server_unref()` to release the server object again after use. The following flags may be passed in the `flags` parameter: - `SD_VARLINK_SERVER_ROOT_ONLY`: only allow connections from UID 0 (i.e. the root user). This has two effects: any incoming connections is authenticated via `SO_PEERCRED` ensuring the UID reported by the kernel is zero. If this check fails the connection is immediately terminated. Moreover, when binding a socket inode in the file system, the access mode is set to 0600 (rather than 0666). If this option is used connections on non-`AF_UNIX` sockets or via pipes are never permitted. - `SD_VARLINK_SERVER_MYSELF_ONLY`: this is very similar to `SD_VARLINK_SERVER_ROOT_ONLY` but enforces that the connecting client's UID must match the server's UID (i.e. the UID this function is invoked as). For servers that run as UID 0 the flags are equivalent. If both flags are specified in combination, connections are allowed by both UID 0 and the server's own UID. - `SD_VARLINK_SERVER_ACCOUNT_UID`: if set connection accounting per client UID is enabled, and a limit on concurrent connections from the same UID is enforced. The limit can be set via `sd_varlink_server_set_connections_per_uid_max()`, and defaults to 3/4th of the total concurrent connection limit, as settable via `sd_varlink_server_set_connections_max()`. - `SD_VARLINK_SERVER_INHERIT_USERDATA`: if set the user data field for incoming connection (i.e. `sd_varlink`) objects (as settable via `sd_varlink_set_userdata()`) is automatically set to the userdata field of the server (i.e. `sd_varlink_server`) object (as settable via `sd_varlink_server_set_userdata()`). If this flag is not specified the connection's user data field will default to `NULL`. - `SD_VARLINK_SERVER_INPUT_SENSITIVE`: mark all incoming method call parameters as security sensitive (equivalent to calling `sd_json_variant_sensitive()`). This is useful for services that deal with secrets and similar, as it ensures that the parameters are kept out of debug logging, and memory used by the parameters is erased after use. - `SD_VARLINK_SERVER_ALLOW_FD_PASSING_INPUT`: if set, allow receiving UNIX file descriptors via the connections, equivalent to calling `sd_varlink_set_allow_fd_passing_input()` immediately for each incoming connection. Note that this only has an effect if `AF_UNIX` sockets are used for communication. - `SD_VARLINK_SERVER_ALLOW_FD_PASSING_OUTPUT`: similar, but controls sending of UNIX file descriptors. - `SD_VARLINK_SERVER_FD_PASSING_INPUT_STRICT`: this flag can be used in conjunction with `SD_VARLINK_SERVER_ALLOW_FD_PASSING_INPUT`. If so, file descriptor passing is turned off on the listening sockets already, ensuring that the connection sockets derived from it at no time have file descriptor passing enabled. If `SD_VARLINK_SERVER_ALLOW_FD_PASSING_INPUT` is used without `SD_VARLINK_SERVER_FD_PASSING_INPUT_STRICT` then a choice when to prohibit or allow file descriptor passing can still be made after the connection came in, however permitting a time window where file descriptors might already be enqueued, that then need to be dropped again. - `SD_VARLINK_SERVER_HANDLE_SIGINT`: if set, and `sd_varlink_server_loop_auto()` is used, incoming `SIGINT` process signals will be caught gracefully and cause the event loop to exit cleanly. - `SD_VARLINK_SERVER_HANDLE_SIGTERM`: similar, but does the same for `SIGTERM`. # Return Value On success, `sd_varlink_server_new()` returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. # History `sd_varlink_server_new()` was added in version 257. # See Also `systemd(1)`, `sd-varlink(3)` # sd_varlink_set_description systemd sd_varlink_set_description 3 sd_varlink_set_description sd_varlink_get_description Set or query description of a Varlink connection object \#include \ int sd_varlink_set_description sd_varlink \* link const char \* description const char\* sd_varlink_get_description sd_varlink \* link # Description `sd_varlink_set_description()` sets the description string that is used in logging to the specified string. The string is copied internally and freed when the Varlink connection object is deallocated. The `description` argument may be `NULL`, in which case the description is unset. `sd_varlink_get_description()` returns a description string for the specified Varlink connection. This string may have been previously set with `sd_varlink_set_description()`. If not set this way, a default string or `NULL` may be returned, depending how the connection was allocated and set up. # Return Value On success, `sd_varlink_set_description()` returns a non-negative integer. On failure, it returns a negative errno-style error code. `sd_varlink_get_description()` returns either `NULL` or a pointer to the description string. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. `-ENOMEM` Memory allocation failed. # History `sd_varlink_set_description()` was added in version 257. `sd_varlink_get_description()` was added in version 258. # See Also `systemd(1)`, `sd-varlink(3)` # sd_varlink_set_relative_timeout systemd sd_varlink_set_relative_timeout 3 sd_varlink_set_relative_timeout Set method call time-out \#include \ int sd_varlink_set_relative_timeout sd_varlink \* link uint64_t usec # Description `sd_varlink_set_relative_timeout()` sets the relative timeout in µs to enforce on Varlink method calls. A default time-out of 45s (currently) applies, which may be changed with this call. Set to `UINT64_MAX` to disable the time-out, and to 0 to revert to revert back to the default time-out. The time-out begins whenever a method call is started, and if no response is received by the time the time-out elapses a synthetic `io.systemd.TimedOut` error is raised as client-generated reply to the method call. This call is particularly useful for method calls issued via `sd_varlink_observe()` that shall remain open continuously for a long time. # Return Value On success, `sd_varlink_set_relative_timeout()` returns a non-negative integer. On failure, it returns a negative errno-style error code. ## Errors Returned errors may indicate the following problems: `-EINVAL` An argument is invalid. # History `sd_varlink_set_relative_timeout()` was added in version 257. # See Also `systemd(1)`, `sd-varlink(3)` # sd_watchdog_enabled systemd sd_watchdog_enabled 3 sd_watchdog_enabled Check whether the service manager expects watchdog keep-alive notifications from a service \#include \ int sd_watchdog_enabled int unset_environment uint64_t \* usec # Description `sd_watchdog_enabled()` may be called by a service to detect whether the service manager expects regular keep-alive watchdog notification events from it, and the timeout after which the manager will act on the service if it did not get such a notification. If the `$WATCHDOG_USEC` environment variable is set, and the `$WATCHDOG_PID` variable is unset or set to the PID of the current process, the service manager expects notifications from this process. The manager will usually terminate a service when it does not get a notification message within the specified time after startup and after each previous message. It is recommended that a daemon sends a keep-alive notification message to the service manager every half of the time returned here. Notification messages may be sent with `sd_notify(3)` with a message string of `WATCHDOG=1`. If the `unset_environment` parameter is non-zero, `sd_watchdog_enabled()` will unset the `$WATCHDOG_USEC` and `$WATCHDOG_PID` environment variables before returning (regardless of whether the function call itself succeeded or not). Those variables are no longer inherited by child processes. Further calls to `sd_watchdog_enabled()` will also return with zero. If the `usec` parameter is non-`NULL`, `sd_watchdog_enabled()` will write the timeout in μs for the watchdog logic to it. To enable service supervision with the watchdog logic, use `WatchdogSec=` in service files. See `systemd.service(5)` for details. Use `sd_event_set_watchdog(3)` to enable automatic watchdog support in `sd-event(3)`-based event loops. # Return Value On failure, this call returns a negative errno-style error code. If the service manager expects watchdog keep-alive notification messages to be sent, \> 0 is returned, otherwise 0 is returned. Only if the return value is \> 0, the `usec` parameter is valid after the call. # Notes Internally, this function parses the `$WATCHDOG_PID` and `$WATCHDOG_USEC` environment variable. The call will ignore these variables if `$WATCHDOG_PID` does not contain the PID of the current process, under the assumption that in that case, the variables were set for a different process further up the process tree. # Environment `$WATCHDOG_PID` Set by the system manager for supervised process for which watchdog support is enabled, and contains the PID of that process. See above for details. `$WATCHDOG_USEC` Set by the system manager for supervised process for which watchdog support is enabled, and contains the watchdog timeout in μs. See above for details. # History `sd_watchdog_enabled()` was added in version 209. # See Also `systemd(1)`, `sd-daemon(3)`, `daemon(7)`, `systemd.service(5)`, `sd_notify(3)`, `sd_event_set_watchdog(3)` # shutdown systemd shutdown 8 shutdown Halt, power off or reboot the machine shutdown OPTIONS TIME WALL # Description `shutdown` may be used to halt, power off, or reboot the machine. The first argument may be a time string (which is usually `now`). Optionally, this may be followed by a wall message to be sent to all logged-in users before going down. The time string may either be in the format `hh:mm` for hour/minutes specifying the time to execute the shutdown at, specified in 24h clock format. Alternatively it may be in the syntax `+m` referring to the specified number of minutes m from now. `now` is an alias for `+0`, i.e. for triggering an immediate shutdown. If no time argument is specified, `+1` is implied. The time string specifies the earliest point in time the shutdown may take place; it is a lower bound only: the shutdown is executed as soon as possible, but not before the specified time. Specifying a time that already elapsed (for example an `hh:mm` time earlier today) is not an error and results in an immediate shutdown. See the discussion of `--when=` in `systemctl(1)` for details. Note that to specify a wall message you must specify a time argument, too. If the time argument is used, 5 minutes before the system goes down the `/run/nologin` file is created to ensure that further logins shall not be allowed. # Options The following options are understood: `--help` `-H`; `--halt` Halt the machine. `-P`; `--poweroff` Power the machine off (the default). `-r`; `--reboot` Reboot the machine. `-h` The same as `--poweroff`, but does not override the action to take if it is "halt". E.g. `shutdown --reboot -h` means "poweroff", but `shutdown --halt -h` means "halt". `-k` Do not halt, power off, or reboot, but just write the wall message. `--no-wall` Do not send wall message before halt, power off, or reboot. `-c` Cancel a pending shutdown. This may be used to cancel the effect of an invocation of `shutdown` with a time argument that is not `+0` or `now`. `--show` Show a pending shutdown action and time if there is any. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Compatibility The `shutdown` command in previous init systems (including sysvinit) defaulted to single-user mode instead of powering off the machine. To change into single-user mode, use `systemctl rescue` instead. # See Also `systemd(1)`, `systemctl(1)`, `halt(8)`, `wall(1)` # smbios-type-11 systemd smbios-type-11 7 smbios-type-11 SMBIOS Type 11 strings `/sys/firmware/dmi/entries/11-*/raw` # Description Various OS components process SMBIOS Type 11 vendor strings that a virtual machine manager (VMM) may set and a virtual machine (VM) receives. SMBIOS Type 11 vendor strings may play a similar role as `kernel-command-line(7)` parameters but generally are under control of the VMM rather than the boot loader or UKI. For details on SMBIOS Type 11 see the [System Management BIOS](https://www.dmtf.org/standards/smbios/) specifications. # Strings The following strings are supported: `io.systemd.credential:`\; `io.systemd.credential.binary:`\ This allows passing additional system credentials into the system, in textual or binary (Base64) form. See `systemd.exec(5)` and [System and Service Credentials](https://systemd.io/CREDENTIALS) for details. `io.systemd.stub.kernel-cmdline-extra=`\ This allows configuration of additional kernel command line options, and is read by the kernel UEFI stub. For details see `systemd-stub(7)`. `io.systemd.boot.kernel-cmdline-extra=`\ This allows configuration of additional kernel command line options for Boot Loader Specification Type 1 entries, and is read by `systemd-boot`. For details see `systemd-boot(7)`. `io.systemd.boot-entries.extra:`\ This allows inserting additional entries into the `systemd-boot` menu. For details see `systemd-boot(7)`. `io.systemd.boot.loglevel=`\ This allows configuration of the log level, and is read by `systemd-boot` and `systemd-stub`. For details see `systemd-boot(7)` and `systemd-stub(7)`. `io.systemd.boot.timeout=`\ This allows configuration of the menu timeout in seconds, and is read by `systemd-boot`. For details see `systemd-boot(7)`. # See Also `systemd(1)`, `kernel-command-line(7)`, `systemd.system-credentials(7)` # Configuration Directories and Precedence Configuration files are read from directories in `/etc/`, `/run/`, `/usr/local/lib/`, and `/usr/lib/`, in order of precedence, as listed in the SYNOPSIS section above. Files must have the `.conf` extension. Files in `/etc/` override files with the same name in `/run/`, `/usr/local/lib/`, and `/usr/lib/`. Files in `/run/` override files with the same name under `/usr/`. All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in. If multiple files specify the same option, the entry in the file with the lexicographically latest name will take precedence. Thus, the configuration in a certain file may either be replaced completely (by placing a file with the same name in a directory with higher priority), or individual settings might be changed (by specifying additional settings in a file with a different name that is ordered later). Packages should install their configuration files in `/usr/lib/` (distribution packages) or `/usr/local/lib/` (local installs) . Files in `/etc/` are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. It is recommended to prefix all filenames with a two-digit number and a dash to simplify the ordering. It is recommended to use the range 10-40 for configuration files in `/usr/` and the range 60-90 for configuration files in `/etc/` and `/run/`, to make sure that local and transient configuration files will always take priority over configuration files shipped by the OS vendor. If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to `/dev/null` in the configuration directory in `/etc/`, with the same filename as the vendor configuration file. If the vendor configuration file is included in the initrd image, the image has to be regenerated. # Configuration Directories and Precedence The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used: `/etc/systemd/`, `/run/systemd/`, `/usr/local/lib/systemd/` , `/usr/lib/systemd/`. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator. Local overrides can also be created by creating drop-ins, as described below. The main configuration file can also be edited for this purpose (or a copy in `/etc/` if it is shipped under `/usr/`), however using drop-ins for local configuration is recommended over modifications to the main configuration file. In addition to the main configuration file, drop-in configuration snippets are read from `/usr/lib/systemd/*.conf.d/`, `/usr/local/lib/systemd/*.conf.d/`, and `/etc/systemd/*.conf.d/`. Those drop-ins have higher precedence and override the main configuration file. Files in the `*.conf.d/` configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files. When packages need to customize the configuration, they can install drop-ins under `/usr/`. Files in `/etc/` are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. Drop-ins have to be used to override package drop-ins, since the main configuration file has lower precedence. It is recommended to prefix all filenames in those subdirectories with a two-digit number and a dash, to simplify the ordering. This also defines a concept of drop-in priorities to allow OS vendors to ship drop-ins within a specific range lower than the range used by users. This should lower the risk of package drop-ins overriding accidentally drop-ins defined by users. It is recommended to use the range 10-40 for drop-ins in `/usr/` and the range 60-90 for drop-ins in `/etc/` and `/run/`, to make sure that local and transient drop-ins take priority over drop-ins shipped by the OS vendor. To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to `/dev/null` in the configuration directory in `/etc/`, with the same filename as the vendor configuration file. # Extras `/usr/local/lib/systemd` [^1] [^1]: 💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If `/usr/local/` is a separate partition, it may not be available during early boot, and must not be used for configuration. # standard-options `-h`; `--help` Print a short help text and exit. `--version` Print a short version string and exit. `-V`; `--version` Print a short version string and exit. `--no-pager` Do not pipe output into a pager. `--no-ask-password` Do not query the user for authentication for privileged operations. `--legend=BOOL` Enable or disable printing of the legend, i.e. column headers and the footer with hints. The legend is printed by default, unless disabled with `--quiet` or similar. `--no-legend` Do not print the legend, i.e. column headers and the footer with hints. `--cat-config` Copy the contents of config files to standard output. Before each file, the filename is printed as a comment. `--tldr` Copy the contents of config files to standard output. Only the "interesting" parts of the configuration files are printed, comments and empty lines are skipped. Before each file, the filename is printed as a comment. `--json=MODE` Shows output formatted as JSON. Expects one of `short` (for the shortest possible output without any redundant whitespace or line breaks), `pretty` (for a pretty version of the same, with indentation and line breaks) or `off` (to turn off JSON output, the default). `-j` Equivalent to `--json=pretty` if running on a terminal, and `--json=short` otherwise. `-s`; `--signal=` When used with `kill`, choose which signal to send to selected processes. Must be one of the well-known signal specifiers such as `SIGTERM`, `SIGINT` or `SIGSTOP`. If omitted, defaults to `SIGTERM`. The special value `help` will list the known values and the program will exit immediately, and the special value `list` will list known values along with the numerical signal numbers and the program will exit immediately. `--image-policy=policy` Takes an image policy string as argument, as per `systemd.image-policy(7)`. The policy is enforced when operating on the disk image specified via `--image=`, see above. If not specified, defaults to the `*` policy, i.e. all recognized file systems in the image are used. `--image-filter=filter` Takes an image filter string as argument, as per `systemd.image-filter(7)`. The filter is taken into consideration when operating on the disk image specified via `--image=`, see above. If not specified no filtering is applied. `--esp-path=` Path to the EFI System Partition (ESP). If not specified, `/efi/`, `/boot/`, and `/boot/efi/` are checked in turn. It is recommended to mount the ESP to `/efi/`, if possible. `--boot-path=` Path to the Extended Boot Loader partition, as defined in the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification). If not specified, `/boot/` is checked. It is recommended to mount the Extended Boot Loader partition to `/boot/`, if possible. `-P` Equivalent to `--value` `--property=`, i.e. shows the value of the property without the property name or `=`. Note that using `-P` once will also affect all properties listed with `-p`/`--property=`. # standard-specifiers %a Architecture A short string identifying the architecture of the local system. A string such as x86 , x86-64 or arm64 . See the architectures defined for ConditionArchitecture= in systemd.unit 5 for a full list. %A Operating system image version The operating system image version identifier of the running system, as read from the IMAGE_VERSION= field of /etc/os-release . If not set, resolves to an empty string. See os-release 5 for more information. %b Boot ID The boot ID of the running system, formatted as string. See random 4 for more information. %B Operating system build ID The operating system build identifier of the running system, as read from the BUILD_ID= field of /etc/os-release . If not set, resolves to an empty string. See os-release 5 for more information. %D Shared data directory This is either /usr/share/ (for the system manager) or the path \$XDG_DATA_HOME resolves to (for user managers). %H Host name The hostname of the running system. %l Short host name The hostname of the running system, truncated at the first dot to remove any domain component. %m Machine ID The machine ID of the running system, formatted as string. See machine-id 5 for more information. %M Operating system image identifier The operating system image identifier of the running system, as read from the IMAGE_ID= field of /etc/os-release . If not set, resolves to an empty string. See os-release 5 for more information. %o Operating system ID The operating system identifier of the running system, as read from the ID= field of /etc/os-release . See os-release 5 for more information. %q Pretty host name The pretty hostname of the running system, as read from the PRETTY_HOSTNAME= field of /etc/machine-info . If not set, resolves to the short hostname. See machine-info 5 for more information. %T Directory for temporary files This is either /tmp or the path \$TMPDIR , \$TEMP or \$TMP are set to. (Note that the directory may be specified without a trailing slash.) %v Kernel release Identical to uname -r output. %V Directory for larger and persistent temporary files This is either /var/tmp or the path \$TMPDIR , \$TEMP or \$TMP are set to. (Note that the directory may be specified without a trailing slash.) %w Operating system version ID The operating system version identifier of the running system, as read from the VERSION_ID= field of /etc/os-release . If not set, resolves to an empty string. See os-release 5 for more information. %W Operating system variant ID The operating system variant identifier of the running system, as read from the VARIANT_ID= field of /etc/os-release . If not set, resolves to an empty string. See os-release 5 for more information. %% Single percent sign Use %% in place of % to specify a single percent sign. # storagectl systemd storagectl 1 storagectl mount.storage Enumerate and mount storage volumes provided by storage providers storagectl OPTIONS COMMAND NAME mount -t storage PROVIDER : VOLUME DIRECTORY mount -t storage. FSTYPE PROVIDER : VOLUME DIRECTORY # Description `storagectl` may be used to inspect storage providers and the storage volumes they expose. A storage provider is a service implementing the `io.systemd.StorageProvider` [Varlink](https://varlink.org/) interface, registered as an AF_UNIX socket below the well-known socket directory `/run/systemd/io.systemd.StorageProvider/` (in system mode) or `$XDG_RUNTIME_DIR``/systemd/io.systemd.StorageProvider/` (in user mode). The two storage providers shipped with systemd are `systemd-storage-block@.service(8)`, which exposes the system's block devices, and `systemd-storage-fs@.service(8)`, which exposes regular files and directories from a backing file system. The tool also provides a `mount(8)` helper for the file system type `storage`, which permits mounting storage volumes to arbitrary places. See "Use as a mount helper" below for details. # Commands The following commands are understood: `volumes` \[\\] List storage volumes provided by all storage providers running on the system (or, with `--user`, in the user runtime). The optional \ argument is a shell-style pattern (see `fnmatch(3)`) that filters the result by volume name. The output is a table containing the providing service, the volume name, its type (`blk`, `reg` or `dir`), whether it is read-only, and — if known — its size and the number of bytes used. This is the default command if none is specified. `templates` \[\\] List volume templates supported by the running storage providers. Templates encapsulate a configuration to use when creating volumes on-the-fly, when they are acquired. Template support is an optional feature for providers, and only applies to providers that allow creation of volumes on-the-fly. See the respective provider documentation for details, for example `systemd-storage-fs@.service(8)`. The optional \ argument filters by template name. Storage providers that do not implement template-based volume creation (such as the block-device provider) do not contribute to this output. `providers` List the storage providers known to the system. This is determined by scanning the well-known socket directory for `AF_UNIX` sockets that look like `io.systemd.StorageProvider` endpoints. For each provider it is also reported whether the socket can currently be connected to. # Options The following options are understood: `--system` Operate on system-wide storage providers. Sockets are looked for in `/run/systemd/io.systemd.StorageProvider/`. This is the default. `--user` Operate on per-user storage providers. Sockets are looked for in `$XDG_RUNTIME_DIR/systemd/io.systemd.StorageProvider/`. # Use as a mount helper The tool provides the `/sbin/mount.storage` alias, implementing the `mount(8)` "external helper" interface, allowing storage volumes to be mounted with the regular `mount` command. The volume to mount is encoded as the source of the mount, in the form `PROVIDER:VOLUME`, where \ is the name of a storage provider (as listed by `storagectl providers`) and \ is the volume name. Two file system type spellings are recognized: `storage` Acquires a directory volume and bind-mounts its directory tree onto the target. `storage.FSTYPE` Acquires a regular file or block device volume and mounts it as a file system of type \ (for example `storage.ext4`, `storage.btrfs`, …). The standard `-o` mount options are forwarded to `mount`. In addition, the following `storage.`-prefixed options are interpreted by `mount.storage` itself and stripped from the forwarded list: `storage.create=`\ Takes one of `any` (open if it exists, otherwise create — the default), `open` (fail if the volume does not yet exist) or `new` (fail if the volume already exists). `storage.template=`\ The template to use when creating a new volume, if it is missing and the provider supports on-the-fly creation of volumes. `storage.create-size=`\ When creating a new volume on-the-fly, the size in bytes to allocate. Accepts the usual `K`/`M`/`G`/`T` suffixes (base 1024). Required when creating a regular file volume. # Examples
Enumerate available storage providers, volumes and templates
$ storagectl providers $ storagectl volumes $ storagectl volumes '*foo*' $ storagectl templates
Mount a directory volume from the file system provider
# mount -t storage fs:myvol /mnt/myvol If the volume `myvol` does not yet exist, it will be created using the default `subvolume` template.
Create and mount an ext4 file system from a regular file.
# mount -t storage.ext4 fs:scratch /mnt/scratch -o loop
Mount a block device volume read-only
# mount -t storage.ext4 -o ro block:/dev/disk/by-id/usb-foo /mnt/foo
# Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-storage-block@.service(8)`, `systemd-storage-fs@.service(8)`, `varlinkctl(1)`, `mount(8)` # supported-controllers # The following controller names may be specified: `cpu`, `cpuset`, `io`, `memory`, `pids`, `bpf-firewall`, `bpf-devices`, `bpf-foreign`, `bpf-socket-bind`, `bpf-restrict-network-interfaces`, and `bpf-bind-network-interface`. # sysctl.d systemd sysctl.d 5 sysctl.d Configure kernel parameters at boot `/etc/sysctl.d/*.conf`, `/run/sysctl.d/*.conf`, `/usr/local/lib/sysctl.d/*.conf`, `/usr/lib/sysctl.d/*.conf` key.name.under.proc.sys = some value key/name/under/proc/sys = some value key/middle.part.with.dots/foo = 123 key.middle/part/with/dots.foo = 123 -key.that.will.not.fail = value key.pattern.*.with.glob = whatever -key.pattern.excluded.with.glob key.pattern.overridden.with.glob = custom # Description At boot, `systemd-sysctl.service(8)` reads configuration files from the above directories to configure `sysctl(8)` kernel parameters. # Configuration Format The configuration files contain a list of variable assignments, separated by newlines. Empty lines and lines whose first non-whitespace character is `#` or `;` are ignored. Note that either `/` or `.` may be used as separators within sysctl variable names. If the first separator is a slash, remaining slashes and dots are left intact. If the first separator is a dot, dots and slashes are interchanged. `kernel.domainname=foo` and `kernel/domainname=foo` are equivalent and will cause `foo` to be written to `/proc/sys/kernel/domainname`. Either `net.ipv4.conf.enp3s0/200.forwarding` or `net/ipv4/conf/enp3s0.200/forwarding` may be used to refer to `/proc/sys/net/ipv4/conf/enp3s0.200/forwarding`. A glob `glob(7)` pattern may be used to write the same value to all matching keys. Keys for which an explicit pattern exists will be excluded from any glob matching. In addition, a key may be explicitly excluded from being set by any matching glob patterns by specifying the key name prefixed with a `-` character and not followed by `=`, see SYNOPSIS. Any access permission errors and attempts to write variables not present on the local system are logged at debug level and do not cause the service to fail. Other types of errors when setting variables are logged with higher priority and cause the service to return failure at the end (after processing other variables). As an exception, if a variable assignment is prefixed with a single `-` character, failure to set the variable for any reason will be logged at debug level and will not cause the service to fail. The settings configured with `sysctl.d` files will be applied early on boot. The network interface-specific options will also be applied individually for each network interface as it shows up in the system. (More specifically, `net.ipv4.conf.*`, `net.ipv6.conf.*`, `net.ipv4.neigh.*` and `net.ipv6.neigh.*`). Many sysctl parameters only become available when certain kernel modules are loaded. Modules are usually loaded on demand, e.g. when certain hardware is plugged in or network brought up. This means that `systemd-sysctl.service(8)` which runs during early boot will not configure such parameters if they become available after it has run. To set such parameters, it is recommended to add an `udev(7)` rule to set those parameters when they become available. Alternatively, a slightly simpler and less efficient option is to add the module to `modules-load.d(5)`, causing it to be loaded statically before sysctl settings are applied (see example below). # Examples
Set kernel YP domain name
`/etc/sysctl.d/domain-name.conf`: kernel.domainname=example.com
Apply settings available only when a certain module is loaded (method one)
`/etc/udev/rules.d/99-bridge.rules`: ACTION=="add", SUBSYSTEM=="module", KERNEL=="br_netfilter", \ RUN+="/usr/lib/systemd/systemd-sysctl --prefix=/net/bridge" `/etc/sysctl.d/bridge.conf`: net.bridge.bridge-nf-call-ip6tables = 0 net.bridge.bridge-nf-call-iptables = 0 net.bridge.bridge-nf-call-arptables = 0 This method applies settings when the module is loaded. Please note that, unless the `br_netfilter` module is loaded, bridged packets will not be filtered by Netfilter (starting with kernel 3.18), so simply not loading the module is sufficient to avoid filtering.
Apply settings available only when a certain module is loaded (method two)
`/etc/modules-load.d/bridge.conf`: br_netfilter `/etc/sysctl.d/bridge.conf`: net.bridge.bridge-nf-call-ip6tables = 0 net.bridge.bridge-nf-call-iptables = 0 net.bridge.bridge-nf-call-arptables = 0 This method forces the module to be always loaded. Please note that, unless the `br_netfilter` module is loaded, bridged packets will not be filtered by Netfilter (starting with kernel 3.18), so simply not loading the module is sufficient to avoid filtering.
Set network routing properties for all interfaces
`/etc/sysctl.d/20-rp_filter.conf`: net.ipv4.conf.default.rp_filter = 2 net.ipv4.conf.*.rp_filter = 2 -net.ipv4.conf.all.rp_filter net.ipv4.conf.hub0.rp_filter = 1 The `rp_filter` key will be set to "2" for all interfaces, except "hub0". We set `net.ipv4.conf.default.rp_filter` first, so any interfaces which are added *later* will get this value (this also covers any interfaces detected while we're running). The glob matches any interfaces which were detected *earlier*. The glob will also match `net.ipv4.conf.all.rp_filter`, which we do not want to set at all, so it is explicitly excluded. And "hub0" is excluded from the glob because it has an explicit setting.
# See Also `systemd(1)`, `systemd-sysctl.service(8)`, `systemd-delta(1)`, `sysctl(8)`, `sysctl.conf(5)`, `modprobe(8)` # sysext.conf systemd sysext.conf 5 sysext.conf confext.conf sysext.conf.d confext.conf.d Configuration files for systemd-sysext `/etc/systemd/sysext.conf` `/etc/systemd/sysext.conf.d/*.conf` `/run/systemd/sysext.conf` `/run/systemd/sysext.conf.d/*.conf` `/usr/lib/systemd/sysext.conf` `/usr/lib/systemd/sysext.conf.d/*.conf` `/etc/systemd/confext.conf` `/etc/systemd/confext.conf.d/*.conf` `/run/systemd/confext.conf` `/run/systemd/confext.conf.d/*.conf` `/usr/lib/systemd/confext.conf` `/usr/lib/systemd/confext.conf.d/*.conf` # Description These configuration files control the behavior of `systemd-sysext(8)` and `systemd-confext(8)`. They are especially useful when needing to customize the behavior of the respective extension service units. # Options The following options are understood in both the `[SysExt]` and `[ConfExt]` sections: ## Section Options `Mutable=` Set the mutable mode for system extensions. Takes one of `no`, `yes`, `auto`, `import`, `ephemeral`, or `ephemeral-import`. For details about the modes, see the `--mutable=` option in `systemd-sysext(8)`. Defaults to `no`. `ImagePolicy=` Set the image policy. Takes an image policy string as argument, as per `systemd.image-policy(7)`. For details, see the `--image-policy=` option in `systemd-sysext(8)`. # See Also `systemd(1)`, `systemd-sysext(8)`, `systemd.syntax(7)` # system-only # This option is only available for system services and is not supported for services running in per-user instances of the service manager. These options are only available for system services and are not supported for services running in per-user instances of the service manager. # system-or-user-ns-mountfsd-mount-options # When enabled for services running in per-user instances of the service manager using mount options is disabled by default, due to the security implications. It is possible to use a [polkit](https://www.freedesktop.org/software/polkit/docs/latest/) policy to allow specific mount options, for example:
A polkit policy that allows mounting the root partition with nosuid
`/etc/polkit-1/rules.d/mountoptions.rules`: polkit.addRule(function(action, subject) { if (action.id == "io.systemd.mount-file-system.mount-untrusted-image-privately" && action.lookup("mount_options") == "root:nosuid") { return polkit.Result.YES; } });
# system-or-user-ns-mountfsd # When enabled for services running in per-user instances of the service manager this option implicitly enables `PrivateUsers=` (requires unprivileged user namespaces support to be enabled in the kernel via the `kernel.unprivileged_userns_clone=` sysctl) and also relies on `systemd-mountfsd.service(8)`. When enabled for services running in per-user instances of the service manager these options implicitly enable `PrivateUsers=` (requires unprivileged user namespaces support to be enabled in the kernel via the `kernel.unprivileged_userns_clone=` sysctl) and also rely on `systemd-mountfsd.service(8)`. # system-or-user-ns # This option is only available for system services, or for services running in per-user instances of the service manager in which case `PrivateUsers=` is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the `kernel.unprivileged_userns_clone=` sysctl). These options are only available for system services, or for services running in per-user instances of the service manager in which case `PrivateUsers=` is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the `kernel.unprivileged_userns_clone=` sysctl). # systemd-ac-power systemd systemd-ac-power 1 systemd-ac-power Report whether we are connected to an external power source systemd-ac-power OPTIONS # Description `systemd-ac-power` may be used to check whether the system is running on AC power or not. By default, it will simply return success (if we can detect that we are running on AC power) or failure, with no output. This can be useful for example to debug `ConditionACPower=` (see `systemd.unit(5)`). # Options The following options are understood: `-v`; `--verbose` Show result as text instead of just returning success or failure. `--low` Instead of showing AC power state, show low battery state. In this case, will return zero if all batteries are currently discharging and below 5% of maximum charge. Returns non-zero otherwise. # Exit status On success (running on AC power), 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)` # systemd-analyze systemd systemd-analyze 1 systemd-analyze Analyze and debug system manager systemd-analyze OPTIONS time systemd-analyze OPTIONS blame systemd-analyze OPTIONS critical-chain UNIT systemd-analyze OPTIONS dump PATTERN systemd-analyze OPTIONS plot \>file.svg systemd-analyze OPTIONS dot PATTERN \>file.dot systemd-analyze OPTIONS unit-files systemd-analyze OPTIONS unit-gdb SERVICE systemd-analyze OPTIONS unit-paths systemd-analyze OPTIONS unit-shell SERVICE COMMAND systemd-analyze OPTIONS exit-status STATUS systemd-analyze OPTIONS capability CAPABILITY -m --mask MASK systemd-analyze OPTIONS condition CONDITION … systemd-analyze OPTIONS syscall-filter SET … systemd-analyze OPTIONS filesystems SET … systemd-analyze OPTIONS calendar SPEC systemd-analyze OPTIONS timestamp TIMESTAMP systemd-analyze OPTIONS timespan SPAN systemd-analyze OPTIONS cat-config NAME \| PATH systemd-analyze OPTIONS compare-versions VERSION1 OP VERSION2 systemd-analyze OPTIONS verify FILE systemd-analyze OPTIONS security UNIT systemd-analyze OPTIONS inspect-elf FILE systemd-analyze OPTIONS malloc D-BUS SERVICE systemd-analyze OPTIONS fdstore UNIT systemd-analyze OPTIONS image-policy POLICY systemd-analyze OPTIONS has-tpm2 systemd-analyze OPTIONS identify-tpm2 systemd-analyze OPTIONS pcrs PCR systemd-analyze OPTIONS nvpcrs NVPCR systemd-analyze OPTIONS srk \>FILE systemd-analyze OPTIONS architectures NAME systemd-analyze OPTIONS cpu-features NAME systemd-analyze OPTIONS smbios11 systemd-analyze OPTIONS chid systemd-analyze OPTIONS transient-settings TYPE # Description `systemd-analyze` may be used to determine system boot-up performance statistics and retrieve other state and tracing information from the system and service manager, and to verify the correctness of unit files. It is also used to access special functions useful for advanced system manager debugging. If no command is passed, `systemd-analyze time` is implied. ## `systemd-analyze time` This command prints the time spent in the kernel before userspace has been reached, the time spent in the initrd before normal system userspace has been reached, and the time normal system userspace took to initialize. Note that these measurements simply measure the time passed up to the point where all system services have been spawned, but not necessarily until they fully finished initialization or the disk is idle. If the manager carried shutdown timestamps across a kexec-based live update (i.e. they were restored from the previous boot through the Live Update Orchestrator), the previous boot's shutdown phases are prepended to the chain, so the full shutdown plus bootup sequence is shown and summed into the total: the time spent stopping units (`(stopping)`), the time the manager took to hand off to `systemd-shutdown(8)` (`(exit)`) and the time spent in `systemd-shutdown` itself (`(systemd-shutdown)`) are added before the firmware/loader/kernel/initrd/userspace phases.
`Show how long the boot took`
# in a container $ systemd-analyze time Startup finished in 296ms (userspace) multi-user.target reached after 275ms in userspace # on a real machine $ systemd-analyze time Startup finished in 2.584s (kernel) + 19.176s (initrd) + 47.847s (userspace) = 1min 9.608s multi-user.target reached after 47.820s in userspace
## `systemd-analyze blame` This command prints a list of all running units, ordered by the time they took to initialize. This information may be used to optimize boot-up times. Note that the output might be misleading as the initialization of one service might be slow simply because it waits for the initialization of another service to complete. Also note: `systemd-analyze blame` does not display results for services with `Type=simple`, because systemd considers such services to be started immediately, hence no measurement of the initialization delays can be done. Also note that this command only shows the time units took for starting up, it does not show how long unit jobs spent in the execution queue. In particular it shows the time units spent in `activating` state, which is not defined for units such as device units that transition directly from `inactive` to `active`. This command hence gives an impression of the performance of program code, but cannot accurately reflect latency introduced by waiting for hardware and similar events.
`Show which units took the most time during boot`
$ systemd-analyze blame 32.875s pmlogger.service 20.905s systemd-networkd-wait-online.service 13.299s dev-vda1.device ... 23ms sysroot.mount 11ms initrd-udevadm-cleanup-db.service 3ms sys-kernel-config.mount
## `systemd-analyze critical-chain UNIT...` This command prints a tree of the time-critical chain of units (for each of the specified \s or for the default target otherwise). The time after the unit is active or started is printed after the "@" character. The time the unit takes to start is printed after the "+" character. Note that the output might be misleading as the initialization of services might depend on socket activation and because of the parallel execution of units. Also, similarly to the `blame` command, this only takes into account the time units spent in `activating` state, and hence does not cover units that never went through an `activating` state (such as device units that transition directly from `inactive` to `active`). Moreover, it does not show information on jobs (and in particular not jobs that timed out).
`systemd-analyze critical-chain`
$ systemd-analyze critical-chain multi-user.target @47.820s └─pmie.service @35.968s +548ms └─pmcd.service @33.715s +2.247s └─network-online.target @33.712s └─systemd-networkd-wait-online.service @12.804s +20.905s └─systemd-networkd.service @11.109s +1.690s └─systemd-udevd.service @9.201s +1.904s └─systemd-tmpfiles-setup-dev.service @7.306s +1.776s └─kmod-static-nodes.service @6.976s +177ms └─systemd-journald.socket └─system.slice └─-.slice
## `systemd-analyze dump [pattern…]` Without any parameter, this command outputs a (usually very long) human-readable serialization of the complete service manager state. Optional glob pattern may be specified, causing the output to be limited to units whose names match one of the patterns. The output format is subject to change without notice and should not be parsed by applications. This command is rate limited for unprivileged users.
Show the internal state of user manager
$ systemd-analyze --user dump Timestamp userspace: Thu 2019-03-14 23:28:07 CET Timestamp finish: Thu 2019-03-14 23:28:07 CET Timestamp generators-start: Thu 2019-03-14 23:28:07 CET Timestamp generators-finish: Thu 2019-03-14 23:28:07 CET Timestamp units-load-start: Thu 2019-03-14 23:28:07 CET Timestamp units-load-finish: Thu 2019-03-14 23:28:07 CET -> Unit proc-timer_list.mount: Description: /proc/timer_list ... -> Unit default.target: Description: Main user target ...
## `systemd-analyze malloc [D-Bus service…]` This command can be used to request the output of the internal memory state (as returned by `malloc_info(3)`) of a D-Bus service. If no service is specified, the query will be sent to `org.freedesktop.systemd1` (the system or user service manager). The output format is not guaranteed to be stable and should not be parsed by applications. The service must implement the `org.freedesktop.MemoryAllocation1` interface. In the systemd suite, it is currently only implemented by the manager. ## `systemd-analyze plot` This command prints either an SVG graphic, detailing which system services have been started at what time, highlighting the time they spent on initialization, or the raw time data in JSON or table format.
`Plot a bootchart`
$ systemd-analyze plot >bootup.svg $ eog bootup.svg&
Note that this plot is based on the most recent per-unit timing data of loaded units. This means that if a unit gets started, then stopped and then started again the information shown will cover the most recent start cycle, not the first one. Thus it is recommended to consult this information only shortly after boot, so that this distinction does not matter. Moreover, units that are not referenced by any other unit through a dependency might be unloaded by the service manager once they terminate (and did not fail). Such units will not show up in the plot. ## `systemd-analyze dot [pattern...]` This command generates textual dependency graph description in dot format for further processing with the GraphViz `dot(1)` tool. Use a command line like `systemd-analyze dot | dot -Tsvg >systemd.svg` to generate a graphical dependency tree. Unless `--order` or `--require` is passed, the generated graph will show both ordering and requirement dependencies. Optional pattern globbing style specifications (e.g. `*.target`) may be given at the end. A unit dependency is included in the graph if any of these patterns match either the origin or destination node.
Plot all dependencies of any unit whose name starts with `avahi-daemon`
$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg >avahi.svg $ eog avahi.svg
Plot the dependencies between all known target units
$ systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' \ | dot -Tsvg >targets.svg $ eog targets.svg
## `systemd-analyze unit-paths` This command outputs a list of all directories from which unit files, `.d` overrides, and `.wants`, `.requires` symlinks may be loaded. Combine with `--user` to retrieve the list for the user manager instance, and `--global` for the global configuration of user manager instances.
`Show all paths for generated units`
$ systemd-analyze unit-paths | grep '^/run' /run/systemd/system.control /run/systemd/transient /run/systemd/generator.early /run/systemd/system /run/systemd/system.attached /run/systemd/generator /run/systemd/generator.late
Note that this verb prints the list that is compiled into `systemd-analyze` itself, and does not communicate with the running manager. Use systemctl [--user] [--global] show -p UnitPath --value to retrieve the actual list that the manager uses, with any empty directories omitted. ## `systemd-analyze exit-status STATUS...` This command prints a list of exit statuses along with their "class", i.e. the source of the definition (one of `libc`, `systemd`, `LSB`, or `BSD`), see the Process Exit Codes section in `systemd.exec(5)`. If no additional arguments are specified, all known statuses are shown. Otherwise, only the definitions for the specified codes are shown.
`Show some example exit status names`
$ systemd-analyze exit-status 0 1 {63..65} NAME STATUS CLASS SUCCESS 0 libc FAILURE 1 libc - 63 - USAGE 64 BSD DATAERR 65 BSD
## `systemd-analyze capability CAPABILITY -m --mask MASK` This command prints a list of Linux capabilities along with their numeric IDs. See `capabilities(7)` for details. If no argument is specified the full list of capabilities known to the service manager and the kernel is shown. Capabilities defined by the kernel but not known to the service manager are shown as `cap_???`. Optionally, if arguments are specified they may refer to specific cabilities by name or numeric ID, in which case only the indicated capabilities are shown in the table. Alternatively, if `--mask` is passed, a single numeric argument must be specified, which is interpreted as a hexadecimal capability mask. In this case, only the capabilities present in the mask are shown in the table. This mode is intended to aid in decoding capability sets available via various debugging interfaces (e.g. `/proc/PID/status`).
`Show some example capability names`
$ systemd-analyze capability 0 1 {30..32} NAME NUMBER cap_chown 0 cap_dac_override 1 cap_audit_control 30 cap_setfcap 31 cap_mac_override 32
`Decode a capability mask extracted from /proc`
$ systemd-analyze capability -m 0000000000003c00 NAME NUMBER cap_net_bind_service 10 cap_net_broadcast 11 cap_net_admin 12 cap_net_raw 13
## `systemd-analyze condition CONDITION...` This command will evaluate `Condition*=...` and `Assert*=...` assignments, and print their values, and the resulting value of the combined condition set. See `systemd.unit(5)` for a list of available conditions and asserts.
Evaluate conditions that check kernel versions
$ systemd-analyze condition 'ConditionVersion = ! <4.0' \ 'ConditionVersion = >=5.1' \ 'ConditionACPower=|false' \ 'ConditionArchitecture=|!arm' \ 'AssertPathExists=/etc/os-release' test.service: AssertPathExists=/etc/os-release succeeded. Asserts succeeded. test.service: ConditionArchitecture=|!arm succeeded. test.service: ConditionACPower=|false failed. test.service: ConditionVersion=>=5.1 succeeded. test.service: ConditionVersion=!<4.0 succeeded. Conditions succeeded.
## `systemd-analyze syscall-filter SET...` This command will list system calls contained in the specified system call set \, or all known sets if no sets are specified. Argument \ must include the `@` prefix. ## `systemd-analyze filesystems SET...` This command will list filesystems in the specified filesystem set \, or all known sets if no sets are specified. Argument \ must include the `@` prefix. ## `systemd-analyze calendar EXPRESSION...` This command will parse and normalize repetitive calendar time events, and will calculate when they elapse next. This takes the same input as the `OnCalendar=` setting in `systemd.timer(5)`, following the syntax described in `systemd.time(7)`. By default, only the next time the calendar expression will elapse is shown; use `--iterations=` to show the specified number of next times the expression elapses. Each time the expression elapses forms a timestamp, see the `timestamp` verb below.
Show leap days in the near future
$ systemd-analyze calendar --iterations=5 '*-2-29 0:0:0' Original form: *-2-29 0:0:0 Normalized form: *-02-29 00:00:00 Next elapse: Sat 2020-02-29 00:00:00 UTC From now: 11 months 15 days left Iter. #2: Thu 2024-02-29 00:00:00 UTC From now: 4 years 11 months left Iter. #3: Tue 2028-02-29 00:00:00 UTC From now: 8 years 11 months left Iter. #4: Sun 2032-02-29 00:00:00 UTC From now: 12 years 11 months left Iter. #5: Fri 2036-02-29 00:00:00 UTC From now: 16 years 11 months left
## `systemd-analyze timestamp TIMESTAMP...` This command parses a timestamp (i.e. a single point in time) and outputs the normalized form and the difference between this timestamp and now. The timestamp should adhere to the syntax documented in `systemd.time(7)`, section "PARSING TIMESTAMPS".
Show parsing of timestamps
$ systemd-analyze timestamp yesterday now tomorrow Original form: yesterday Normalized form: Mon 2019-05-20 00:00:00 CEST (in UTC): Sun 2019-05-19 22:00:00 UTC UNIX seconds: @15583032000 From now: 1 day 9h ago Original form: now Normalized form: Tue 2019-05-21 09:48:39 CEST (in UTC): Tue 2019-05-21 07:48:39 UTC UNIX seconds: @1558424919.659757 From now: 43us ago Original form: tomorrow Normalized form: Wed 2019-05-22 00:00:00 CEST (in UTC): Tue 2019-05-21 22:00:00 UTC UNIX seconds: @15584760000 From now: 14h left
## `systemd-analyze timespan EXPRESSION...` This command parses a time span (i.e. a difference between two timestamps) and outputs the normalized form and the equivalent value in microseconds. The time span should adhere to the syntax documented in `systemd.time(7)`, section "PARSING TIME SPANS". Values without units are parsed as seconds.
Show parsing of timespans
$ systemd-analyze timespan 1s 300s '1year 0.000001s' Original: 1s μs: 1000000 Human: 1s Original: 300s μs: 300000000 Human: 5min Original: 1year 0.000001s μs: 31557600000001 Human: 1y 1us
## `systemd-analyze cat-config` \\|\... This command is similar to `systemctl cat`, but operates on config files. It will copy the contents of a config file and any drop-ins to standard output, using the usual systemd set of directories and rules for precedence. Each argument must be either an absolute path including the prefix (such as `/etc/systemd/logind.conf` or `/usr/lib/systemd/logind.conf`), or a name relative to the prefix (such as `systemd/logind.conf`).
Showing logind configuration
$ systemd-analyze cat-config systemd/logind.conf # /etc/systemd/logind.conf ... [Login] NAutoVTs=8 ... # /usr/lib/systemd/logind.conf.d/20-test.conf ... some override from another package # /etc/systemd/logind.conf.d/50-override.conf ... some administrator override
## `systemd-analyze compare-versions VERSION1 OP VERSION2` This command has two distinct modes of operation, depending on whether the operator \ is specified. In the first mode — when \ is not specified —, it will compare the two version strings and print either `VERSION1 < VERSION2`, or `VERSION1 == VERSION2`, or `VERSION1 > VERSION2` as appropriate. The exit status is `0` if the versions are equal, `11` if the version of the right is smaller, and `12` if the version of the left is smaller. (This matches the convention used by `rpmdev-vercmp`.) In the second mode — when \ is specified — it will compare the two version strings using the operation \ and return `0` (success) if they condition is satisfied, and `1` (failure) otherwise. `OP` may be `lt`, `le`, `eq`, `ne`, `ge`, `gt`. In this mode, no output is printed. (This matches the convention used by `dpkg(1)` `--compare-versions`.)
Compare versions of a package
$ systemd-analyze compare-versions systemd-250~rc1.fc36.aarch64 systemd-251.fc36.aarch64 systemd-250~rc1.fc36.aarch64 < systemd-251.fc36.aarch64 $ echo $? 12 $ systemd-analyze compare-versions 1 lt 2; echo $? 0 $ systemd-analyze compare-versions 1 ge 2; echo $? 1
## `systemd-analyze verify FILE...` This command will load unit files and print warnings if any errors are detected. Files specified on the command line will be loaded, but also any other units referenced by them. A unit's name on disk can be overridden by specifying an alias after a colon; see below for an example. The full unit search path is formed by combining the directories for all command line arguments, and the usual unit load paths. The variable `$SYSTEMD_UNIT_PATH` is supported, and may be used to replace or augment the compiled in set of unit load paths; see `systemd.unit(5)`. All units files present in the directories containing the command line arguments will be used in preference to the other paths. If a template unit without an instance name is specified (e.g. `foo@.service`), `test_instance` will be used as the instance name, which can be controlled by `--instance=` option. The following errors are currently detected: - unknown sections and directives, - missing dependencies which are required to start the given unit, - man pages listed in `Documentation=` which are not found in the system, - commands listed in `ExecStart=` and similar which are not found in the system or not executable.
Misspelt directives
$ cat ./user.slice [Unit] WhatIsThis=11 Documentation=man:nosuchfile(1) Requires=different.service [Service] Description=x $ systemd-analyze verify ./user.slice [./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit' [./user.slice:13] Unknown section 'Service'. Ignoring. Error: org.freedesktop.systemd1.LoadFailed: Unit different.service failed to load: No such file or directory. Failed to create user.slice/start: Invalid argument user.slice: man nosuchfile(1) command failed with code 16
Missing service units
$ tail ./a.socket ./b.socket ==> ./a.socket <== [Socket] ListenStream=100 ==> ./b.socket <== [Socket] ListenStream=100 Accept=yes $ systemd-analyze verify ./a.socket ./b.socket Service a.service not loaded, a.socket cannot be started. Service b@0.service not loaded, b.socket cannot be started.
Aliasing a unit
$ cat /tmp/source [Unit] Description=Hostname printer [Service] Type=simple ExecStart=/usr/bin/echo %H MysteryKey=true $ systemd-analyze verify /tmp/source Failed to prepare filename /tmp/source: Invalid argument $ systemd-analyze verify /tmp/source:alias.service alias.service:7: Unknown key name 'MysteryKey' in section 'Service', ignoring.
## `systemd-analyze security UNIT...` This command analyzes the security and sandboxing settings of one or more specified service units. If at least one unit name is specified the security settings of the specified service units are inspected and a detailed analysis is shown. If no unit name is specified, all currently loaded, long-running service units are inspected and a terse table with results shown. The command checks for various security-related service settings, assigning each a numeric "exposure level" value, depending on how important a setting is. It then calculates an overall exposure level for the whole unit, which is an estimation in the range 0.0…10.0 indicating how exposed a service is security-wise. High exposure levels indicate very little applied sandboxing. Low exposure levels indicate tight sandboxing and strongest security restrictions. Note that this only analyzes the per-service security features systemd itself implements. This means that any additional security mechanisms applied by the service code itself are not accounted for. The exposure level determined this way should not be misunderstood: a high exposure level neither means that there is no effective sandboxing applied by the service code itself, nor that the service is actually vulnerable to remote or local attacks. High exposure levels do indicate however that most likely the service might benefit from additional settings applied to them. Please note that many of the security and sandboxing settings individually can be circumvented — unless combined with others. For example, if a service retains the privilege to establish or undo mount points many of the sandboxing options can be undone by the service code itself. Due to that is essential that each service uses the most comprehensive and strict sandboxing and security settings possible. The tool will take into account some of these combinations and relationships between the settings, but not all. Also note that the security and sandboxing settings analyzed here only apply to the operations executed by the service code itself. If a service has access to an IPC system (such as D-Bus) it might request operations from other services that are not subject to the same restrictions. Any comprehensive security and sandboxing analysis is hence incomplete if the IPC access policy is not validated too.
Analyze `systemd-logind.service`
$ systemd-analyze security --no-pager systemd-logind.service NAME DESCRIPTION EXPOSURE ✗ PrivateNetwork= Service has access to the host's network 0.5 ✗ User=/DynamicUser= Service runs as root user 0.4 ✗ DeviceAllow= Service has no device ACL 0.2 ✓ IPAddressDeny= Service blocks all IP address ranges ... → Overall exposure level for systemd-logind.service: 4.1 OK 🙂
## `systemd-analyze inspect-elf FILE...` This command will load the specified files, and if they are ELF objects (executables, libraries, core files, etc.) it will parse the embedded packaging metadata, if any, and print it in a table or json format. See the [ Package Metadata for Executable Files](https://systemd.io/PACKAGE_METADATA_FOR_EXECUTABLE_FILES/) document for more information.
Print information about a core file as JSON
$ systemd-analyze inspect-elf --json=pretty \ core.fsverity.1000.f77dac5dc161402aa44e15b7dd9dcf97.58561.1637106137000000 { "elfType" : "coredump", "elfArchitecture" : "AMD x86-64", "/home/bluca/git/fsverity-utils/fsverity" : { "type" : "deb", "name" : "fsverity-utils", "version" : "1.3-1", "buildId" : "7c895ecd2a271f93e96268f479fdc3c64a2ec4ee" }, "/home/bluca/git/fsverity-utils/libfsverity.so.0" : { "type" : "deb", "name" : "fsverity-utils", "version" : "1.3-1", "buildId" : "b5e428254abf14237b0ae70ed85fffbb98a78f88" } }
## `systemd-analyze dlopen-metadata FILE` This command will load the specified file, and if it is an ELF object (executables, libraries, core files, etc.) it will parse the embedded dlopen metadata, if any, and print it in a table or json format. See the [ dlopen() Metadata for ELF Files](https://systemd.io/ELF_DLOPEN_METADATA/) document for more information. ## `systemd-analyze fdstore UNIT...` Lists the current contents of the specified service unit's file descriptor store. This shows names, inode types, device numbers, inode numbers, paths and open modes of the open file descriptors. The specified units must have `FileDescriptorStoreMax=` enabled, see `systemd.service(5)` for details.
Table output
$ systemd-analyze fdstore systemd-journald.service FDNAME TYPE DEVNO INODE RDEVNO PATH FLAGS stored sock 0:8 4218620 - socket:[4218620] ro stored sock 0:8 4213198 - socket:[4213198] ro stored sock 0:8 4213190 - socket:[4213190] ro …
Note: the "DEVNO" column refers to the major/minor numbers of the device node backing the file system the file descriptor's inode is on. The "RDEVNO" column refers to the major/minor numbers of the device node itself if the file descriptor refers to one. Compare with corresponding `.st_dev` and `.st_rdev` fields in `struct stat` (see `stat(2)` for details). The listed inode numbers in the "INODE" column are on the file system indicated by "DEVNO". ## `systemd-analyze image-policy POLICY…` This command analyzes the specified image policy string, as per `systemd.image-policy(7)`. The policy is normalized and simplified. For each currently defined partition identifier (as per the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)) the effect of the image policy string is shown in tabular form.
Example Output
$ systemd-analyze image-policy swap=encrypted:usr=read-only-on+verity:root=encrypted Analyzing policy: root=encrypted:usr=verity+read-only-on:swap=encrypted Long form: root=encrypted:usr=verity+read-only-on:swap=encrypted:=unused+absent PARTITION MODE READ-ONLY GROWFS root encrypted - - usr verity yes - home ignore - - srv ignore - - esp ignore - - xbootldr ignore - - swap encrypted - - root-verity ignore - - usr-verity unprotected yes - root-verity-sig ignore - - usr-verity-sig ignore - - tmp ignore - - var ignore - - default ignore - -
## `systemd-analyze has-tpm2` Reports whether the system is equipped with a usable TPM2 device. If a TPM2 device has been discovered, is supported, and is being used by firmware, by the OS kernel drivers and by userspace (i.e. systemd) this prints `yes` and exits with exit status zero. If no such device is discovered/supported/used, prints `no`. Otherwise, prints `partial`. In either of these two cases exits with non-zero exit status. It also shows five lines indicating separately whether firmware, drivers, the system, the kernel and libraries discovered/support/use TPM2. Currently, required libraries are `libtss2-esys.so.0`, `libtss2-rc.so.0`, and `libtss2-mu.so.0`. The requirement may be changed in the future release. Note, this checks for TPM 2.0 devices only, and does not consider TPM 1.2 at all. Combine with `--quiet` to suppress the output.
Example Output
yes +firmware +driver +system +subsystem +libraries +libtss2-esys.so.0 +libtss2-rc.so.0 +libtss2-mu.so.0
## `systemd-analyze identify-tpm2` Shows vendor information about the TPM 2.0 device discovered.
Example Output
Family Indicator: 2.0 Level: 0 Revision: 1.59 Specification Date: Mon 2023-01-09 Manufacturer: STM Vendor String: ST33KTPM2XSPI Firmware Version: 9.258 Modalias String: fi2.0:lv0:rv1.59:sy2023:sd9:mfSTM:vsST33KTPM2XSPI:ty0:fw9.258.0:
## `systemd-analyze pcrs PCR…` This command shows the known TPM2 PCRs along with their identifying names and current values.
Example Output
$ systemd-analyze pcrs NR NAME SHA256 0 platform-code bcd2eb527108bbb1f5528409bcbe310aa9b74f687854cc5857605993f3d9eb11 1 platform-config b60622856eb7ce52637b80f30a520e6e87c347daa679f3335f4f1a600681bb01 2 external-code 1471262403e9a62f9c392941300b4807fbdb6f0bfdd50abfab752732087017dd 3 external-config 3d458cfe55cc03ea1f443f1562beec8df51c75e14a9fcf9a7234a13f198e7969 4 boot-loader-code 939f7fa1458e1f7ce968874d908e524fc0debf890383d355e4ce347b7b78a95c 5 boot-loader-config 864c61c5ea5ecbdb6951e6cb6d9c1f4b4eac79772f7fe13b8bece569d83d3768 6 - 3d458cfe55cc03ea1f443f1562beec8df51c75e14a9fcf9a7234a13f198e7969 7 secure-boot-policy 9c905bd9b9891bfb889b90a54c4b537b889cfa817c4389cc25754823a9443255 8 - 0000000000000000000000000000000000000000000000000000000000000000 9 kernel-initrd 9caa29b128113ef42aa53d421f03437be57211e5ebafc0fa8b5d4514ee37ff0c 10 ima 5ea9e3dab53eb6b483b6ec9e3b2c712bea66bca1b155637841216e0094387400 11 kernel-boot 0000000000000000000000000000000000000000000000000000000000000000 12 kernel-config 627ffa4b405e911902fe1f1a8b0164693b31acab04f805f15bccfe2209c7eace 13 sysexts 0000000000000000000000000000000000000000000000000000000000000000 14 shim-policy 0000000000000000000000000000000000000000000000000000000000000000 15 system-identity 0000000000000000000000000000000000000000000000000000000000000000 16 debug 0000000000000000000000000000000000000000000000000000000000000000 17 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff 18 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff 19 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff 20 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff 21 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff 22 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff 23 application-support 0000000000000000000000000000000000000000000000000000000000000000
## `systemd-analyze nvpcrs NVPCR…` This command shows the known TPM2 NvPCRs (additional PCRs stored in TPM2 NV indexes) along with their identifying names and current values.
Example Output
$ systemd-analyze nvpcrs NAME NVINDEX VALUE cryptsetup 0x1d10201 f400543943cc7215557ce672872ace5382e6d53177cc459078ba9277e41588d9 hardware 0x1d10200 e155474936d7d74c893e6ece1099a2311d572cf23becea159dabf282db754284
## `systemd-analyze srk >FILE` This command reads the Storage Root Key (SRK) from the TPM2 device, and writes it in marshalled TPM2B_PUBLIC format to stdout. The output is non-printable data, so it should be redirected to a file or into a pipe.
Save the Storage Root Key to `srk.tpm2b_public`
systemd-analyze srk >srk.tpm2b_public
## `systemd-analyze architectures NAME...` Lists all known CPU architectures, and which ones are native. The listed architecture names are those `ConditionArchitecture=` supports, see `systemd.unit(5)` for details. If architecture names are specified only those specified are listed.
Table output
$ systemd-analyze architectures NAME SUPPORT alpha foreign arc foreign arc-be foreign arm foreign arm64 foreign … sparc foreign sparc64 foreign tilegx foreign x86 secondary x86-64 native
## `systemd-analyze cpu-features NAME...` Lists all known CPU features for the system's CPU architecture, indicating which of them are supported. The listed feature names are those understood by `ConditionCPUFeature=`; see `systemd.unit(5)` for details. If one or more feature names are specified, only those are listed. The command is currently supported only on arm64, x86, and x86_64 systems.
Table output on an x86_64 system
$ systemd-analyze cpu-features NAME SUPPORT abm ✓ adx ✓ aes ✓ apic ✓ avx ✓ avx2 ✓ …
## `systemd-analyze smbios11` Shows a list of SMBIOS Type \#11 strings passed to the system. Also see `smbios-type-11(7)`.
Example output
$ systemd-analyze smbios11 io.systemd.stub.kernel-cmdline-extra=console=ttyS0 io.systemd.credential.binary:ssh.ephemeral-authorized_keys-all=c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTVBQUFBSURGd20xbFp4WlRGclJteG9ZQlozOTYzcE1uYlJCaDMwM1MxVXhLSUM2NmYgbGVubmFydEB6ZXRhCg== io.systemd.credential:vmm.notify_socket=vsock-stream:2:254570042 3 SMBIOS Type #11 strings passed.
## `systemd-analyze chid` Shows a list of Computer Hardware IDs (CHIDs) of the local system. These IDs identify the system's computer hardware, based on SMBIOS data. See [Using Computer Hardware IDs (CHIDs)](https://learn.microsoft.com/en-us/windows-hardware/drivers/dashboard/using-chids) for details about CHIDs.
Example output
$ systemd-analyze chid TYPE INPUT CHID 3 MFPSmp 520537c0-3b59-504f-b062-9682ea236b21 4 MFPS-- edf05dc8-a53d-5b2c-8023-630bca2a2463 5 MFP--- ebc6a4d9-ec48-537a-916b-c69fa4fdd814 6 M--Smp 5ebe4bba-f598-5e90-9ff2-9fd0d3211465 7 M--S-- 1a3fb835-b42a-5f9c-a38c-eff5bfd5c41d 8 M-P-mp 2a831dce-8163-5bad-8406-435b8c752dd8 9 M-P--- 7c21c878-4a75-50f7-9816-21e811588da0 10 MF--mp 9a003537-bcc5-500e-b10a-8d8892e4fc64 11 MF---- bb9122bb-8a5c-50d2-a742-a85beb719909 13 M---mp bfc36935-5032-5987-a0a3-6311f01de33a LEGEND: M → sys_vendor (LENOVO) ┄ F → product_family (ThinkPad X1 Carbon Gen 9) ┄ P → product_name (20XW0055GE) S → product_sku (LENOVO_MT_20XW_BU_Think_FM_ThinkPad X1 Carbon Gen 9) ┄ m → board_vendor (LENOVO) p → board_name (20XW0055GE)
## `systemd-analyze transient-settings TYPE...` Lists properties that can be set for various unit types via command line interfaces, in particular `systemctl(1)` `set-property` and `--property=`/`--automount-property=` options in `systemd-run(1)`, `systemd-nspawn(1)`, and `systemd-mount(1)`. Those assignments are possible for a subset of the properties that can be set in config files, see `systemd.unit(5)`, `systemd.exec(5)`, `systemd.resource-control(5)`, and the other unit-type-specific pages. The \ argument must be a unit type ("service", "socket", …). The properties that apply to the specific types are listed. Note: D-Bus properties documented in `org.freedesktop.systemd1(5)` form a partially overlapping set with the lists generated by this command. Many D-Bus properties and transient settings share the same names, but for example, `LogRateLimitIntervalSec=` is described in `systemd.exec(5)` and would be listed by this command, but the corresponding D-Bus property described in `systemd.exec(5)` is `LogRateLimitIntervalUSec`. This verb is intended primarily for programmatic generation of shell completions. ## `systemd-analyze unit-shell SERVICE command...` The given command runs on the namespace of the specified running service. If no command is given, spawn and attach a shell with the namespace to the service.
Example output
$ systemd-analyze unit-shell systemd-resolved.service ls bin dev etc home lib lib64 lost+found mnt proc run srv tmp var vmlinuz.old boot efi exitrd init lib32 libx32 media opt root sbin sys usr vmlinuz work
## `systemd-analyze unit-gdb SERVICE` Spawn and attach a debugger to the given service. By default, `gdb(1)` will be used. This may be changed using the `--debugger=` option or the `$SYSTEMD_DEBUGGER` environment variable. Use the `--debugger-arguments=` option to pass extra command line arguments to the debugger and quote as appropriate when \ contain whitespace (See Example).
$ systemd-analyze --debugger-arguments="-batch -ex 'info all-registers'" unit-gdb systemd-oomd.service
# Options The following options are understood: `--system` Operates on the system systemd instance. This is the implied default. `--user` Operates on the user systemd instance. `--global` Operates on the system-wide configuration for user systemd instance. `--order`; `--require` When used in conjunction with the `dot` command (see above), selects which dependencies are shown in the dependency graph. If `--order` is passed, only dependencies of type `After=` or `Before=` are shown. If `--require` is passed, only dependencies of type `Requires=`, `Requisite=`, `BindsTo=`, `Wants=`, and `Conflicts=` are shown. If neither is passed, this shows dependencies of all these types. `--from-pattern=`; `--to-pattern=` When used in conjunction with the `dot` command (see above), this selects which relationships are shown in the dependency graph. Both options require a `glob(7)` pattern as an argument, which will be matched against the left-hand and the right-hand, respectively, nodes of a relationship. Each of these can be used more than once, in which case the unit name must match one of the values. When tests for both sides of the relation are present, a relation must pass both tests to be shown. When patterns are also specified as positional arguments, they must match at least one side of the relation. In other words, patterns specified with those two options will trim the list of edges matched by the positional arguments, if any are given, and fully determine the list of edges shown otherwise. `--fuzz=timespan` When used in conjunction with the `critical-chain` command (see above), also show units, which finished \ earlier, than the latest unit in the same level. The unit of \ is seconds unless specified with a different unit, e.g. "50ms". `--man=no` Do not invoke `man(1)` to verify the existence of man pages listed in `Documentation=`. `--generators` Invoke unit generators, see `systemd.generator(7)`. Some generators require root privileges. Under a normal user, running with generators enabled will generally result in some warnings. `--instance=NAME` Specifies fallback instance name for template units. This will be used when one or more template units without an instance name (e.g. `foo@.service`) specified for `systemd-analyze condition` with `--unit=`, `systemd-analyze security`, and `systemd-analyze verify`. If unspecified, `test_instance` will be used. `--recursive-errors=MODE` Control verification of units and their dependencies and whether `systemd-analyze verify` exits with a non-zero process exit status or not. With `yes`, return a non-zero process exit status when warnings arise during verification of either the specified unit or any of its associated dependencies. With `no`, return a non-zero process exit status when warnings arise during verification of only the specified unit. With `one`, return a non-zero process exit status when warnings arise during verification of either the specified unit or its immediate dependencies. If this option is not specified, zero is returned as the exit status regardless whether warnings arise during verification or not. `--root=PATH` With `cat-config`, `verify`, `condition`, `unit-gdb`, and `security` when used with `--offline=`, operate on files underneath the specified root path \. `--image=PATH` With `cat-config`, `verify`, `condition` and `security` when used with `--offline=`, operate on files inside the specified image path \. `--offline=BOOL` With `security`, perform an offline security review of the specified unit files, i.e. does not have to rely on PID 1 to acquire security information for the files like the `security` verb when used by itself does. This means that `--offline=` can be used with `--root=` and `--image=` as well. If a unit's overall exposure level is above that set by `--threshold=` (default value is 100), `--offline=` will return an error. `--profile=PATH` With `security` `--offline=`, takes into consideration the specified portable profile when assessing unit settings. The profile can be passed by name, in which case the well-known system locations will be searched, or it can be the full path to a specific drop-in file. `--threshold=NUMBER` With `security`, allow the user to set a custom value to compare the overall exposure level with, for the specified unit files. If a unit's overall exposure level, is greater than that set by the user, `security` will return an error. `--threshold=` can be used with `--offline=` as well and its default value is 100. `--security-policy=PATH` With `security`, allow the user to define a custom set of requirements formatted as a JSON file against which to compare the specified unit file(s) and determine their overall exposure level to security threats. | Assessment Test Identifier | |----------------------------------------------------------| | UserOrDynamicUser | | SupplementaryGroups | | PrivateMounts | | PrivateDevices | | PrivateTmp | | PrivateNetwork | | PrivateUsers | | ProtectControlGroups | | ProtectKernelModules | | ProtectKernelTunables | | ProtectKernelLogs | | ProtectClock | | ProtectHome | | ProtectHostname | | ProtectSystem | | RootDirectoryOrRootImage | | LockPersonality | | MemoryDenyWriteExecute | | NoNewPrivileges | | CapabilityBoundingSet_CAP_SYS_ADMIN | | CapabilityBoundingSet_CAP_SET_UID_GID_PCAP | | CapabilityBoundingSet_CAP_SYS_PTRACE | | CapabilityBoundingSet_CAP_SYS_TIME | | CapabilityBoundingSet_CAP_NET_ADMIN | | CapabilityBoundingSet_CAP_SYS_RAWIO | | CapabilityBoundingSet_CAP_SYS_MODULE | | CapabilityBoundingSet_CAP_AUDIT | | CapabilityBoundingSet_CAP_SYSLOG | | CapabilityBoundingSet_CAP_SYS_NICE_RESOURCE | | CapabilityBoundingSet_CAP_MKNOD | | CapabilityBoundingSet_CAP_CHOWN_FSETID_SETFCAP | | CapabilityBoundingSet_CAP_DAC_FOWNER_IPC_OWNER | | CapabilityBoundingSet_CAP_KILL | | CapabilityBoundingSet_CAP_NET_BIND_SERVICE_BROADCAST_RAW | | CapabilityBoundingSet_CAP_SYS_BOOT | | CapabilityBoundingSet_CAP_MAC | | CapabilityBoundingSet_CAP_LINUX_IMMUTABLE | | CapabilityBoundingSet_CAP_IPC_LOCK | | CapabilityBoundingSet_CAP_SYS_CHROOT | | CapabilityBoundingSet_CAP_BLOCK_SUSPEND | | CapabilityBoundingSet_CAP_WAKE_ALARM | | CapabilityBoundingSet_CAP_LEASE | | CapabilityBoundingSet_CAP_SYS_TTY_CONFIG | | CapabilityBoundingSet_CAP_BPF | | UMask | | KeyringMode | | ProtectProc | | ProcSubset | | NotifyAccess | | RemoveIPC | | Delegate | | RestrictRealtime | | RestrictSUIDSGID | | RestrictNamespaces_user | | RestrictNamespaces_mnt | | RestrictNamespaces_ipc | | RestrictNamespaces_pid | | RestrictNamespaces_cgroup | | RestrictNamespaces_uts | | RestrictNamespaces_net | | RestrictAddressFamilies_AF_INET_INET6 | | RestrictAddressFamilies_AF_UNIX | | RestrictAddressFamilies_AF_NETLINK | | RestrictAddressFamilies_AF_PACKET | | RestrictAddressFamilies_OTHER | | SystemCallArchitectures | | SystemCallFilter_swap | | SystemCallFilter_obsolete | | SystemCallFilter_clock | | SystemCallFilter_cpu_emulation | | SystemCallFilter_debug | | SystemCallFilter_mount | | SystemCallFilter_module | | SystemCallFilter_raw_io | | SystemCallFilter_reboot | | SystemCallFilter_privileged | | SystemCallFilter_resources | | IPAddressDeny | | DeviceAllow | | AmbientCapabilities | Accepted Assessment Test Identifiers See example "JSON Policy" below. `--json=MODE` With the `security` command, generate a JSON formatted output of the security analysis table. The format is a JSON array with objects containing the following fields: `set` which indicates if the setting has been enabled or not, `name` which is what is used to refer to the setting, `json_field` which is the JSON compatible identifier of the setting, `description` which is an outline of the setting state, and `exposure` which is a number in the range 0.0…10.0, where a higher value corresponds to a higher security threat. The JSON version of the table is printed to standard output. The \ passed to the option can be one of three: `off` which is the default, `pretty` and `short` which respectively output a prettified or shorted JSON version of the security table. With the `plot` command, generate a JSON formatted output of the raw time data. The format is a JSON array with objects containing the following fields: `name` which is the unit name, `activated` which is the time after startup the service was activated, `activating` which is how long after startup the service was initially started, `time` which is how long the service took to activate from when it was initially started, `deactivated` which is the time after startup that the service was deactivated, `deactivating` which is the time after startup that the service was initially told to deactivate. `--iterations=NUMBER` When used with the `calendar` command, show the specified number of iterations the specified calendar expression will elapse next. Defaults to 1. `--base-time=TIMESTAMP` When used with the `calendar` command, show next iterations relative to the specified point in time. If not specified, defaults to the current time. `--unit=UNIT` When used with the `condition` command, evaluate all the `Condition*=...` and `Assert*=...` assignments in the specified unit file. The full unit search path is formed by combining the directories for the specified unit with the usual unit load paths. The variable `$SYSTEMD_UNIT_PATH` is supported, and may be used to replace or augment the compiled in set of unit load paths; see `systemd.unit(5)`. All units files present in the directory containing the specified unit will be used in preference to the other paths. If a template unit without an instance name is specified (e.g. `foo@.service`), `test_instance` will be used as the instance name, which can be controlled by `--instance=` option. `--table` When used with the `plot` command, the raw time data is output in a table. `--no-legend` When used with the `plot` command in combination with either `--table` or `--json=`, no legends or hints are included in the output. `-q`; `--quiet` Suppress hints and other non-essential output. `--tldr` With `cat-config`, only print the "interesting" parts of the configuration files, skipping comments and empty lines and section headers followed only by comments and empty lines. `--scale-svg=FACTOR` When used with the `plot` command, the x-axis of the plot can be stretched by FACTOR (default: 1.0). `--detailed` When used with the `plot` command, activation timestamps details can be seen in SVG plot. `--drm-device=PATH` When provided with the `chid` command, use this sysfs path to a DRM device to fetch EDID from. Example: `/sys/class/drm/card1-HDMI-A-1/` `--debugger=DEBUGGER` Use the given debugger for the `unit-gdb` command. If not given and `$SYSTEMD_DEBUGGER` is unset, then `gdb(1)` will be used. `-A` \; `--debugger-arguments=ARGS` Pass the given \ as extra command line arguments to the debugger. # Exit status For most verbs, `0` is returned on success, and a non-zero failure code otherwise. For the verb `compare-versions`, in the two-argument form, `12`, `0`, or `11` are returned if the second version string is respectively larger than, equal to, or smaller than the first. In the three-argument form, `0` or `1` are returned when the condition is respectively true or false. For the verb `has-tpm2`, `0` is returned if a TPM2 device is discovered, supported, and used by firmware, driver, and userspace (i.e. `systemd`). Otherwise, the OR combination of the value `1` (in case firmware support is missing), `2` (in case driver support is missing), and `4` (in case userspace support is missing). If no TPM2 support is available at all, value `7` is hence returned. # Examples
JSON Policy
The JSON file passed as a path parameter to `--security-policy=` has a top-level JSON object, with keys being the assessment test identifiers mentioned above. The values in the file should be JSON objects with one or more of the following fields: `description_na` (string), `description_good` (string), `description_bad` (string), `weight` (unsigned integer), and `range` (unsigned integer). If any of these fields corresponding to a specific id of the unit file is missing from the JSON object, the default built-in field value corresponding to that same id is used for security analysis as default. The weight and range fields are used in determining the overall exposure level of the unit files: the value of each setting is assigned a badness score, which is multiplied by the policy weight and divided by the policy range to determine the overall exposure that the setting implies. The computed badness is summed across all settings in the unit file, normalized to the 1…100 range, and used to determine the overall exposure level of the unit. By allowing users to manipulate these fields, the 'security' verb gives them the option to decide for themself which ids are more important and hence should have a greater effect on the exposure level. A weight of `0` means the setting will not be checked. { "PrivateDevices": { "description_good": "Service has no access to hardware devices", "description_bad": "Service potentially has access to hardware devices", "weight": 1000, "range": 1 }, "PrivateMounts": { "description_good": "Service cannot install system mounts", "description_bad": "Service may install system mounts", "weight": 1000, "range": 1 }, "PrivateNetwork": { "description_good": "Service has no access to the host's network", "description_bad": "Service has access to the host's network", "weight": 2500, "range": 1 }, "PrivateTmp": { "description_good": "Service has no access to other software's temporary files", "description_bad": "Service has access to other software's temporary files", "weight": 1000, "range": 1 }, "PrivateUsers": { "description_good": "Service does not have access to other users", "description_bad": "Service has access to other users", "weight": 1000, "range": 1 } }
# See Also `systemd(1)`, `systemctl(1)` # systemd-ask-password-console.service systemd systemd-ask-password-console.service 8 systemd-ask-password-console.service systemd-ask-password-console.path systemd-ask-password-wall.service systemd-ask-password-wall.path Query the user for system passwords on the console and via wall `systemd-ask-password-console.service`, `systemd-ask-password-console.path`, `systemd-ask-password-wall.service`, `systemd-ask-password-wall.path` # Description `systemd-ask-password-console.service` is a system service that queries the user for system passwords (such as hard disk encryption keys and SSL certificate passphrases) on the console. It is intended to be used during boot to ensure proper handling of passwords necessary for boot. `systemd-ask-password-wall.service` is a system service that informs all logged in users for system passwords via `wall(1)`. It is intended to be used after boot to ensure that users are properly notified. See the [developer documentation](https://systemd.io/PASSWORD_AGENTS/) for more information about the system password logic. Note that these services invoke `systemd-tty-ask-password-agent(1)` with either the `--watch --console` or `--watch --wall` command line parameters. # See Also `systemd(1)`, `systemd-tty-ask-password-agent(1)`, `wall(1)` # systemd-ask-password systemd systemd-ask-password 1 systemd-ask-password Query the user for a system password systemd-ask-password OPTIONS MESSAGE # Description `systemd-ask-password` may be used to query a password or passphrase interactively from the user, using a question prompt specified on the command line. When run from a TTY it will query a password on the TTY and print it to standard output. When run with no TTY or with `--no-tty` it will use a system-wide or per-user agent-based query mechanism, which allows active users to respond via several agents, listed below. The purpose of this tool is to query system-wide or per-user passwords — the former includes passwords possibly not associated to a specific user account. Examples include: unlocking encrypted hard disks when they are plugged in or at boot, entering an SSL certificate passphrase for web and VPN servers. Existing system-level agents are: - A boot-time password agent asking the user for passwords using `plymouth(8)`, - A boot-time password agent querying the user directly on the console — `systemd-ask-password-console.service(8)`, - An agent requesting password input via a `wall(1)` message — `systemd-ask-password-wall.service(8)`, - A TTY agent that is temporarily spawned during `systemctl(1)` invocations, - A command line agent which can be started temporarily to process queued password requests — `systemd-tty-ask-password-agent --query`. Answering system-wide password queries is a privileged operation, hence all the agents listed above (except for the last one), run as privileged system services. The last one also needs elevated privileges, so should be run through `run0(1)` or similar. Additional password agents may be implemented according to the [systemd Password Agent Specification](https://systemd.io/PASSWORD_AGENTS/). If a password is queried on a TTY, the user may press TAB to hide the asterisks normally shown for each character typed. Pressing Backspace as first key achieves the same effect. # Options The following options are understood: `--icon=` Specify an icon name alongside the password query, which may be used in all agents supporting graphical display. The icon name should follow the [XDG Icon Naming Specification](https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html). `--id=` Specify an identifier for this password query. This identifier is freely choosable and allows recognition of queries by involved agents. It should include the subsystem doing the query and the specific object the query is done for. Example: `--id=cryptsetup:/dev/sda5`. `--keyname=` Configure a kernel keyring key name to use as cache for the password. If set, then the tool will try to push any collected passwords into the kernel keyring of the root user, as a key of the specified name. If combined with `--accept-cached`, it will also try to retrieve such cached passwords from the key in the kernel keyring instead of querying the user right away. By using this option, the kernel keyring may be used as effective cache to avoid repeatedly asking users for passwords, if there are multiple objects that may be unlocked with the same password. The cached key will have a timeout of 2.5min set, after which it will be purged from the kernel keyring. Note that it is possible to cache multiple passwords under the same keyname, in which case they will be stored as `NUL`-separated list of passwords. Use `keyctl(1)` to access the cached key via the kernel keyring directly. Example: `--keyname=cryptsetup` `--credential=` Configure a credential to read the password from – if it exists. This may be used in conjunction with the `ImportCredential=`, `LoadCredential=` and `SetCredential=` settings in unit files. See `systemd.exec(5)` for details. If not specified, defaults to `password`. This option has no effect if no credentials directory is passed to the program (i.e. `$CREDENTIALS_DIRECTORY` is not set) or if the no credential of the specified name exists. `--timeout=` Specify the query timeout in seconds. Defaults to 90s. A timeout of 0 waits indefinitely. `--echo=yes|no|masked` Controls whether to echo user input. Takes a boolean or the special string `masked`, the default being the latter. If enabled the typed characters are echoed literally, which is useful for prompting for usernames and other non-protected data. If disabled the typed characters are not echoed in any form, the user will not get feedback on their input. If set to `masked`, an asterisk (`*`) is echoed for each character typed. In this mode, if the user hits the tabulator key (`↹`), echo is turned off. (Alternatively, if the user hits the backspace key (`⌫`) while no data has been entered otherwise, echo is turned off, too). `--echo`; `-e` Equivalent to `--echo=yes`, see above. `--emoji=yes|no|auto` Controls whether or not to prefix the query with a lock and key emoji (🔐), if the TTY settings permit this. The default is `auto`, which defaults to `yes`, unless `--echo=yes` is given. `--no-tty` Never ask for password on current TTY even if one is available. Always use agent system. `--accept-cached` If passed, accept cached passwords, i.e. passwords previously entered. `--multiple` When used in conjunction with `--accept-cached` accept multiple passwords. This will output one password per line. `--no-output` Do not print passwords to standard output. This is useful if you want to store a password in kernel keyring with `--keyname=` but do not want it to show up on screen or in logs. `-n` By default, when the acquired password is written to standard output it is suffixed by a newline character. This may be turned off with the `-n` switch, similarly to the switch of the same name of the `echo(1)` command. `--user`; `--system` Controls whether to query the system-wide or the per-user password agents. By default if invoked privileged the system-wide agents are queried, otherwise the per-user ones. These options allow one to override this automatic behaviour. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-ask-password-console.service(8)`, `systemd-tty-ask-password-agent(1)`, `keyctl(1)`, `plymouth(8)`, `wall(1)` # systemd-backlight@.service systemd systemd-backlight@.service 8 systemd-backlight@.service systemd-backlight Load and save the display backlight brightness at boot and shutdown `systemd-backlight@.service` `/usr/lib/systemd/systemd-backlight` save \[backlight\|leds\]:DEVICE `/usr/lib/systemd/systemd-backlight` load \[backlight\|leds\]:DEVICE # Description `systemd-backlight@.service` is a service that restores the brightness of a display backlight or LED (e.g. keyboard backlight) device at early boot, and saves it at shutdown. The brightness is stored in `/var/lib/systemd/backlight/`. On restoring brightness of a display backlight device, `systemd-backlight` reads `ID_BACKLIGHT_CLAMP` udev property, that takes a boolean value or a percentage (needs to be suffixed with `%`, e.g. `30%`). When a percentage is specified, the saved brightness is clamped to a value of at least 1 or the specified percentage of the maximum brightness, whichever is greater. When unset or set to true, the brightness is clamped in the same way with percentage 5%. When false, the saved brightness will not be clamped, and loaded as is. On restoring brightness of a LED device, `systemd-backlight` reads `ID_LEDS_CLAMP` udev property, that also takes a boolean value or a percentage. When a percentage is specified, the saved brightness is clamped to the specified percentage of the maximum brightness. When set to true, the brightness is clamped in the same way with percentage 5%. When unset or set to false, the saved brightness will not be clamped, and loaded as is. # Kernel Command Line `systemd-backlight` understands the following kernel command line parameter: `systemd.restore_state=` Takes a boolean argument. Defaults to `1`. If `0`, does not restore the backlight settings on boot. However, settings will still be stored on shutdown. # See Also `systemd(1)` # systemd-battery-check.service systemd systemd-battery-check.service 8 systemd-battery-check.service systemd-battery-check Check battery level whether there's enough charge, and power off if not `systemd-battery-check.service` /usr/lib/systemd/systemd-battery-check OPTIONS # Description This service checks the presence of an external power supply and the battery level during the early boot stage to determine whether there is sufficient power to carry on with the booting process. `systemd-battery-check` returns success if the device is connected to an AC power source or if the battery charge is greater than 5%. It returns failure otherwise. # Options The following options are understood by `systemd-battery-check`: # Exit status On success (running on AC power or battery capacity greater than 5%), 0 is returned, a non-zero failure code otherwise. # Kernel Command Line The following variables are understood: `systemd.battery_check=BOOL` Takes a boolean. If specified with false, `systemd-battery-check` command will return immediately with exit status 0 without checking battery capacity and AC power existence, and the service `systemd-battery-check.service` will succeed. This may be useful when the command wrongly detects and reports battery capacity percentage or AC power existence, or when you want to boot the system forcibly. # See Also `systemd(1)` # systemd-binfmt.service systemd systemd-binfmt.service 8 systemd-binfmt.service systemd-binfmt Configure additional binary formats for executables at boot `systemd-binfmt.service` `/usr/lib/systemd/systemd-binfmt` # Description `systemd-binfmt.service` is an early boot service that registers additional binary formats for executables in the kernel. See `binfmt.d(5)` for information about the configuration of this service. # Options `--unregister` If passed, instead of registering configured binary formats in the kernel, the reverse operation is executed: all currently registered binary formats are unregistered from the kernel. # See Also `systemd(1)`, `binfmt.d(5)`, `wine(8)` # systemd-bless-boot-generator systemd systemd-bless-boot-generator 8 systemd-bless-boot-generator Pull systemd-bless-boot.service into the initial boot transaction when boot counting is in effect `/usr/lib/systemd/system-generators/systemd-bless-boot-generator` # Description `systemd-bless-boot-generator` is a generator that pulls `systemd-bless-boot.service` into the initial boot transaction when boot counting, as implemented by `systemd-boot(7)`, is enabled. `systemd-bless-boot-generator` implements `systemd.generator(7)`. # See Also `systemd(1)`, `systemd-bless-boot.service(8)`, `systemd-boot(7)` # systemd-bless-boot.service systemd systemd-bless-boot.service 8 systemd-bless-boot.service systemd-bless-boot Mark current boot process as successful `systemd-bless-boot.service` `/usr/lib/systemd/systemd-bless-boot` # Description `systemd-bless-boot.service` is a system service that marks the current boot process as successful. It's automatically pulled into the initial transaction when `systemd-bless-boot-generator(8)` detects that `systemd-boot(7)` style boot counting is used. Internally, the service operates based on the `LoaderBootCountPath` EFI variable (of the vendor UUID `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`), which is passed from the boot loader to the OS. It contains a file system path (relative to the EFI system partition) of the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) compliant boot loader entry file or unified kernel image file that was used to boot up the system. `systemd-bless-boot.service` removes the two "tries done" and "tries left" numeric boot counters from the filename, which indicates to future invocations of the boot loader that the entry has completed booting successfully at least once. (This service will hence rename the boot loader entry file or unified kernel image file on the first successful boot.) Note that if the system was booted via kexec and LUO is available and enabled, this service will skip marking the boot entry as good or bad, since kexec bypasses the EFI boot loader entirely. # Options The `/usr/lib/systemd/systemd-bless-boot` executable may also be invoked from the command line, taking one of the following command arguments: `status` The current status of the boot loader entry file or unified kernel image file is shown. This outputs one of `good`, `bad`, `indeterminate`, `clean`, `dirty`, depending on the state and previous invocations of the command. The string `indeterminate` is shown initially after boot, before it has been marked as "good" or "bad". The string `good` is shown after the boot was marked as "good" with the `good` command below, and "bad" conversely after the `bad` command was invoked. The string `clean` is returned when boot counting is currently not in effect (which includes the case where the current entry was already marked as persistently good). The string `dirty` is returned when the system is booted up with a known-bad kernel (i.e. one where the tries left counter has previously reached zero already). This command is implied if no command argument is specified. `good` When invoked, the current boot loader entry file or unified kernel image file will be marked as "good", executing the file rename operation described above. This command is intended to be invoked at the end of a successful boot. The `systemd-bless-boot.service` unit invokes this command. `bad` When called the "tries left" counter in the boot loader entry file name or unified kernel image file name is set to zero, marking the boot loader entry or kernel image as "bad", so that the boot loader will not consider it anymore on future boots (at least as long as there are other entries available that are not marked "bad" yet). This command is normally not executed, but can be used to instantly put an end to the boot counting logic if a problem is detected and persistently mark the boot entry as bad. `indeterminate` This command undoes any marking of the current boot loader entry file or unified kernel image file as good or bad. This is implemented by renaming the boot loader entry file or unified kernel image file back to the path encoded in the `LoaderBootCountPath` EFI variable. Note that operation will fail if the current kernel is not booted with boot counting enabled (i.e. if the EFI variable is not set). If the boot counter already reached zero tries left on a previous boot this operation will fail too: once an entry is marked `bad` it can only be reset to `good` again, but not to `indeterminate`. # See Also `systemd(1)`, `systemd-boot(7)`, `systemd.special(7)` # systemd-boot-check-no-failures.service systemd systemd-boot-check-no-failures.service 8 systemd-boot-check-no-failures.service systemd-boot-check-no-failures verify that the system booted up cleanly `systemd-boot-check-no-failures.service` `/usr/lib/systemd/systemd-boot-check-no-failures` # Description `systemd-boot-check-no-failures.service` is a system service that checks whether the system booted up successfully. This service implements a very minimal test only: whether there are any failed units on the system. This service is disabled by default. When enabled, it is ordered before `boot-complete.target`, thus ensuring the target cannot be reached when the system booted up with failed services. Note that due the simple nature of this check this service is probably not suitable for deployment in most scenarios. It is primarily useful only as example for developing more fine-grained checks to order before `boot-complete.target`. # See Also `systemd(1)`, `systemd.special(7)` # systemd-boot-clear-sysfail.service systemd systemd-boot-clear-sysfail.service 8 systemd-boot-clear-sysfail.service Clear LoaderEntrySysFail entry `systemd-boot-clear-sysfail.service` # Description `systemd-boot-clear-sysfail.service` is a system service that automatically clears the 'LoaderEntrySysFail' boot loader entry if the boot was successful and the 'LoaderSysFailReason' EFI variable, which indicates the reason for the system failure, is not set. The `systemd-boot-clear-sysfail.service` unit invokes the `bootctl --graceful set-sysfail ""` command, which clears the LoaderEntrySysFail entry. The service is conditionalized so that it is run only when a LoaderSysFailReason entry is not set. For further details see `bootctl(1)`, regarding the command this service invokes. # See Also `systemd(1)`, `bootctl(1)`, `systemd-boot(7)` # systemd-boot-random-seed.service systemd systemd-boot-random-seed.service 8 systemd-boot-random-seed.service Refresh boot loader random seed at boot `systemd-boot-random-seed.service` # Description `systemd-boot-random-seed.service` is a system service that automatically refreshes the boot loader random seed stored in the EFI System Partition (ESP), from the Linux kernel entropy pool. The boot loader random seed is primarily consumed and updated by `systemd-boot(7)` from the UEFI environment (or `systemd-stub(7)` if the former is not used, but the latter is), and passed as initial RNG seed to the OS. It is an effective way to ensure the OS comes up with a random pool that is fully initialized. The service also automatically generates a 'system token' to store in an EFI variable in the system's NVRAM. The boot loader may then combine the on-disk random seed and the system token by cryptographic hashing, and pass it to the OS it boots as initialization seed for its entropy pool. Note: the random seed stored in the ESP is refreshed on *every* reboot ensuring that multiple subsequent boots will boot with different seeds. On the other hand, the system token is generated randomly *once*, and then persistently stored in the system's EFI variable storage, ensuring the same disk image will not result in the same series of boot loader seed values if used on multiple systems in parallel. The `systemd-boot-random-seed.service` unit invokes the `bootctl random-seed` command, which updates the random seed in the ESP, and initializes the system token if it is not initialized yet. The service is conditionalized so that it is run only when a boot loader is used that implements the [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE). For further details see `bootctl(1)`, regarding the command this service invokes. Note the relationship between `systemd-boot-random-seed.service` and `systemd-random-seed(8)`. The former maintains the random seed consumed and updated by the boot environment (i.e. by `systemd-boot(7)` or `systemd-stub(7)`), the latter maintains a random seed consumed and updated by the OS itself. The former ensures that the OS has a filled entropy pool already during earliest boot when regular disk access is not available yet (i.e. when the OS random seed cannot be loaded yet). The latter is processed much later, once writable disk access is available. Thus it cannot be used to seed the initial boot phase, but typically has much higher quality of entropy. Both files are consumed and updated at boot, but at different times. Specifically: 1. In UEFI mode, the `systemd-boot(7)` or `systemd-stub(7)` components load the boot loader random seed from the ESP, hash it with available entropy and the system token, and then update it on disk. A derived seed is passed to the kernel which writes it to its entropy pool. 2. In userspace the `systemd-random-seed.service` service loads the OS random seed, writes it to the kernel entropy pool, and then updates it on disk with a new value derived from the kernel entropy pool. 3. In userspace the `systemd-boot-random-seed.service` service updates the boot loader random seed with a new value derived from the kernel entropy pool. This logic should ensure that the kernel's entropy pool is seeded during earliest boot already, if possible, but the highest quality entropy is propagated back to both on-disk seeds. # See Also `systemd(1)`, `random(4)`, `bootctl(1)`, `systemd-boot(7)`, `systemd-stub(7)`, `systemd-random-seed.service(8)` # systemd-boot systemd systemd-boot 7 systemd-boot sd-boot A simple UEFI boot manager # Description `systemd-boot` (short: `sd-boot`) is a simple UEFI boot manager. It provides a textual menu to select the entry to boot and an editor for the kernel command line. `systemd-boot` supports systems with UEFI firmware only. `systemd-boot` loads boot entry information from the EFI system partition (ESP), usually mounted at `/efi/`, `/boot/`, or `/boot/efi/` during OS runtime, as well as from the Extended Boot Loader partition (XBOOTLDR) if it exists (usually mounted to `/boot/`). Configuration file fragments, kernels, initrds and other EFI images to boot generally need to reside on the ESP or the Extended Boot Loader partition. Linux kernels must be built with `CONFIG_EFI_STUB` to be able to be directly executed as an EFI image. During boot `systemd-boot` automatically assembles a list of boot entries from the following sources: - Boot entries defined with [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#1 description files located in `/loader/entries/` on the ESP and the Extended Boot Loader Partition. These usually describe Linux kernel images with associated initrd images, but alternatively may also describe other arbitrary EFI executables. - Unified kernel images, [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#2, which are executable EFI binaries in `/EFI/Linux/` on the ESP and the Extended Boot Loader Partition. - The Microsoft Windows EFI boot manager, if installed. - The Apple macOS boot manager, if installed. - The EFI Shell binary, if installed. - A `Reboot Into Firmware Interface` option, if supported by the UEFI firmware. - Secure Boot variable enrollment if the UEFI firmware is in setup mode and files are provided on the ESP. `systemd-boot` supports the following features: - Basic boot manager configuration changes (such as timeout configuration, default boot entry selection, …) may be made directly from the boot loader UI at boot-time, as well as during system runtime with EFI variables. - The boot manager integrates with the `systemctl` command to implement features such as `systemctl reboot --boot-loader-entry=…` (for rebooting into a specific boot menu entry, i.e. "reboot into Windows") and `systemctl reboot --boot-loader-menu=…` (for rebooting into the boot loader menu), by implementing the [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE). See `systemctl(1)` for details. - An EFI variable set by the boot loader informs the OS about the EFI System Partition used during boot. This is then used to automatically mount the correct EFI System Partition to `/efi/` or `/boot/` during OS runtime. See `systemd-gpt-auto-generator(8)` for details. - The boot manager provides information about the boot time spent in UEFI firmware using the [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE). This information can be displayed using `systemd-analyze(1)`. - The boot manager implements boot counting and automatic fallback to older, working boot entries on failure. See [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT). - The boot manager optionally reads a random seed from the ESP partition, combines it with a 'system token' stored in a persistent EFI variable and derives a random seed to use by the OS as entropy pool initialization, providing a full entropy pool during early boot. - The boot manager allows for Secure Boot variables to be enrolled if the UEFI firmware is in setup mode. Additionally, variables can be automatically enrolled if configured. `bootctl(1)` may be used from a running system to locate the ESP and the Extended Boot Loader Partition, list available entries, and install `systemd-boot` itself. `kernel-install(8)` may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate description files compliant with the Boot Loader Specification. `systemd-stub(7)` may be used as UEFI boot stub for executed kernels, which is useful to show graphical boot splashes before transitioning into the Linux world. It is also capable of automatically picking up auxiliary credential files (for boot parameterization) and system extension images, as companion files to the booted kernel images. # Key bindings The following keys may be used in the boot menu: ↑ (Up); ↓ (Down); j; k; PageUp; PageDown; Home; End Navigate up/down in the entry list ↵ (Enter); → (Right) Boot selected entry d Make selected entry the preferred boot entry An EFI variable is set to allow this setting to persist. D Make selected entry the default boot entry An EFI variable is set to allow this setting to persist. e Edit the kernel command line for selected entry +; t Increase the timeout before default entry is booted An EFI variable is set to allow this setting to persist. -; T Decrease the timeout An EFI variable is set to allow this setting to persist. r Change screen resolution, skipping any unsupported modes. An EFI variable is set to allow this setting to persist. R Reset screen resolution to firmware or configuration file default. An EFI variable is set to allow this setting to persist. p Print status h; ?; F1 Show a help screen f Reboot into firmware interface. For compatibility with the keybindings of several firmware implementations this operation may also be reached with F2, F10, Del and Esc. Shift+o Power off the system. Shift+b Reboot the system. The following keys may be pressed during bootup or in the boot menu to directly boot a specific entry: l Linux w Windows a macOS s EFI shell 1; 2; 3; 4; 5; 6; 7; 8; 9 Boot entry number 1 … 9 The boot menu is shown when a non-zero menu timeout has been configured. If the menu timeout has been set to zero, hold down a key (space is recommended) before the boot loader initializes to bring up the boot menu. Note that depending on the firmware implementation the time window where key presses are accepted before the boot loader initializes might be short. If the window is missed, reboot and try again, possibly repeatedly pressing a suitable key; on most systems it should be possible to hit the time window after a few attempts. Keys other than the space bar may be used, except for the keys listed above. If showing the menu on demand doesn't work well, consider setting a non-zero timeout to show the boot menu unconditionally. Some desktop environments might offer an option to boot directly into the boot menu, which also avoids the problem altogether. Alternatively, use the command line `systemctl reboot --boot-loader-menu=` with a non-zero value from the shell. In the editor, most keys simply insert themselves, but the following keys may be used to perform additional actions: ← (Left); → (Right); Home; End Navigate left/right Esc; Ctrl+c Abort the edit and quit the editor Ctrl+k Clear the command line forwards Ctrl+w; Alt+Backspace Delete word backwards Ctrl+Del; Alt+d Delete word forwards ↵ (Enter) Boot entry with the edited command line Note that unless configured otherwise in the UEFI firmware, systemd-boot will use the US keyboard layout, so key labels might not match for keys like +/-. # Files The files `systemd-boot` processes generally reside on the UEFI ESP which is usually mounted to `/efi/`, `/boot/` or `/boot/efi/` during OS runtime. It also processes files on the Extended Boot Loader partition which is typically mounted to `/boot/`, if it exists. `systemd-boot` reads runtime configuration such as the boot timeout and default entry from `/loader/loader.conf` on the ESP (in combination with data read from EFI variables). See `loader.conf(5)`. Boot entry description files following the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) are read from `/loader/entries/` on the ESP and the Extended Boot Loader partition. Unified kernel boot entries following the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) are read from `/EFI/Linux/` on the ESP and the Extended Boot Loader partition. Optionally, a random seed for early boot entropy pool provisioning is stored in `/loader/random-seed` in the ESP. If the read-only file attribute is set on this file, it is neither updated nor used: a seed that cannot be updated would be identical on every boot, and hence must not be credited. The file attribute may thus be used to explicitly turn off random seed handling, for example in OS images that are replicated to multiple systems. During initialization, `systemd-boot` automatically loads all driver files placed in the `/EFI/systemd/drivers/` directory of the ESP. The files placed there must have an extension of the EFI architecture ID followed by `.efi` (e.g. for x86-64 this means a suffix of `x64.efi`). This may be used e.g. to add support for hardware not supported natively by the firmware. Enrollment of Secure Boot variables can be performed manually or automatically if files are available under `/loader/keys/NAME/{db,dbx,KEK,PK}.auth`, \ being the display name for the set of variables in the menu. If one of the sets is named `auto` then it might be enrolled automatically depending on the execution environment and the value of the `secure-boot-enroll` option. See `loader.conf(5)`. # Companion Files For Type \#1 boot loader entries (as defined in the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification)) `systemd-boot` will collect additional companion resources declared via the `extra` key in the entry, dynamically generate `cpio` initrd archives from them, and register those archives via the Linux initrd EFI protocol so that they are passed to the kernel together with the entry's own initrd. This is supported for entries referencing a Unified Kernel Image (UKI) via the `uki` or `uki-url` keys. Each `extra` key references a single regular file (relative to the root of the file system containing the entry snippet) and the key may be specified multiple times. Companion resources are recognized by file name suffix: - Files with the `.cred` suffix are packed into a `cpio` archive placed in the `/.extra/credentials/` directory of the initrd file hierarchy. This is intended to convey auxiliary, encrypted, authenticated credentials for use with `LoadCredentialEncrypted=`. See `systemd.exec(5)` and `systemd-creds(1)` for details on encrypted credentials. The generated `cpio` archive is measured into TPM PCR 12 (if a TPM is present). - Files with the `.sysext.raw` suffix are packed into a `cpio` archive placed in the `/.extra/sysext/` directory of the initrd file hierarchy. This is intended to pass additional entry-specific system extension images to the initrd. See `systemd-sysext(8)` for details on system extension images. The generated `cpio` archive is measured into TPM PCR 13 (if a TPM is present). - Files with the `.confext.raw` suffix are packed into a `cpio` archive placed in the `/.extra/confext/` directory of the initrd file hierarchy. This is intended to pass additional entry-specific configuration extension images to the initrd. See `systemd-confext(8)` for details on configuration extension images. The generated `cpio` archive is measured into TPM PCR 12 (if a TPM is present). When the booted kernel is a UKI, the `systemd-stub` UEFI stub embedded in it will combine the companion resources injected here with any companion files it itself collects from the UKI's `.extra.d/` drop-in directory and from `/loader/credentials/` and `/loader/extensions/`, so that all sources are merged uniformly into `/.extra/` in the initrd. See `systemd-stub(7)` for details. Example Type \#1 entry making use of the `extra` key: title My OS version 1.2.3 machine-id 6a9857a393724b7a981ebb5b8495b9ea uki /6a9857a393724b7a981ebb5b8495b9ea/1.2.3/img.efi extra /6a9857a393724b7a981ebb5b8495b9ea/1.2.3/foo.cred extra /6a9857a393724b7a981ebb5b8495b9ea/1.2.3/bar.sysext.raw extra /6a9857a393724b7a981ebb5b8495b9ea/1.2.3/baz.confext.raw # EFI Variables The following EFI variables are defined, and may be set or read by `systemd-boot` for communication between the boot loader and the OS. The vendor UUID `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` is used in all cases. `LoaderBootCountPath` If boot counting is enabled, contains the path to the file in whose name the boot counters are encoded. Set by the boot loader. `systemd-bless-boot.service(8)` uses this information to mark a boot as successful as determined by the successful activation of the `boot-complete.target` target unit. `LoaderConfigTimeout`; `LoaderConfigTimeoutOneShot` The menu timeout in seconds. Read by the boot loader. `LoaderConfigTimeout` is maintained persistently, while `LoaderConfigTimeoutOneShot` is a one-time override which is read once (in which case it takes precedence over `LoaderConfigTimeout`) and then removed. `LoaderConfigTimeout` may be manipulated with the t/T keys, see above. `LoaderConfigConsoleMode` The numerical menu console mode. Read by the boot loader. `LoaderConfigConsoleMode` is maintained persistently. `LoaderConfigConsoleMode` may be manipulated with the r/R keys, see above. `LoaderDevicePartUUID` Contains the partition UUID of the partition the boot loader has been started from on the current boot (usually an EFI System Partition). Set by the boot loader. (Note that `systemd-stub(7)` will set this too, if not set yet, to support systems that boot directly into a unified kernel image, bypassing any boot loader.) `systemd-gpt-auto-generator(8)` uses this information to automatically find the disk booted from, in order to discover various other partitions on the same disk automatically. `LoaderDeviceURL` If the boot loader has been invoked via network booting this variable contains the originating URL. This may be used to automatically acquire additional resources from the same source. `LoaderEntries` A list of the identifiers of all discovered boot loader entries. Set by the boot loader. `LoaderEntryPreferred`; `LoaderEntryDefault`; `LoaderEntrySysFail`; `LoaderEntryOneShot` The identifier of the default boot loader entry. Can be set in the OS and the boot loader. `LoaderEntryOneShot` sets the default entry for the next boot only, while `LoaderEntryDefault` sets it persistently for all future boots. `LoaderEntryPreferred` is like `LoaderEntryDefault` but additionally takes into account boot assessment and skips boot entries with a tries-left counter equal to zero. `bootctl(1)`'s `set-default` and `set-oneshot` commands make use of these variables. The boot loader modifies `LoaderEntryDefault` on request, when the d key is used, see above. `LoaderEntryLastBooted` The identifier of the boot loader entry last attempted. Set and read by the boot loader, only when `/loader/loader.conf` has default set to `@saved`. See `loader.conf(5)`. The boot loader will ensure `LoaderEntryLastBooted` is up-to date for every boot, updating it as needed and will omit changing it all together when `LoaderEntryOneShot` is set. The boot loader reads the variable, which takes higher priority than `LoaderEntryDefault`. The variable is ignored when `LoaderEntryOneShot` is set. `LoaderEntryLastBooted` cannot be used as indication that the last boot was successful or not. `LoaderEntrySelected` The identifier of the boot loader entry currently being booted. Set by the boot loader. `LoaderFeatures` A set of flags indicating the features the boot loader supports. Set by the boot loader. Use `bootctl(1)` to view this data. `LoaderFirmwareInfo`; `LoaderFirmwareType` Brief firmware information. Set by the boot loader. Use `bootctl(1)` to view this data. `LoaderTpm2ActivePcrBanks` Hexadecimal string representation of a bitmask with values defined by the TCG EFI Protocol Specification for TPM 2.0 as EFI_TCG2_BOOT_HASH_ALG\_\*. If no TPM2 support or no active banks were detected, will be set to `0`. Set by the boot loader. Use `systemd-analyze(1)` to view this data. `LoaderPcrSMBIOS` The PCR register index select SMBIOS structures are measured into — type 1 (system information, with the volatile "Wake-up Type" field zeroed out), type 2 (baseboard information) and type 11 (OEM strings). Formatted as decimal ASCII string (e.g. `1`). Set by the boot loader only if all of these structures were measured successfully, and remains unset otherwise. (Note that `systemd-stub` performs the same measurement when booted directly, bypassing the boot loader.) `LoaderImageIdentifier` The file system path to the EFI executable of the boot loader for the current boot, relative to the partition's root directory (i.e. relative to the partition indicated by `LoaderDevicePartUUID`, see above). Set by the boot loader. (Note that `systemd-stub` will set this too, if not set yet, to support systems that directly boot into a unified kernel image, bypassing any boot loader.) Use `bootctl(1)` to view this data. `LoaderInfo` Brief information about the boot loader. Set by the boot loader. Use `bootctl(1)` to view this data. `LoaderTimeExecUSec`; `LoaderTimeInitUSec`; `LoaderTimeMenuUsec` Information about the time spent in various parts of the boot loader. Set by the boot loader. Use `systemd-analyze(1)` to view this data. `LoaderFactoryResetVariables` A boolean, formatted as a UTF-16 string (e.g. `1`). If set to true by the OS, the boot loader will erase all EFI variables in the Boot Loader Interface vendor UUID namespace and in systemd's own vendor UUID namespace (except for `FactoryResetRequest`) on the next boot, and then reboot. Before doing so the user is asked for confirmation. This variable is typically set by `systemd-efivars-clear.service(8)` as part of a factory reset. `LoaderSystemToken` A binary random data field, that is used for generating the random seed to pass to the OS (see above). Note that this random data is generally only generated once, during OS installation, and is then never updated again. Many of these variables are defined by the [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE). # SMBIOS Type 11 Strings `systemd-boot` can be configured using SMBIOS Type 11 strings. Applicable strings consist of a name, followed by `=`, followed by the value. Unless `systemd-boot` detects it is running inside a confidential computing environment, `systemd-boot` will search the table for a string with a specific name, and if found, use its value. The following strings are read: `io.systemd.boot.kernel-cmdline-extra` If set, the value of this string is added to the list of kernel command line arguments for Boot Loader Specification Type 1 entries that are measured in PCR12 and passed to the kernel. `io.systemd.boot-entries.extra:`\ This allows inserting additional entries into the `systemd-boot` menu. Take a pair of menu entry identifier and menu entry definition string. The former should be suitable for use as a filename of a Boot Loader Specification Type \#1 entry filename (note that it is used for identification purposes only, no file of this name is actually accessed), the latter shall follow the syntax of the contents of a Type \#1 entry. Any menu entry defined this way is processed and shown in pretty much the same way as a Type \#1 entry read from the ESP or XBOOTLDR partition. Example: io.systemd.boot-entries.extra:fooos-current.conf=title FooOS (Current) uki-url http://example.com/somedir/fooos.efi Note that this example contains a newline character. When generating this string from a shell care must be taken to encode it correctly. Pass multiple strings formatted this way to generate multiple menu entries. `io.systemd.boot.loglevel` If set, the value of this string is used as log level. Valid values (from most to least critical) are `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, and `debug`. # Boot Counting `systemd-boot` implements a simple boot counting mechanism on top of the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification), for automatic and unattended fallback to older kernel versions/boot loader entries when a specific entry continuously fails. Any boot loader entry file and unified kernel image file that contains a `+` followed by one or two numbers (if two they need to be separated by a `-`), before the `.conf` or `.efi` suffix is subject to boot counting: the first of the two numbers ('tries left') is decreased by one on every boot attempt, the second of the two numbers ('tries done') is increased by one (if 'tries done' is absent it is considered equivalent to 0). Depending on the current value of these two counters the boot entry is considered to be in one of three states: 1. If the 'tries left' counter of an entry is greater than zero the entry is considered to be in 'indeterminate' state. This means the entry has not completed booting successfully yet, but also has not been determined not to work. 2. If the 'tries left' counter of an entry is zero it is considered to be in 'bad' state. This means no further attempts to boot this item will be made (that is, unless all other boot entries are also in 'bad' state), as all attempts to boot this entry have not completed successfully. 3. If the 'tries left' and 'tries done' counters of an entry are absent it is considered to be in 'good' state. This means further boot counting for the entry is turned off, as it successfully booted at least once. The `systemd-bless-boot.service(8)` service moves the currently booted entry from 'indeterminate' into 'good' state when a boot attempt completed successfully. Generally, when new entries are added to the boot loader, they first start out in 'indeterminate' state, i.e. with a 'tries left' counter greater than zero. The boot entry remains in this state until either it managed to complete a full boot successfully at least once (in which case it will be in 'good' state) — or the 'tries left' counter reaches zero (in which case it will be in 'bad' state). Example: let's say a boot loader entry file `foo.conf` is set up for 3 boot tries. The installer will hence create it under the name `foo+3.conf`. On first boot, the boot loader will rename it to `foo+2-1.conf`. If that boot does not complete successfully, the boot loader will rename it to `foo+1-2.conf` on the following boot. If that fails too, it will finally be renamed `foo+0-3.conf` by the boot loader on next boot, after which it will be considered 'bad'. If the boot succeeds however the entry file will be renamed to `foo.conf` by the OS, so that it is considered 'good' from then on. The boot menu takes the 'tries left' counter into account when sorting the menu entries: entries in 'bad' state are ordered at the beginning of the list, and entries in 'good' or 'indeterminate' at the end. The user can freely choose to boot any entry of the menu, including those already marked 'bad'. If the menu entry to boot is automatically determined, this means that 'good' or 'indeterminate' entries are generally preferred (as the bottom item of the menu is the one booted by default), and 'bad' entries will only be considered if there are no 'good' or 'indeterminate' entries left. The `kernel-install(8)` kernel install framework optionally sets the initial 'tries left' counter to the value specified in `/etc/kernel/tries` when a boot loader entry is first created. # Using `systemd-boot` in virtual machines When using [qemu](https://www.qemu.org/docs/master/) with [OVMF](https://www.linux-kvm.org/downloads/lersek/ovmf-whitepaper-c770f8c.txt) (UEFI Firmware for virtual machines) the `-kernel` switch works not only for linux kernels, but for any EFI binary, including `systemd-boot` and unified linux kernels (UKIs). Example command line for loading `systemd-boot` on x64: `qemu-system-x86_64 -drive if=pflash,format=qcow2,readonly=on,file=/usr/share/edk2/ovmf/OVMF_CODE_4M.qcow2 -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi -drive file=... [ ... ]` (The path to the firmware file might need to be adjusted depending on the distribution.) `systemd-boot` will detect that it was started directly instead of being loaded from ESP and will search for the ESP in that case, taking into account boot order information from the hypervisor (if available). Note that for this to yield a useful result, another `-drive` argument needs to be used to attach an actual disk image with an ESP. # See Also `bootctl(1)`, `loader.conf(5)`, `systemd-bless-boot.service(8)`, `systemd-boot-random-seed.service(8)`, `kernel-install(8)`, `systemd-stub(7)`, [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification), [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE), [TPM2 PCR Measurements Made by systemd](https://systemd.io/TPM2_PCR_MEASUREMENTS) # systemd-bsod.service systemd systemd-bsod.service 8 systemd-bsod.service systemd-bsod Display boot-time emergency log message in full screen `systemd-bsod.service` /usr/lib/systemd/systemd-bsod OPTIONS # Description `systemd-bsod.service` is used to display a blue screen which contains a message relating to a boot failure, including a QR code which can be scanned to get helpful information about the failure. # Options The following options are understood by `systemd-bsod`: `-c`; `--continuous` When specified, `systemd-bsod` waits continuously for changes in the journal if it does not find any emergency messages on the initial attempt. `--tty=` Specify the TTY to output to. By default, `systemd-bsod` will automatically find a free VT to display the message on. If this option is specified a TTY may be selected explicitly. Use `--tty=/dev/tty` to direct output to the terminal the command is invoked on. # Exit status On success (displaying the journal message successfully), 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)` # systemd-cat systemd systemd-cat 1 systemd-cat Connect a pipeline or program's output with the journal systemd-cat OPTIONS COMMAND ARGUMENTS systemd-cat OPTIONS # Description `systemd-cat` may be used to connect the standard output and error output of a command to the journal, or as a filter tool in a shell pipeline to pass the output the previous pipeline element generates to the journal. If no parameter is passed, `systemd-cat` will write everything it reads from standard input (stdin) to the journal. If parameters are passed, they are executed as command line with standard output (stdout) and standard error output (stderr) connected to the journal, so that all it writes is stored in the journal. # Options The following options are understood: `-t`; `--identifier=` Specify a short string that is used to identify the logging tool. If not specified, no identification string is set for the journal entry, and the executable name (or `cat` if the input is read from a pipe) will be used to describe the log source instead. `-p`; `--priority=` Specify the default priority level for the logged messages. Pass one of `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, `debug`, or a value between 0 and 7 (corresponding to the same named levels). These priority values are the same as defined by `syslog(3)`. Defaults to `info`. Note that this simply controls the default, individual lines may be logged with different levels if they are prefixed accordingly. For details, see `--level-prefix=` below. `--stderr-priority=` Specifies the default priority level for messages from the process's standard error output (stderr). Usage of this option is the same as the `--priority=` option, above, and both can be used at once. When both are used, `--priority=` will specify the default priority for standard output (stdout). If `--stderr-priority=` is not specified, messages from stderr will still be logged, with the same default priority level as stdout. Also, note that when stdout and stderr use the same default priority, the messages will be strictly ordered, because one channel is used for both. When the default priority differs, two channels are used, and so stdout messages will not be strictly ordered with respect to stderr messages - though they will tend to be approximately ordered. `--level-prefix=` Controls whether lines read are parsed for syslog priority level prefixes. If enabled (the default), a line prefixed with a priority prefix such as `<5>` is logged at priority 5 (`notice`), and similarly for the other priority levels. Takes a boolean argument. `--namespace=` Specifies the journal namespace to which the standard IO should be connected. For details about journal namespaces, see `systemd-journald.service(8)`. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Examples
Invoke a program
This calls `/bin/ls` with standard output and error connected to the journal: # systemd-cat ls
Usage in a shell pipeline
This builds a shell pipeline also invoking `/bin/ls` and writes the output it generates to the journal: # ls | systemd-cat
Even though the two examples have very similar effects, the first is preferable, since only one process is running at a time and both stdout and stderr are captured, while in the second example, only stdout is captured. # See Also `systemd(1)`, `systemctl(1)`, `logger(1)` # systemd-cgls systemd systemd-cgls 1 systemd-cgls Recursively show control group contents systemd-cgls OPTIONS CGROUP systemd-cgls OPTIONS --unit \| --user-unit UNIT # Description `systemd-cgls` recursively shows the contents of the selected Linux control group hierarchy in a tree. If arguments are specified, shows all member processes of the specified control groups plus all their subgroups and their members. The control groups may either be specified by their full file paths or are assumed in the systemd control group hierarchy. If no argument is specified and the current working directory is beneath the control group mount point `/sys/fs/cgroup/`, shows the contents of the control group the working directory refers to. Otherwise, the full systemd control group hierarchy is shown. By default, empty control groups are not shown. # Options The following options are understood: `--all` Do not hide empty control groups in the output. `-l`; `--full` Do not ellipsize process tree members. `-u`; `--unit` Show cgroup subtrees for the specified units. `--user-unit` Show cgroup subtrees for the specified user units. `-k` Include kernel threads in output. `-M MACHINE`; `--machine=MACHINE` Limit control groups shown to the part corresponding to the container \. `--xattr[=BOOL]`; `-x` Controls whether to include information about extended attributes of the listed control groups in the output. With the long option only, optionally accepts a boolean value. Defaults to no. `--cgroup-id[=BOOL]`; `-c` Controls whether to include the numeric ID of the listed control groups in the output. With the long option only, optionally accepts a boolean value. Defaults to no. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemctl(1)`, `systemd-cgtop(1)`, `systemd-nspawn(1)`, `ps(1)` # systemd-cgtop systemd systemd-cgtop 1 systemd-cgtop Show top control groups by their resource usage systemd-cgtop OPTIONS GROUP # Description `systemd-cgtop` shows the top control groups of the local Linux control group hierarchy, ordered by their CPU, memory, or disk I/O load. The display is refreshed in regular intervals (by default every 1s), similar in style to `top(1)`. If a control group path is specified, shows only the services of the specified control group. If `systemd-cgtop` is not connected to a tty, no column headers are printed and the default is to only run one iteration. The `--iterations=` argument, if given, is honored. This mode is suitable for scripting. Resource usage is only accounted for control groups with the appropriate controllers turned on: `memory` controller for memory usage and `io` controller for disk I/O consumption. If resource monitoring for these resources is required, it is recommended to add the `MemoryAccounting=1` and `IOAccounting=1` settings in the unit files in question. See `systemd.resource-control(5)` for details. The CPU load value can be between 0 and 100 times the number of processors the system has. For example, if the system has 8 processors, the CPU load value is going to be between 0% and 800%. The number of processors can be found in `/proc/cpuinfo`. To emphasize: unless `MemoryAccounting=1` and `IOAccounting=1` are enabled for the services in question, no resource accounting will be available for system services and the data shown by `systemd-cgtop` will be incomplete. # Options The following options are understood: `-p`; `--order=path` Order by control group path name. `-t`; `--order=tasks` Order by number of tasks/processes in the control group. `-c`; `--order=cpu` Order by CPU load. `-m`; `--order=memory` Order by memory usage. `-i`; `--order=io` Order by disk I/O load. `-b`; `--batch` Run in "batch" mode: do not accept input and run until the iteration limit set with `--iterations=` is exhausted or until killed. This mode could be useful for sending output from `systemd-cgtop` to other programs or to a file. `-r`; `--raw` Format byte counts (as in memory usage and I/O metrics) and CPU time with raw numeric values rather than human-readable numbers. `--cpu=percentage`; `--cpu=time` Controls whether the CPU usage is shown as percentage or time. By default, the CPU usage is shown as percentage. When the option is used without an argument, it is equivalent to `--cpu=time`. This setting may also be toggled at runtime by pressing the % key. `-P` Count only userspace processes instead of all tasks. By default, all tasks are counted: each kernel thread and each userspace thread individually. With this setting, kernel threads are excluded from the count and each userspace process only counts as one task, regardless of how many threads it consists of. This setting may also be toggled at runtime by pressing the P key. This option may not be combined with `-k`. `-k` Count only userspace processes and kernel threads instead of all tasks. By default, all tasks are counted: each kernel thread and each userspace thread individually. With this setting, kernel threads are included in the count and each userspace process only counts as one task, regardless of how many threads it consists of. This setting may also be toggled at runtime by pressing the k key. This option may not be combined with `-P`. `--recursive=` Controls whether the number of processes shown for a control group shall include all processes that are contained in any of the child control groups as well. Takes a boolean argument, which defaults to `yes`. If enabled, the processes in child control groups are included, if disabled, only the processes in the control group itself are counted. This setting may also be toggled at runtime by pressing the r key. Note that this setting only applies to process counting, i.e. when the `-P` or `-k` options are used. When all tasks are counted, setting this option to `no` is rejected with an error, as task counting is always recursive. `-n`; `--iterations=` Perform only this many iterations. A value of 0 indicates that the program should run indefinitely. `-1` A shortcut for `--iterations=1`. `-d`; `--delay=` Specify refresh delay in seconds (or if one of `ms`, `us`, `min` is specified as unit in this time unit). This setting may also be increased and decreased at runtime by pressing the + and - keys. `--depth=` Maximum control group tree traversal depth. Specifies how deep `systemd-cgtop` shall traverse the control group hierarchies. If 0 is specified, only the root group is monitored. For 1, only the first level of control groups is monitored, and so on. Defaults to 3. `--root-memory=` Selects how the root control group row (`/`) reports memory usage. Takes one of `cgroup` or `system`. When `cgroup` (the default) is used, the root row shows the sum of `memory.current` across its direct children, which matches the accounting semantics of every other row in the table. When `system` is used, the root row shows whole-system RAM usage (`MemTotal - MemAvailable` from `/proc/meminfo`), which additionally accounts for kernel slab, vmalloc, page tables, and other memory not attributable to any cgroup. This setting may also be toggled at runtime by pressing the / key. `-M MACHINE`; `--machine=MACHINE` Limit control groups shown to the part corresponding to the container \. This option may not be used when a control group path is specified. # Keys `systemd-cgtop` is an interactive tool and may be controlled via user input using the following keys: h Shows a short help text. Immediately refresh output. q Terminate the program. p; t; c; m; i Sort the control groups by path, number of tasks, CPU load, memory usage, or I/O load, respectively. This setting may also be controlled using the `--order=` command line switch. % Toggle between showing CPU time as time or percentage. This setting may also be controlled using the `--cpu=` command line switch. / Toggle the root control group row between cgroup-sum accounting (default) and whole-system accounting from `/proc/meminfo`. This setting may also be controlled using the `--root-memory=` command line switch. +; - Increase or decrease refresh delay, respectively. This setting may also be controlled using the `--delay=` command line switch. P Toggle between counting all tasks, or only userspace processes. This setting may also be controlled using the `-P` command line switch (see above). k Toggle between counting all tasks, or only userspace processes and kernel threads. This setting may also be controlled using the `-k` command line switch (see above). r Toggle between recursively including or excluding processes in child control groups in control group process counts. This setting may also be controlled using the `--recursive=` command line switch. This key is not available if all tasks are counted, it is only available if processes are counted, as enabled with the P or k keys. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemctl(1)`, `systemd-cgls(1)`, `systemd.resource-control(5)`, `top(1)` # systemd-clonesetup-generator systemd systemd-clonesetup-generator 8 systemd-clonesetup-generator Unit generator for /etc/clonetab `/usr/lib/systemd/system-generators/systemd-clonesetup-generator` # Description `systemd-clonesetup-generator` is a generator that translates `/etc/clonetab` into native systemd units early at boot and when configuration of the system manager is reloaded. This will create `systemd-clonesetup@.service(8)` units as necessary. `systemd-clonesetup-generator` implements `systemd.generator(7)`. # See Also `systemd(1)`, `clonetab(5)`, `systemd-clonesetup@.service(8)`, `dmsetup(8)` # systemd-clonesetup systemd systemd-clonesetup 8 systemd-clonesetup systemd-clonesetup@.service Set up and tear down dm-clone devices systemd-clonesetup add NAME SOURCE-DEVICE DEST-DEVICE META-DEVICE OPTIONS systemd-clonesetup remove NAME `systemd-clonesetup@.service` # Description `systemd-clonesetup` is used to set up (with `add`) and tear down (with `remove`) dm-clone devices. It is primarily used via `systemd-clonesetup@.service` units generated from `/etc/clonetab` by `systemd-clonesetup-generator(8)`. The positional arguments `NAME`, `SOURCE-DEVICE`, `DEST-DEVICE`, `META-DEVICE`, and `OPTIONS` have the same meaning as the fields in `clonetab(5)`. Currently, the supported option in `OPTIONS` is `region-size=`\, where \ is measured in bytes (standard suffixes like `K`, `M`, `G` are supported). # See Also `systemd(1)`, `clonetab(5)`, `systemd-clonesetup-generator(8)`, `systemd.generator(7)`, `dmsetup(8)` # systemd-coredump systemd systemd-coredump 8 systemd-coredump systemd-coredump.socket systemd-coredump@.service systemd-coredump-register.service systemd-coredumpd.service Acquire, save, and process core dumps `/usr/lib/systemd/systemd-coredump` `/usr/lib/systemd/systemd-coredump` `--backtrace` `/usr/lib/systemd/systemd-coredump` `--manager` `/usr/lib/systemd/systemd-coredump` `--check-requirements` `systemd-coredump.socket` `systemd-coredump@.service` `systemd-coredump-register.service` `systemd-coredumpd.service` # Description `systemd-coredump@.service` is a system service to process core dumps. It will log a summary of the event to `systemd-journald.service(8)`, including information about the process identifier, owner, the signal that killed the process, and the stack trace if possible. It may also save the core dump for later processing. See the "Information about the crashed process" section below. The behavior of a specific program upon reception of a signal is governed by a few factors which are described in detail in `core(5)`. In particular, the core dump will only be processed when the related process resource limits (`RLIMIT_CORE`) are sufficient. Core dumps can be written to the journal or saved as a file. In both cases, they can be retrieved for further processing, for example in `gdb(1)`. See `coredumpctl(1)`, in particular the `list` and `debug` verbs. By default, `systemd-coredump` will log the core dump to the journal, including a backtrace if possible, and store the core dump (an image of the memory contents of the process) itself in an external file in `/var/lib/systemd/coredump/`. These core dumps are deleted after a few days by default; see `/usr/lib/tmpfiles.d/systemd.conf` for details. Note that the removal of core files from the file system and the purging of journal entries are independent, and the core file may be present without the journal entry, and journal entries may point to since-removed core files. Some metadata is attached to core files in the form of extended attributes, so the core files are useful for some purposes even without the full metadata available in the journal entry. For further details see [systemd Coredump Handling](https://systemd.io/COREDUMP). ## Overview The `systemd-coredump` executable does the actual work, but is invoked differently depending on the capabilities of the running kernel. When the kernel supports the kernel coredump socket protocol (see "Kernel Requirements" below, generally kernel v6.19 or newer), `systemd-coredumpd.service` creates and listens on a Unix socket, and `systemd-coredump-register.service` writes the socket path to `/proc/sys/kernel/core_pattern`. When a process crashes, the kernel connects to the socket, and sends the core dump of the process through the socket. Then, `systemd-coredumpd.service` transfers the core to the corresponding container if the crashed process is in a container environment, otherwise saves the core in the local storage and writes information about the crashed process to journal. When the running kernel does not meet those requirements, the executable `systemd-coredump` is invoked twice: once as the handler by the kernel, and the second time in the `systemd-coredump@.service` to actually write the data to the journal and process and save the core file. When the kernel invokes `systemd-coredump` to handle a core dump this way, it runs in privileged mode, and will connect to the socket created by the `systemd-coredump.socket` unit, which in turn will spawn an unprivileged `systemd-coredump@.service` instance to process the core dump. Hence `systemd-coredump.socket` and `systemd-coredump@.service` are helper units which do the actual processing of core dumps and are subject to normal service management. See "Units" below for details on the individual units involved in either mode. ## Command-line Options `systemd-coredump` is normally not invoked directly by the user, but by the kernel, or by the units described below. It supports the following modes of invocation: (no option) Handles a single core dump. This is the mode the kernel uses to invoke `systemd-coredump` directly (via `kernel.core_pattern`) on kernels that do not support the kernel coredump socket protocol, as well as the mode used by `systemd-coredump@.service` to actually process and save a core dump that was handed to it via `systemd-coredump.socket`. `--backtrace` `systemd-coredump` expects a journal entry in the [Journal Export Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format) on standard input. The entry should contain a `MESSAGE=` field and any additional metadata fields the caller deems reasonable. `systemd-coredump` will append additional metadata fields in the same way it does for core dumps received from the kernel. In this mode, no core dump is stored in the journal. `--manager` Runs `systemd-coredump` as the long-running manager process that listens on the kernel coredump socket, accepts connections from the kernel, and forks off worker processes to process each individual core dump. This is the mode used internally by `systemd-coredumpd.service` and is not intended to be invoked interactively. See "Units" below for details. `--check-requirements` Checks whether the running kernel and execution environment fulfil the requirements for the kernel coredump socket protocol (see "Kernel Requirements" below), and exits with a non-zero status if they are not met. This is used internally as the `ExecCondition=` of `systemd-coredumpd.service` and `systemd-coredump-register.service`, so that those units are skipped, without being marked as failed, on systems where the feature is unavailable. It is not intended to be invoked interactively. ## Kernel Requirements for the Coredump Socket The kernel coredump socket protocol, used by `systemd-coredumpd.service` and `systemd-coredump-register.service`, requires: - A kernel that supports the `PIDFD_INFO_COREDUMP` (since kernel v6.16) and `PIDFD_INFO_COREDUMP_SIGNAL` (since kernel v6.19) flags for the `PIDFD_GET_INFO` `ioctl(2)` operation on a PID file descriptor (see `pidfd_open(2)`). Support for these flags is used as an indicator that the kernel is also new enough to support the request-mode (`@@`-prefixed) kernel coredump socket `kernel.core_pattern`, which was introduced in kernel v6.17. - `systemd-coredump` must be running in the initial PID, USER, and TIME namespaces, i.e. on the host, not inside a container. These conditions are checked with `systemd-coredump` `--check-requirements` before `systemd-coredumpd.service` and `systemd-coredump-register.service` are started. If the requirements are not met, `systemd-coredump` instead falls back to the legacy invocation via `systemd-coredump.socket` and `systemd-coredump@.service`. ## Units The following units are involved in processing core dumps. Which of them are active depends on whether the kernel coredump socket protocol is available, see "Kernel Requirements" above. `systemd-coredumpd.service` A long-running manager service, started early at boot on kernels that support the kernel coredump socket protocol. It creates and listens on the `AF_UNIX` socket `/run/systemd/coredumpd/kernel` (this path is also passed to the kernel via `kernel.core_pattern` by `systemd-coredump-register.service`, see below). When the kernel connects to this socket to submit a core dump, `systemd-coredumpd.service` accepts the connection and forks off a worker process to receive and process that specific core dump, up to a limit of 8 concurrently running workers (once this limit is reached, no further connections are accepted until a worker finishes). Workers that run for longer than 5 minutes are killed automatically. The configuration in `coredump.conf(5)` is read once when `systemd-coredumpd.service` starts. Since the service keeps running afterwards (rather than being invoked anew for every core dump, as `systemd-coredump@.service` is), changes to `coredump.conf` and its drop-ins are *not* picked up automatically. Reload the service to apply configuration changes, see `coredump.conf(5)` for details. `systemd-coredump-register.service` A oneshot unit, automatically pulled in and bound to the lifetime of `systemd-coredumpd.service` (it is not meant to be started or stopped manually). Once `systemd-coredumpd.service` is up, this unit points the kernel at it by setting `kernel.core_pattern` to the request-mode (`@@`-prefixed) socket path `/run/systemd/coredumpd/kernel`, and persists this setting to `/run/sysctl.d/60-coredump.conf` via `systemd-sysctl(8)`. When `systemd-coredumpd.service` is stopped, `systemd-coredump-register.service` is stopped along with it and reverts `kernel.core_pattern` to its previous value. Because `/run/sysctl.d/60-coredump.conf` takes precedence, per the usual `sysctl.d(5)` ordering rules, over the `/usr/lib/sysctl.d/50-coredump.conf` file described in "Configuration" below, masking or overriding `50-coredump.conf` alone is *not* sufficient to install a custom `kernel.core_pattern` on a system where `systemd-coredumpd.service` is active. See "Configuration" below for how to prevent this. `systemd-coredump.socket`; `systemd-coredump@.service` Legacy handler units, used on kernels that do not support the kernel coredump socket protocol (see "Kernel Requirements" above). The kernel invokes `systemd-coredump` directly and in privileged mode for each crash; that instance connects to `systemd-coredump.socket`, which in turn spawns an unprivileged `systemd-coredump@.service` instance to actually process and save the core dump. Unlike `systemd-coredumpd.service`, a fresh `systemd-coredump@.service` instance is started for every core dump, so it always reads the current `coredump.conf` configuration. ## Core dumps in Containers/Namespaces The `systemd-coredump@.service` service will automatically attempt to extract a stacktrace from a process as it crashes. For this stacktrace symbols will be resolved based on debug information embedded in the crashing ELF image, or equivalent debug information separately available on the host OS. For processes that crash inside of local containers or other mount namespace-based sandboxes, this auxiliary debug information is typically not available on the host (simply because containers typically run different software versions than the host). `systemd-coredump` provides two mechanisms to address this: 1. For full-OS containers running systemd inside it is a good idea to enable `CoredumpReceive=` on the unit (see `systemd.resource-control(5)`), which ensures that coredumps of a container are attempted to be forwarded to `systemd-coredump@.service` running inside the container, i.e the container gets to process and store its own core dumps. Note that `systemd-nspawn(1)` defaults to this mode if invoked with the `--boot` switch. This mode of operation is generally recommended for security reasons: the security-sensitive processing of the core dump is done within the confinements of the container itself, by the container's own code, backed by the container's own storage. 2. Alternatively, for more restricted containers (that do not run a proper `init` system as PID 1) it is possible to enable processing of the core dump on the host, with access to the debug information data from the container itself. This mode of operation must be enabled via `EnterNamespace=` in `coredump.conf(5)`, and defaults to off, for security reasons. If both `CoredumpReceive=` is enabled on the unit of the container the core dump belongs to, and `EnterNamespace=` is enabled in the `coredump.conf` configuration file, the former takes precedence. # Configuration For programs started by `systemd`, process resource limits can be set by directive `LimitCORE=`, see `systemd.exec(5)`. In order to be used by the kernel to handle core dumps, `systemd-coredump` must be configured in `sysctl(8)` parameter `kernel.core_pattern`. The syntax of this parameter is explained in `core(5)`. systemd installs the file `/usr/lib/sysctl.d/50-coredump.conf` which configures `kernel.core_pattern` accordingly. This file may be masked or overridden to use a different setting following normal `sysctl.d(5)` rules. If the sysctl configuration is modified, it must be updated in the kernel before it takes effect, see `sysctl(8)` and `systemd-sysctl(8)`. On systems where `systemd-coredumpd.service` is active (see "Kernel Requirements" and "Units" above), `systemd-coredump-register.service` writes its own `kernel.core_pattern` setting to `/run/sysctl.d/60-coredump.conf` whenever `systemd-coredumpd.service` is running, and this file takes precedence over `/usr/lib/sysctl.d/50-coredump.conf`. As a result, masking or overriding `50-coredump.conf` alone does *not* override the default `kernel.core_pattern` on such systems, since `60-coredump.conf` will still take effect. To set a custom `kernel.core_pattern` of your own on a system where `systemd-coredumpd.service` is active, stop and disable it: systemctl disable --now systemd-coredumpd.service In order to be used in the `--backtrace` mode, an appropriate backtrace handler must be installed on the sender side. For example, in case of `python(1)`, this means a `sys.excepthook` must be installed, see [systemd-coredump-python](https://github.com/systemd/systemd-coredump-python). The behavior of `systemd-coredump` itself is configured through the configuration file `/etc/systemd/coredump.conf` and corresponding snippets `/etc/systemd/coredump.conf.d/*.conf`, see `coredump.conf(5)`. When core dumps are processed via `systemd-coredump@.service` (see "Units" above), a new instance of `systemd-coredump` is invoked upon receiving every core dump, and changes in these files will take effect the next time a core dump is received. When core dumps are instead processed by the long-running `systemd-coredumpd.service`, configuration changes require an explicit reload of that service to take effect; see `coredump.conf(5)` for details. Resources used by core dump files are restricted in two ways. Parameters like maximum size of acquired core dumps and files can be set in files `/etc/systemd/coredump.conf` and snippets mentioned above. In addition the storage time of core dump files is restricted by `systemd-tmpfiles`, corresponding settings are by default in `/usr/lib/tmpfiles.d/systemd.conf`. The default is to delete core dumps after a few days; see the above file for details. ## Disabling coredump processing To disable potentially resource-intensive processing by `systemd-coredump`, set Storage=none ProcessSizeMax=0 in `coredump.conf(5)`. # Information about the crashed process `coredumpctl(1)` can be used to retrieve saved core dumps independently of their location, to display information, and to process them e.g. by passing to the GNU debugger (gdb). Data stored in the journal can be also viewed with `journalctl(1)` as usual (or from any other process, using the `sd-journal(3)` API). The relevant messages have `MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1`: $ journalctl MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 -o verbose … MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 COREDUMP_PID=552351 COREDUMP_UID=1000 COREDUMP_GID=1000 COREDUMP_SIGNAL_NAME=SIGSEGV COREDUMP_SIGNAL=11 COREDUMP_CODE=2 COREDUMP_TIMESTAMP=1614342930000000 COREDUMP_COMM=Web Content COREDUMP_EXE=/usr/lib64/firefox/firefox COREDUMP_USER_UNIT=app-gnome-firefox-552136.scope COREDUMP_CMDLINE=/usr/lib64/firefox/firefox -contentproc -childID 5 -isForBrowser … COREDUMP_CGROUP=/user.slice/user-1000.slice/user@1000.service/app.slice/app-….scope COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst … The following fields are saved (if known) with the journal entry `COREDUMP_UID=`; `COREDUMP_PID=`; `COREDUMP_GID=` The process number (PID), owner user number (UID), and group number (GID) of the crashed process. When the crashed process was part of a container (or in a process or user namespace in general), those are the values as seen *outside*, in the namespace where `systemd-coredump` is running. `COREDUMP_TID=`; `COREDUMP_THREAD_NAME=` The thread number (TID) and name (`/proc/pid/task/tid/comm`) of the thread that triggered the core dump. For single-threaded processes the TID is the same as the PID. Like `COREDUMP_PID=`, the TID is the value as seen in the namespace where `systemd-coredump` is running. `COREDUMP_BY_PIDFD=` If the crashed process was analyzed using a PIDFD provided by the kernel (requires kernel v6.16) then this field will be present and set to `1`. If this field is not set, then the crashed process was analyzed via a PID, which is known to be subject to race conditions. `COREDUMP_TIMESTAMP=` The time of the crash as reported by the kernel (in μs since the epoch). `COREDUMP_RLIMIT=` The core file size soft resource limit, see `getrlimit(2)`. `COREDUMP_UNIT=`; `COREDUMP_SLICE=` The system unit and slice names. When the crashed process was in container, those are the units names *outside*, in the main system manager. `COREDUMP_CGROUP=` The primary cgroup of the unit of the crashed process. When the crashed process was in a container, this is the full path, as seen outside of the container. `COREDUMP_PROC_CGROUP=` Control group information in the format used in `/proc/self/cgroup`. On systems with the unified cgroup hierarchy, this is a single path prefixed with `0::`, and multiple paths prefixed with controller numbers on legacy systems. When the crashed process was in a container, this is the full path, as seen outside of the container. `COREDUMP_OWNER_UID=`; `COREDUMP_USER_UNIT=`; `COREDUMP_SESSION=` The numerical UID of the user owning the login session or systemd user unit of the crashed process, the user manager unit, and the session identifier. All three fields are only present for user processes. When the crashed process was in container, those are the values *outside*, in the main system. `COREDUMP_SIGNAL_NAME=`; `COREDUMP_SIGNAL=` The terminating signal name (with the `SIG` prefix [^1]) and numerical value. (Both are included because signal numbers vary by architecture.) `COREDUMP_CODE=` The reason why the signal was sent as a numerical value. The code is defined as field `si_code` in the `siginfo_t` structure and documented in `sigaction(2)`. `COREDUMP_CWD=`; `COREDUMP_ROOT=` The current working directory and root directory of the crashed process. When the crashed process is in a container, those paths are relative to the root of the container's mount namespace. `COREDUMP_DUMPABLE=` The `PR_GET_DUMPABLE` field as reported by the kernel, see `prctl(2)`. `COREDUMP_OPEN_FDS=` Information about open file descriptors, in the following format: fd:/path/to/file pos: ... flags: ... ... fd:/path/to/file pos: ... flags: ... ... The first line contains the file descriptor number \ and the path, while subsequent lines show the contents of `/proc/pid/fdinfo/fd`. `COREDUMP_EXE=` The destination of the `/proc/pid/exe` symlink. When the crashed process is in a container, that path is relative to the root of the container's mount namespace. `COREDUMP_CMDLINE=`; `COREDUMP_COMM=`; `COREDUMP_ENVIRON=`; `COREDUMP_PROC_AUXV=`; `COREDUMP_PROC_LIMITS=`; `COREDUMP_PROC_MAPS=`; `COREDUMP_PROC_MOUNTINFO=`; `COREDUMP_PROC_STATUS=` Fields that map the per-process entries in the `/proc/` filesystem: `/proc/pid/cmdline` (the command line of the crashed process), `/proc/pid/comm` (the command name associated with the process), `/proc/pid/environ` (the environment block of the crashed process), `/proc/pid/auxv` (the auxiliary vector of the crashed process, see `getauxval(3)`), `/proc/pid/limits` (the soft and hard resource limits), `/proc/pid/maps` (memory regions visible to the process and their access permissions), `/proc/pid/mountinfo` (mount points in the process's mount namespace), `/proc/pid/status` (various metadata about the process). See `proc(5)` for more information. `COREDUMP_HOSTNAME=` The system hostname. When the crashed process was in container, this is the container hostname. `COREDUMP_CONTAINER_CMDLINE=` For processes running in a container, the command line of the process spawning the container (the first parent process with a different mount namespace). `COREDUMP=` When the core is stored in the journal, the core image itself. `COREDUMP_FILENAME=` When the core is stored externally, the path to the core file. `COREDUMP_TRUNCATED=` Set to `1` when the saved coredump was truncated. (A partial core image may still be processed by some tools, though obviously not all information is available.) `COREDUMP_PACKAGE_NAME=`; `COREDUMP_PACKAGE_VERSION=`; `COREDUMP_PACKAGE_JSON=` If the executable contained .package metadata ELF notes, they will be parsed and attached. The `package` and `version` of the 'main' ELF module (i.e., the executable) will be appended individually. The JSON-formatted content of all modules will be appended as a single JSON object, each with the module name as the key. For more information about this metadata format and content, see the [Package Metadata for Executable Files](https://systemd.io/PACKAGE_METADATA_FOR_EXECUTABLE_FILES/) document. `MESSAGE=` The message generated by `systemd-coredump` that includes the backtrace if it was successfully generated. When `systemd-coredump` is invoked with `--backtrace`, this field is provided by the caller. Various other fields exist in the journal entry, but pertain to the logging process, i.e. `systemd-coredump`, not the crashed process. See `systemd.journal-fields(7)`. The following fields are saved (if known) with the external file listed in `COREDUMP_FILENAME=` as extended attributes: `user.coredump.pid`; `user.coredump.uid`; `user.coredump.gid`; `user.coredump.signal`; `user.coredump.timestamp`; `user.coredump.rlimit`; `user.coredump.hostname`; `user.coredump.comm`; `user.coredump.exe` Those are the same as `COREDUMP_PID=`, `COREDUMP_UID=`, `COREDUMP_GID=`, `COREDUMP_SIGNAL=`, `COREDUMP_TIMESTAMP=`, `COREDUMP_RLIMIT=`, `COREDUMP_HOSTNAME=`, `COREDUMP_COMM=`, and `COREDUMP_EXE=`, described above. `user.coredump.tid`; `user.coredump.thread_name` Those are the same as `COREDUMP_TID=` and `COREDUMP_THREAD_NAME=`, described above. Those can be viewed using `getfattr(1)`. For the core file described in the journal entry shown above: $ getfattr --absolute-names -d /var/lib/systemd/coredump/core.Web….552351.….zst # file: /var/lib/systemd/coredump/core.Web….552351.….zst user.coredump.pid="552351" user.coredump.uid="1000" user.coredump.gid="1000" user.coredump.signal="11" user.coredump.timestamp="1614342930000000" user.coredump.comm="Web Content" user.coredump.exe="/usr/lib64/firefox/firefox" … # See Also `coredump.conf(5)`, `coredumpctl(1)`, `systemd-journald.service(8)`, `systemd-tmpfiles(8)`, `core(5)`, `sysctl.d(5)`, `systemd-sysctl.service(8)`, [systemd Coredump Handling](https://systemd.io/COREDUMP) [^1]: `kill(1)` expects signal names *without* the prefix; `kill(2)` uses the prefix; all systemd tools accept signal names both with and without the prefix. # systemd-creds systemd systemd-creds 1 systemd-creds Lists, shows, encrypts and decrypts service credentials systemd-creds OPTIONS COMMAND ARGS # Description `systemd-creds` is a tool for listing, showing, encrypting and decrypting unit credentials. Credentials are limited-size binary or textual objects that may be passed to unit processes. They are primarily used for passing cryptographic keys (both public and private) or certificates, user account information or identity information from the host to services. Credentials are configured in unit files via the `ImportCredential=`, `LoadCredential=`, `SetCredential=`, `LoadCredentialEncrypted=`, and `SetCredentialEncrypted=` settings, see `systemd.exec(5)` for details. For further information see [System and Service Credentials](https://systemd.io/CREDENTIALS) documentation. # Commands The following commands are understood: `list` Show a list of credentials passed into the current execution context. This command shows the files in the directory referenced by the `$CREDENTIALS_DIRECTORY` environment variable, and is intended to be executed from within service context. Along with each credential name, the size and security state is shown. The latter is one of `secure` (in case the credential is backed by unswappable memory, i.e. `ramfs`), `weak` (in case it is backed by any other type of memory), or `insecure` (if having any access mode that is not 0400, i.e. if readable by anyone but the owner). `cat` \ Show contents of specified credentials passed into the current execution context. Takes one or more credential names, whose contents shall be written to standard output. When combined with `--json=` or `--transcode=` the output is transcoded in simple ways before outputting. `setup` Generates a host encryption key for credentials, if one has not been generated already. This ensures the `/var/lib/systemd/credential.secret` file is initialized with a random secret key if it does not exist yet. This secret key is used when encrypting/decrypting credentials with `encrypt` or `decrypt`, and is only accessible to the root user. Note that there's typically no need to invoke this command explicitly as it is implicitly called when `encrypt` is invoked, and credential host key encryption selected. `encrypt` \ \ Loads the specified (unencrypted plaintext) input credential file, encrypts it and writes the (encrypted ciphertext) output to the specified target credential file. The resulting file may be referenced in the `LoadCredentialEncrypted=` setting in unit files, or its contents used literally in `SetCredentialEncrypted=` settings. Takes two file system paths. The file name part of the output path is embedded as name in the encrypted credential, to ensure encrypted credentials cannot be renamed and reused for different purposes without this being noticed. The credential name to embed may be overridden with the `--name=` setting. The input or output paths may be specified as `-`, in which case the credential data is read from/written to standard input and standard output. If the output path is specified as `-` the credential name cannot be derived from the file system path, and thus should be specified explicitly via the `--name=` switch. The credential data is encrypted and authenticated symmetrically with one of the following encryption keys: 1. A secret key automatically derived from the system's TPM2 chip. This encryption key is not stored on the host system and thus decryption is only possible with access to the original TPM2 chip. Or in other words, the credential secured in this way can only be decrypted again by the local machine. 2. A secret key stored in the `/var/lib/systemd/credential.secret` file which is only accessible to the root user. This "host" encryption key is stored on the host file system, and thus decryption is possible with access to the host file system and sufficient privileges. The key is automatically generated when needed, but can also be created explicitly with the `setup` command, see above. 3. A combination of the above: an encryption key derived from both the TPM2 chip and the host file system. This means decryption requires both access to the original TPM2 chip and the OS installation. This is the default mode of operation if a TPM2 chip is available and `/var/lib/systemd/` resides on persistent media. Which of the three keys shall be used for encryption may be configured with the `--with-key=` switch. Depending on the use-case for the encrypted credential the key to use may differ. For example, for credentials that shall be accessible from the initrd, encryption with the host key is not appropriate, since access to the host key is typically not available from the initrd. Thus, for such credentials only the TPM2 key should be used. Encrypted credentials are always encoded in Base64. Use `decrypt` (see below) to undo the encryption operation, and acquire the decrypted plaintext credential from the encrypted ciphertext credential. The credential data is encrypted using AES256-GCM, i.e. providing both confidentiality and integrity, keyed by a SHA256 hash of one or both of the secret keys described above. `decrypt` \ \[\\] Undoes the effect of the `encrypt` operation: loads the specified (encrypted ciphertext) input credential file, decrypts and authenticates it and writes the (decrypted plaintext) output to the specified target credential file. Takes one or two file system paths. The file name part of the input path is compared with the credential name embedded in the encrypted file. If it does not match decryption fails. This is done in order to ensure that encrypted credentials are not re-purposed without this being detected. The credential name to compare with the embedded credential name may also be overridden with the `--name=` switch. If the input path is specified as `-`, the encrypted credential is read from standard input. If only one path is specified or the output path specified as `-`, the decrypted credential is written to standard output. In this mode, the expected name embedded in the credential cannot be derived from the path and should be specified explicitly with `--name=`. Decrypting credentials requires access to the original TPM2 chip and/or credentials host key, see above. Information about which keys are required is embedded in the encrypted credential data, and thus decryption is entirely automatic. # Options `--system` When specified with the `list` and `cat` commands operates on the credentials passed to system as a whole instead of on those passed to the current execution context. This is useful in container environments where credentials may be passed in from the container manager. `--user` When specified with the `encrypt` and `decrypt` commands encrypts a user-scoped (rather than a system-scoped) credential. Use `--uid=` to select which user the credential is from. Such credentials may only be decrypted from the specified user's context, except if privileges can be acquired. Generally, when an encrypted credential shall be used in the per-user service manager it should be encrypted with this option set, when it shall be used in the system service manager it should be encrypted without. Internally, this ensures that the selected user's numeric UID and username, as well as the system's `machine-id(5)` are incorporated into the encryption key. `--uid=` Specifies the user to encrypt the credential for. Takes a user name or numeric UID. If set, implies `--user`. If set to the special string `self` sets the user to the user of the calling process. If `--user` is used without `--uid=` then `--uid=self` is implied, i.e. the credential is encrypted for the calling user. `--transcode=` When specified with the `cat` or `decrypt` commands, transcodes the output before showing it. Takes one of `base64`, `unbase64`, `hex` or `unhex` as argument, in order to encode/decode the credential data with Base64 or as series of hexadecimal values. The special value `help` may be used to list supported transcode types. Note that this has no effect on the `encrypt` command, as encrypted credentials are unconditionally encoded in Base64. `--newline=` When specified with `cat` or `decrypt` controls whether to add a trailing newline character to the end of the output if it does not end in one, anyway. Takes one of `auto`, `yes` or `no`. The default mode of `auto` will suffix the output with a single newline character only when writing credential data to a TTY. `--pretty`; `-p` When specified with `encrypt` controls whether to show the encrypted credential as `SetCredentialEncrypted=` setting that may be pasted directly into a unit file. Has effect only when used together with `--name=` and `-` as the output file. `--name=name` When specified with the `encrypt` command controls the credential name to embed in the encrypted credential data. If not specified, the name is chosen automatically from the filename component of the specified output path. If specified as empty string no credential name is embedded in the encrypted credential, and no verification of credential name is done when the credential is decrypted. When specified with the `decrypt` command control the credential name to validate the credential name embedded in the encrypted credential with. If not specified, the name is chosen automatically from the filename component of the specified input path. If no credential name is embedded in the encrypted credential file (i.e. the `--name=` with an empty string was used when encrypted) the specified name has no effect as no credential name validation is done. Embedding the credential name in the encrypted credential is done in order to protect against reuse of credentials for purposes they were not originally intended for, under the assumption the credential name is chosen carefully to encode its intended purpose. `--timestamp=timestamp` When specified with the `encrypt` command controls the timestamp to embed into the encrypted credential. Defaults to the current time. Takes a timestamp specification in the format described in `systemd.time(7)`. When specified with the `decrypt` command controls the timestamp to use to validate the "not-after" timestamp that was configured with `--not-after=` during encryption. If not specified, defaults to the current system time. `--not-after=timestamp` When specified with the `encrypt` command controls the time when the credential shall not be used anymore. This embeds the specified timestamp in the encrypted credential. During decryption the timestamp is checked against the current system clock, and if the timestamp is in the past the decryption will fail. By default, no such timestamp is set. Takes a timestamp specification in the format described in `systemd.time(7)`. `--with-key=`; `-H`; `-T` When specified with the `encrypt` command controls the encryption/signature key to use. Takes one of `host`, `tpm2`, `host+tpm2`, `null`, `auto`, `auto-initrd`. See above for details on the key types. If set to `auto` (which is the default) the TPM2 key is used if a TPM2 device is found and not running in a container. The host key is used if `/var/lib/systemd/` is on persistent media. This means on typical systems the encryption is by default bound to both the TPM2 chip and the OS installation, and both need to be available to decrypt the credential again. If `auto` is selected but neither TPM2 is available (or running in container) nor `/var/lib/systemd/` is on persistent media, encryption will fail. If set to `null` a fixed zero length key is used (thus, in this mode no confidentiality nor authenticity are provided!). This logic is useful to cover for systems that lack a TPM2 chip but where credentials shall be generated. Note that decryption of such credentials is refused on systems that have a TPM2 chip and where UEFI SecureBoot is enabled (this is done so that such a locked down system cannot be tricked into loading a credential generated this way that lacks authentication information. If either UEFI SecureBoot or a TPM2 are not available, then loading such credentials is allowed by default). If set to `auto-initrd` a TPM2 key is used if a TPM2 is found. If not, a fixed zero length key is used, equivalent to `null` mode. This option is particularly useful to generate credentials files that are encrypted/authenticated against TPM2 where available but still work on systems lacking support for this. The special value `help` may be used to list supported key types. systemd v262 and later additionally pin the encrypted credential to the TPM2's SRK to defend against MITM interposer attacks when decrypting credentials. This makes the resulting credentials incompatible with earlier systemd versions. The `-H` switch is a shortcut for `--with-key=host`. Similar, `-T` is a shortcut for `--with-key=tpm2`. When encrypting credentials that shall be used in the initrd (where `/var/lib/systemd/` is typically not available) make sure to use `--with-key=auto-initrd` mode, to disable binding against the host secret. This switch has no effect on the `decrypt` command, as information on which key to use for decryption is included in the encrypted credential already. `--tpm2-device=PATH` Controls the TPM2 device to use. Expects a device node path referring to the TPM2 chip (e.g. `/dev/tpmrm0`). Alternatively the special value `auto` may be specified, in order to automatically determine the device node of a suitable TPM2 device (of which there must be exactly one). The special value `list` may be used to enumerate all suitable TPM2 devices currently discovered. `--tpm2-pcrs=PCR+PCR...` Configures the TPM2 PCRs (Platform Configuration Registers) to bind the encryption key to. Takes a `+` separated list of numeric PCR indexes in the range 0…23. If an empty string is specified, binds the encryption key to no PCRs at all (this is also the default if this option is not used). For details about the PCRs available, see the documentation of the switch of the same name for `systemd-cryptenroll(1)`. `--tpm2-public-key=PATH`; `--tpm2-public-key-pcrs=PCR+PCR...` Configures a TPM2 signed PCR policy to bind encryption to, for use with the `encrypt` command. The `--tpm2-public-key=` option accepts a path to a PEM encoded RSA public key, to bind the encryption to. If this is not specified explicitly, but a file `tpm2-pcr-public-key.pem` exists in one of the directories `/etc/systemd/`, `/run/systemd/`, `/usr/lib/systemd/` (searched in this order), it is automatically used. The `--tpm2-public-key-pcrs=` option takes a list of TPM2 PCR indexes to bind to (same syntax as `--tpm2-pcrs=` described above). If not specified, defaults to 11 (i.e. this binds the policy to any unified kernel image for which a PCR signature can be provided). Note the difference between `--tpm2-pcrs=` and `--tpm2-public-key-pcrs=`: the former binds decryption to the current, specific PCR values; the latter binds decryption to any set of PCR values for which a signature by the specified public key can be provided. The latter is hence more useful in scenarios where software updates shall be possible without losing access to all previously encrypted secrets. `--tpm2-signature=PATH` Takes a path to a TPM2 PCR signature file as generated by the `systemd-measure(1)` tool and that may be used to allow the `decrypt` command to decrypt credentials that are bound to specific signed PCR values. If this is not specified explicitly, and a credential with a signed PCR policy is attempted to be decrypted, a suitable signature file `tpm2-pcr-signature.json` is searched for in `/etc/systemd/`, `/run/systemd/`, `/usr/lib/systemd/` (in this order) and used. `--allow-null` Allow decrypting credentials that use a null key. By default decryption of credentials encrypted/authenticated with a null key is only allowed if UEFI SecureBoot is off or if a TPM2 is not available. `--refuse-null` Refuse decrypting credentials that use a null key, regardless of the UEFI SecureBoot state or TPM2 availability (see above). `--quiet`; `-q` Suppress additional output. # Exit status On success, 0 is returned. # Examples
Encrypt a password for use as credential
The following command line encrypts the specified password `hunter2`, writing the result to a file `password.cred`. # echo -n hunter2 | systemd-creds encrypt - password.cred This decrypts the file `password.cred` again, revealing the literal password: # systemd-creds decrypt password.cred hunter2
Encrypt a password and include it in a unit file
The following command line prompts the user for a password and generates a `SetCredentialEncrypted=` line from it for a credential named `mysql-password`, suitable for inclusion in a unit file. # systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - - 🔐 Password: **** SetCredentialEncrypted=mysql-password: \ k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAASfFsBoPLIm/dlDoGAAAAAAAAAA \ NAAAAAgAAAAAH4AILIOZ3w6rTzYsBy9G7liaCAd4i+Kpvs8mAgArzwuKxd0ABDjgSeO5k \ mKQc58zM94ZffyRmuNeX1lVHE+9e2YD87KfRFNoDLS7F3YmCb347gCiSk2an9egZ7Y0Xs \ 700Kr6heqQswQEemNEc62k9RJnEl2q7SbcEYguegnPQUATgAIAAsAAAASACA/B90W7E+6 \ yAR9NgiIJvxr9bpElztwzB5lUJAxtMBHIgAQACCaSV9DradOZz4EvO/LSaRyRSq2Hj0ym \ gVJk/dVzE8Uxj8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciyageTfrVEer8z5 \ 9cUQfM5ynSaV2UjeUWEHuz4fwDsXGLB9eELXLztzUU9nsAyLvs3ZRR+eEK/A== The generated line can be pasted 1:1 into a unit file, and will ensure the acquired password will be made available in the `$CREDENTIALS_DIRECTORY``/mysql-password` credential file for the started service. Utilizing the unit file drop-in logic this can be used to securely pass a password credential to a unit. A similar, more comprehensive set of commands to insert a password into a service `xyz.service`: # mkdir -p /etc/systemd/system/xyz.service.d # systemd-ask-password -n | ( echo "[Service]" && systemd-creds encrypt --name=mysql-password -p - - ) >/etc/systemd/system/xyz.service.d/50-password.conf # systemctl daemon-reload # systemctl restart xyz.service
# See Also `systemd(1)`, `systemd.exec(5)`, `systemd-measure(1)` # systemd-cryptenroll systemd systemd-cryptenroll 1 systemd-cryptenroll Enroll PKCS#11, FIDO2, TPM2 token/devices to LUKS2 encrypted volumes systemd-cryptenroll OPTIONS DEVICE # Description `systemd-cryptenroll` is a tool for enrolling hardware security tokens and devices into a LUKS2 encrypted volume, which may then be used to unlock the volume during boot. Specifically, it supports tokens and credentials of the following kind to be enrolled: 1. PKCS#11 security tokens and smartcards that may carry an RSA or EC key pair (e.g. various YubiKeys) 2. FIDO2 security tokens that implement the `hmac-secret` extension (most FIDO2 keys, including YubiKeys) 3. TPM2 security devices 4. Regular passphrases 5. Recovery keys. These are similar to regular passphrases, however are randomly generated on the computer and thus generally have higher entropy than user-chosen passphrases. Their character set has been designed to ensure they are easy to type in, while having high entropy. They may also be scanned off screen using QR codes. Recovery keys may be used for unlocking LUKS2 volumes wherever passphrases are accepted. They are intended to be used in combination with an enrolled hardware security token, as a recovery option when the token is lost. In addition, the tool may be used to enumerate currently enrolled security tokens and wipe a subset of them. The latter may be combined with the enrollment operation of a new security token, in order to update or replace enrollments. The tool supports only LUKS2 volumes, as it stores token meta-information in the LUKS2 JSON token area, which is not available in other encryption formats. `systemd-cryptsetup` operates on the device backing `/var/` if no device is specified explicitly, and no wipe operation is requested. (Note that in the typical case where `/var/` is on the same file system as the root file system, this hence enrolls a key into the backing device of the root file system.) ## TPM2 PCRs and policies PCRs allow binding of the encryption of secrets to specific software versions and system state, so that the enrolled key is only accessible (may be "unsealed") if specific trusted software and/or configuration is used. Such bindings may be created with the option `--tpm2-pcrs=` described below. Secrets may also be bound indirectly: a signed policy for a state of some combination of PCR values is provided, and the secret is bound to the public part of the key used to sign this policy. This means that the owner of a key can generate a sequence of signed policies, for specific software versions and system states, and the secret can be decrypted as long as the machine state matches one of those policies. For example, a vendor may provide such a policy for each kernel+initrd update, allowing users to encrypt secrets so that they can be decrypted when running any kernel+initrd signed by the vendor. Such bindings may be created with the options `--tpm2-public-key=`, `--tpm2-public-key-pcrs=`, `--tpm2-signature=` described below. See [UAPI.7 Linux TPM PCR Registry](https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/) for an authoritative list of PCRs and how they are updated. The table below contains a quick reference, describing in particular the PCRs modified by systemd. | PCR | name | Explanation | |----|----|----| | 0 | platform-code | Core system firmware executable code; changes on firmware updates | | 1 | platform-config | Core system firmware data/host platform configuration; typically contains serial and model numbers, changes on basic hardware/CPU/RAM replacements | | 2 | external-code | Extended or pluggable executable code; includes option ROMs on pluggable hardware | | 3 | external-config | Extended or pluggable firmware data; includes information about pluggable hardware | | 4 | boot-loader-code | Boot loader and additional drivers, PE binaries invoked by the boot loader; changes on boot loader updates. `sd-stub(7)` measures system extension images read from the ESP here too (see `systemd-sysext(8)`). | | 5 | boot-loader-config | GPT/Partition table; changes when the partitions are added, modified, or removed | | 7 | secure-boot-policy | Secure Boot state; changes when UEFI SecureBoot mode is enabled/disabled, or firmware certificates (PK, KEK, db, dbx, …) changes. | | 9 | kernel-initrd | The Linux kernel measures all initrds it receives into this PCR. | | 10 | ima | The IMA project measures its runtime state into this PCR. | | 11 | kernel-boot | `systemd-stub(7)` measures the ELF kernel image, embedded initrd and other payload of the PE image it is placed in into this PCR. `systemd-pcrphase.service(8)` measures boot phase strings into this PCR at various milestones of the boot process. | | 12 | kernel-config | `systemd-boot(7)` measures the kernel command line into this PCR. `systemd-stub(7)` measures any manually specified kernel command line (i.e. a kernel command line that overrides the one embedded in the unified PE image) and loaded credentials into this PCR. | | 13 | sysexts | `systemd-stub(7)` measures any `systemd-sysext(8)` images it passes to the booted kernel into this PCR. | | 14 | shim-policy | The shim project measures its "MOK" certificates and hashes into this PCR. | | 15 | system-identity | `systemd-cryptsetup(8)` optionally measures the volume key of activated LUKS volumes into this PCR. `systemd-pcrmachine.service(8)` measures the `machine-id(5)` into this PCR. `systemd-pcrfs@.service(8)` measures mount points, file system UUIDs, labels, partition UUIDs of the root and `/var/` filesystems into this PCR. | | 16 | debug | Debug | | 23 | application-support | Application Support | Well-known PCR Definitions In general, encrypted volumes would be bound to some combination of PCRs 7, 11, and 14 (if shim/MOK is used). In order to allow firmware and OS version updates, it is typically not advisable to use PCRs such as 0 and 2, since the program code they cover should already be covered indirectly through the certificates measured into PCR 7. Validation through certificates hashes is typically preferable over validation through direct measurements as it is less brittle in context of OS/firmware updates: the measurements will change on every update, but signatures should remain unchanged. See the [UAPI.7 Linux TPM PCR Registry](https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/) for more discussion. # Limitations Note that currently when enrolling a new key of one of the five supported types listed above, it is required to first provide a passphrase, a recovery key, a FIDO2 token, or a TPM2 key. It's currently not supported to unlock a device with a PKCS#11 key in order to enroll a new PKCS#11 key. Thus, if in future key roll-over is desired it is generally recommended to ensure a passphrase, a recovery key, a FIDO2 token, or a TPM2 key is always enrolled. Also note that support for enrolling multiple FIDO2 tokens is currently limited. When multiple FIDO2 tokens are enrolled, `systemd-cryptsetup` will perform pre-flight requests to attempt to identify which of the enrolled tokens are currently plugged in. However, this is not possible for FIDO2 tokens with user verification (UV, usually via biometrics), in which case it will fall back to attempting each enrolled token one by one. This will result in multiple prompts for PIN and user verification. This limitation does not apply to PKCS#11 tokens. # Compatibility Security technology both in systemd and in the general industry constantly evolves. In order to provide best security guarantees, the way TPM2, FIDO2, PKCS#11 devices are enrolled is regularly updated in newer versions of systemd. Whenever this happens the following compatibility guarantees are given: - Old enrollments continue to be supported and may be unlocked with newer versions of `systemd-cryptsetup@.service(8)`. - The opposite is not guaranteed however: it might not be possible to unlock volumes with enrollments done with a newer version of `systemd-cryptenroll` with an older version of `systemd-cryptsetup`. That said, it is generally recommended to use matching versions of `systemd-cryptenroll` and `systemd-cryptsetup`, since this is best tested and supported. It might be advisable to re-enroll existing enrollments to take benefit of newer security features, as they are added to systemd. # Unlocking The following options are understood that may be used to unlock the device in preparation of the enrollment operations: `--unlock-empty` Use an empty password/passphrase to unlock the volume, instead of reading one from stdin. This is useful to unlock volumes that are currently protected by an empty password, in order to enroll a different, stronger unlock mechanism. `--unlock-key-file=PATH` Use a file instead of a password/passphrase read from stdin to unlock the volume. Expects the PATH to the file containing your key to unlock the volume. Currently there is nothing like `--key-file-offset=` or `--key-file-size=` so this file has to only contain the full key. `--unlock-fido2-device=PATH` Use a FIDO2 device instead of a password/passphrase read from stdin to unlock the volume. Expects a `hidraw` device referring to the FIDO2 device (e.g. `/dev/hidraw1`). Alternatively the special value `auto` may be specified, in order to automatically determine the device node of a currently plugged in security token (of which there must be exactly one). This automatic discovery is unsupported if `--fido2-device=` option is also specified. Note that currently FIDO2 devices enrolled without an accompanying LUKS2 token (i.e. `--fido2-parameters-in-header=no`) cannot be used for unlocking. `--unlock-tpm2-device=PATH` Use a TPM2 device instead of a password/passphrase read from stdin to unlock the volume. Expects a device node path referring to the TPM2 chip (e.g. `/dev/tpmrm0`). Alternatively the special value `auto` may be specified, in order to automatically determine the device node of a currently discovered TPM2 device (of which there must be exactly one). `--unlock-headless` Try the unlock mechanisms suitable for headless operation in turn, without requiring any interactive input. If a TPM2 device is available the volume is unlocked via TPM2, and otherwise (or if TPM2 unlocking fails) an empty password is attempted. This is primarily useful in automated provisioning scenarios where a volume is first set up with a TPM2 enrollment or an empty password and a stronger unlock mechanism shall be enrolled subsequently. # Simple Enrollment The following options are understood that may be used to enroll simple user input based unlocking: `--password` Enroll a regular password/passphrase. This command is mostly equivalent to `cryptsetup luksAddKey`, however may be combined with `--wipe-slot=` in one call, see below. `--recovery-key` Enroll a recovery key. Recovery keys are mostly identical to passphrases, but are computer-generated instead of being chosen by a human, and thus have a guaranteed high entropy. The key uses a character set that is easy to type in, and may be scanned off screen via a QR code. # Interactive Enrollment The following options are understood that drive an interactive enrollment wizard, intended to be run on first boot (similar in spirit to `systemd-firstboot(1)`): `--firstboot` Run an interactive wizard that lets the user enroll a passphrase, a recovery key, or a FIDO2 security token (one menu entry per suitable token currently plugged in). If credentials of any of these types are already enrolled, the wizard additionally offers to wipe them. Pressing enter at the top-level menu leaves the volume unchanged. This option may not be combined with an explicit enrollment type or with `--wipe-slot=`. As with the other commands, the volume to operate on is the one backing `/var/` if none is specified. Honours the `systemd.firstboot=` kernel command line option. `--prompt-suppress=TYPE…` Takes a comma-separated list of slot types, out of `password`, `recovery`, `pkcs11`, `fido2` and `tpm2`. Only useful together with `--firstboot`: if a slot of any of the listed types is already enrolled on the volume, the wizard does nothing and exits successfully. This is useful to hook the wizard into the boot process while ensuring it stays quiet once suitable credentials have been set up. `--chrome=BOOL` Takes a boolean argument, defaults to on. Only useful together with `--firstboot`: if enabled the interactive wizard draws a coloured bar across the top and bottom of the terminal to visually frame the prompt. Pass `--chrome=no` to disable this decoration, for example when running on a terminal that does not render it well. `--mute-console=BOOL` Takes a boolean argument, defaults to off. Only useful together with `--firstboot`: if enabled the kernel and PID 1 are asked to refrain from writing log messages to the console while the interactive wizard is shown, so that such output does not interfere with the prompt. The console is unmuted again once the wizard exits. # PKCS#11 Enrollment The following option is understood that may be used to enroll PKCS#11 tokens: `--pkcs11-token-uri=URI` Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey). Expects a PKCS#11 URI that allows finding an X.509 certificate or a public key on the token. The URI must also be suitable to find a related private key after changing the type of object in it. Alternatively the special value `auto` may be specified, in order to automatically determine the suitable URI if a single security token containing a single key pair is plugged in. The special value `list` may be used to enumerate all suitable PKCS#11 tokens currently plugged in. The PKCS#11 token must contain an RSA or EC key pair which will be used to unlock a LUKS2 volume. For RSA, a randomly generated volume key is encrypted with a public key in the token, and stored in the LUKS2 JSON token header area. To unlock a volume, the stored encrypted volume key will be decrypted with a private key in the token. For ECC, ECDH algorithm is used: we generate a pair of EC keys in the same EC group, then derive a shared secret using the generated private key and the public key in the token. The derived shared secret is used as a volume key. The generated public key is stored in the LUKS2 JSON token header area. The generated private key is erased. To unlock a volume, we derive the shared secret with the stored public key and a private key in the token. In order to unlock a LUKS2 volume with an enrolled PKCS#11 security token, specify the `pkcs11-uri=` option in the respective `/etc/crypttab` line: myvolume /dev/sda1 none pkcs11-uri=auto See `crypttab(5)` for a more comprehensive example of a `systemd-cryptenroll` invocation and its matching `/etc/crypttab` line. # FIDO2 Enrollment The following options are understood that may be used to enroll FIDO2 tokens: `--fido2-device=PATH` Enroll a FIDO2 security token that implements the `hmac-secret` extension (e.g. a YubiKey). Expects a `hidraw` device referring to the FIDO2 device (e.g. `/dev/hidraw1`). Alternatively the special value `auto` may be specified, in order to automatically determine the device node of a currently plugged in security token (of which there must be exactly one). This automatic discovery is unsupported if `--unlock-fido2-device=` option is also specified. The special value `list` may be used to enumerate all suitable FIDO2 tokens currently plugged in. Note that many hardware security tokens that implement FIDO2 also implement the older PKCS#11 standard. Typically FIDO2 is preferable, given it is simpler to use and more modern. In order to unlock a LUKS2 volume with an enrolled FIDO2 security token, specify the `fido2-device=` option in the respective `/etc/crypttab` line: myvolume /dev/sda1 none fido2-device=auto See `crypttab(5)` for a more comprehensive example of a `systemd-cryptenroll` invocation and its matching `/etc/crypttab` line. `--fido2-credential-algorithm=STRING` Specify COSE algorithm used in credential generation. The default value is `es256`. Supported values are `es256`, `rs256` and `eddsa`. `es256` denotes ECDSA over NIST P-256 with SHA-256. `rs256` denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. `eddsa` denotes EDDSA over Curve25519 with SHA-512. Note that your authenticator may choose not to support some algorithms. `--fido2-salt-file=PATH` When enrolling a FIDO2 security token, specifies the path to a file or an `AF_UNIX` socket from which we should read the salt value to be used in the HMAC operation performed by the FIDO2 security token. If this option is not specified, the salt will be randomly generated. `--fido2-parameters-in-header=BOOL` When enrolling a FIDO2 security token, controls whether to store FIDO2 parameters in a token in the LUKS2 superblock. Defaults to `yes`. If set to `no`, the `fido2-cid=` option has to be specified manually in the respective `/etc/crypttab` line along with a key file. See `crypttab(5)` for details. `--fido2-with-client-pin=BOOL` When enrolling a FIDO2 security token, controls whether to require the user to enter a PIN when unlocking the volume (the FIDO2 `clientPin` feature). Defaults to `yes`. Note that this setting has no effect if the security token does not support the `clientPin` feature, or does not allow the client PIN requirement to be enabled or disabled for the requested operation. `--fido2-with-user-presence=BOOL` When enrolling a FIDO2 security token, controls whether to require the user to verify presence (tap the token, the FIDO2 `up` feature) when unlocking the volume. Defaults to `yes`. Note that this setting has no effect if the security token does not support the `up` feature, or does not allow the user presence requirement to be enabled or disabled for the requested operation. `--fido2-with-user-verification=BOOL` When enrolling a FIDO2 security token, controls whether to require user verification when unlocking the volume (the FIDO2 `uv` feature). Defaults to `no`. Note that this setting has no effect if the security token does not support the `uv` feature, or does not allow the user verification requirement to be enabled or disabled for the requested operation. # TPM2 Enrollment The following options are understood that may be used to enroll TPM2 devices: `--tpm2-device=PATH` Enroll a TPM2 security chip. Expects a device node path referring to the TPM2 chip (e.g. `/dev/tpmrm0`). Alternatively the special value `auto` may be specified, in order to automatically determine the device node of a currently discovered TPM2 device (of which there must be exactly one). The special value `list` may be used to enumerate all suitable TPM2 devices currently discovered. In order to unlock a LUKS2 volume with an enrolled TPM2 security chip, specify the `tpm2-device=` option in the respective `/etc/crypttab` line: myvolume /dev/sda1 none tpm2-device=auto See `crypttab(5)` for a more comprehensive example of a `systemd-cryptenroll` invocation and its matching `/etc/crypttab` line. Use `--tpm2-pcrs=` (see below) to configure which TPM2 PCR indexes to bind the enrollment to. `--tpm2-device-key=PATH` Enroll a TPM2 security chip using its public key. Expects a path referring to the TPM2 public key in TPM2B_PUBLIC format. This cannot be used with `--tpm2-device=`, as it performs the same operation, but without connecting to the TPM2 security chip; instead the enrollment is calculated using the provided TPM2 key. This is useful in situations where the TPM2 security chip is not available at the time of enrollment. The key, in most cases, should be the Storage Root Key (SRK) from a local TPM2 security chip. If a key from a different handle (not the SRK) is used, you must specify its handle index using `--tpm2-seal-key-handle=`. The `systemd-tpm2-setup.service(8)` service writes the SRK to `/run/systemd/tpm2-srk-public-key.tpm2b_public` automatically during boot, in the correct format. Alternatively, you may use `systemd-analyze srk` to retrieve the SRK from the TPM2 security chip explicitly. See `systemd-analyze(1)` for details. Example: systemd-analyze srk > srk.tpm2b_public `--tpm2-seal-key-handle=HANDLE` Configures which parent key to use for sealing, using the TPM handle (index) of the key. This is used to "seal" (encrypt) a secret and must be used later to "unseal" (decrypt) the secret. Expects a hexadecimal 32bit integer, optionally prefixed with `0x`. Allowable values are any handle index in the persistent (`0x81000000`-`0x81ffffff`) or transient (`0x80000000`-`0x80ffffff`) ranges. Since transient handles are lost after a TPM reset, and may be flushed during TPM context switching, they should not be used except for very specific use cases, e.g. testing. The default is the Storage Root Key (SRK) handle index `0x81000001`. A value of 0 will use the default. For the SRK handle, a new key will be created and stored in the TPM if one does not already exist; for any other handle, the key must already exist in the TPM at the specified handle index. This should not be changed unless you know what you are doing. `--tpm2-pcrs=PCR+PCR...` Configures the TPM2 PCRs (Platform Configuration Registers) to bind to when enrollment is requested via `--tpm2-device=`. Takes a list of PCR entries, where each entry starts with a name or numeric index in the range 0…23, optionally followed by `:` and a hash algorithm name (specifying the PCR bank), optionally followed by `=` and a hash digest value. Multiple PCR entries are separated by `+`. If an empty string is specified, binds the enrollment to no PCRs at all (this is also the default, if this option is not used). See the table above for a list of available PCRs. Example: `--tpm2-pcrs=boot-loader-code+platform-config+boot-loader-config` specifies that PCR registers 4, 1, and 5 should be used. Example: `--tpm2-pcrs=7:sha256` specifies that PCR register 7 from the SHA256 bank should be used. Example: `--tpm2-pcrs=4:sha1=3a3f780f11a4b49969fcaa80cd6e3957c33b2275` specifies that PCR register 4 from the SHA1 bank should be used, and a hash digest value of 3a3f780f11a4b49969fcaa80cd6e3957c33b2275 will be used instead of reading the current PCR value. `--tpm2-with-pin=BOOL|direct` When enrolling a TPM2 device, controls whether to require the user to enter a PIN when unlocking the volume in addition to PCR binding, based on TPM2 policy authentication. Takes a boolean or the special value `direct`. Defaults to `no`. Despite being called PIN, any character can be used, not just numbers. When enabled (`yes`), the PIN is hardened with Argon2id before it is passed to the TPM, making the TPM a second factor rather than a single point of failure: a compromised TPM alone does not expose the volume key without the PIN. When `direct` is used, the PIN is hashed with PBKDF2 and used directly (compatible with systemd v253 and later). Note that incorrect PIN entry when unlocking increments the TPM dictionary attack lockout mechanism, and may lock out users for a prolonged time, depending on its configuration. The lockout mechanism is a global property of the TPM, `systemd-cryptenroll` does not control or configure the lockout mechanism. You may use tpm2-tss tools to inspect or configure the dictionary attack lockout, with `tpm2_getcap(1)` and `tpm2_dictionarylockout(1)` commands, respectively. `--tpm2-argon2id-memory=BYTES` When enrolling a TPM2 with PIN hardening enabled, sets the Argon2id memory cost, in bytes. By default, the memory cost is auto-detected from available RAM (up to 50% of total physical memory), with a minimum of 64 MiB. When specified, the benchmark calibrates only iterations to the target time; the memory cost is used as specified. To express large values comfortably, use suffixes such as `K`, `M`, `G` (for kilobytes, megabytes, gigabytes). `--tpm2-argon2id-iterations=NUM` When enrolling a TPM2 with PIN hardening enabled, sets the Argon2id iteration count. Defaults to auto-calibrated by a benchmark to reach the target unlock time. When specified, the benchmark calibrates only memory cost to the target time; the iteration count is used as specified. `--tpm2-argon2id-parallelism=NUM` When enrolling a TPM2 with PIN hardening enabled, sets the Argon2id parallelism (lane count). Defaults to the number of online CPUs. `--tpm2-argon2id-iter-time=SEC` When enrolling a TPM2 with PIN hardening enabled, sets the target benchmark time for the Argon2id parameter calibration, in seconds. Defaults to 2 seconds. The benchmark adjusts memory cost and/or iteration count so that the actual derivation time falls within a tolerance window of the specified target time. `--tpm2-public-key=PATH`; `--tpm2-public-key-pcrs=PCR+PCR...`; `--tpm2-signature=PATH` Configures a TPM2 signed PCR policy to bind encryption to. The `--tpm2-public-key=` option accepts a path to a PEM encoded RSA public key, to bind the encryption to. If this is not specified explicitly, but a file `tpm2-pcr-public-key.pem` exists in one of the directories `/etc/systemd/`, `/run/systemd/`, `/usr/lib/systemd/` (searched in this order), it is automatically used. The `--tpm2-public-key-pcrs=` option takes a list of TPM2 PCR indexes to bind to (same syntax as `--tpm2-pcrs=` described above). If not specified, defaults to 11 (i.e. this binds the policy to any unified kernel image for which a PCR signature can be provided). Note the difference between `--tpm2-pcrs=` and `--tpm2-public-key-pcrs=`: the former binds decryption to the current, specific PCR values; the latter binds decryption to any set of PCR values for which a signature by the specified public key can be provided. The latter is hence more useful in scenarios where software updates shall be possible without losing access to all previously encrypted LUKS2 volumes. Like with `--tpm2-pcrs=`, names defined in the table above can also be used to specify the registers, for instance `--tpm2-public-key-pcrs=boot-loader-code+system-identity`. The `--tpm2-signature=` option takes a path to a TPM2 PCR signature file as generated by the `systemd-measure(1)` tool. If this is not specified explicitly, a suitable signature file `tpm2-pcr-signature.json` is searched for in `/etc/systemd/`, `/run/systemd/`, `/usr/lib/systemd/` (in this order) and used. If a signature file is specified or found it is used to verify if the volume can be unlocked with it given the current PCR state, before the new slot is written to disk. This is intended as safety net to ensure that access to a volume is not lost if a public key is enrolled for which no valid signature for the current PCR state is available. If the supplied signature does not unlock the current PCR state and public key combination, no slot is enrolled and the operation will fail. If no signature file is specified or found no such safety verification is done. `--tpm2-public-key-policyref=STRING` Configures the policy reference to use together with the signed PCR policy enrolled via `--tpm2-public-key=`. The policy reference is an opaque string that is incorporated into the resulting authorization policy (via the `TPM2_PolicyAuthorize` assertion), so that the slot can only be unlocked by a signed policy that was generated with the same policy reference. This must match the policy reference passed to the `--policyref=` option of `systemd-measure(1)` when the signature was generated. It can be used to bind a slot to signatures for a specific boot phase, even when a single signing key is used to produce signatures for multiple phases. This option can be used to select a policy reference that is only bound to a signature for the initrd phase, in order to create a slot that can only be unlocked from the initrd. For example, if such a signature is created by supplying `--phase=enter-initrd` and `--policyref=initrd` to `systemd-measure(1)`: systemd-cryptenroll --tpm2-device=auto --tpm2-public-key-policyref=initrd /dev/sda1 `--tpm2-pcrlock=PATH` Configures a TPM2 pcrlock policy to bind encryption to. Expects a path to a pcrlock policy file as generated by the `systemd-pcrlock(8)` tool. If a TPM2 device is enrolled and this option is not used but a file `pcrlock.json` is found in `/run/systemd/` or `/var/lib/systemd/` it is automatically used. Assign an empty string to turn this behaviour off. # Other Options The following additional options are understood: `--wipe-slot=SLOT,SLOT...` Wipes one or more LUKS2 key slots. Takes a comma separated list of numeric slot indexes, or the special strings `all` (for wiping all key slots), `empty` (for wiping all key slots that are unlocked by an empty passphrase), `password` (for wiping all key slots that are unlocked by a traditional passphrase), `recovery` (for wiping all key slots that are unlocked by a recovery key), `pkcs11` (for wiping all key slots that are unlocked by a PKCS#11 token), `fido2` (for wiping all key slots that are unlocked by a FIDO2 token), `tpm2` (for wiping all key slots that are unlocked by a TPM2 chip), or any combination of these strings or numeric indexes, in which case all slots matching either are wiped. As safety precaution an operation that wipes all slots without exception (so that the volume cannot be unlocked at all anymore, unless the volume key is known) is refused. This switch may be used alone, in which case only the requested wipe operation is executed. It may also be used in combination with any of the enrollment options listed above, in which case the enrollment is completed first, and only when successful the wipe operation executed — and the newly added slot is always excluded from the wiping. Combining enrollment and slot wiping may thus be used to update existing enrollments: systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto --unlock-tpm2-device=auto The above command will enroll the TPM2 chip, and then wipe all previously created TPM2 enrollments on the LUKS2 volume, leaving only the newly created one. Combining wiping and enrollment may also be used to replace enrollments of different types, for example for changing from a PKCS#11 enrollment to a FIDO2 one: systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto Or for replacing an enrolled empty password by TPM2: systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto `--list-devices` Show a list of candidate block devices this command may operate on. Specifically, this enumerates block devices currently present that contain a LUKS superblock, and shows their device node paths along with any of their symlinks. The devices must implement the `hmac-secret` extension to be usable. # Credentials `systemd-cryptenroll` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `cryptenroll.passphrase`; `cryptenroll.new-passphrase` May contain the passphrase to unlock the volume with/to newly enroll. `cryptenroll.tpm2-pin`; `cryptenroll.new-tpm2-pin` May contain the TPM2 PIN to unlock the volume with/to newly enroll. `cryptenroll.fido2-pin` If a FIDO2 token is enrolled this may contain the PIN of the token. `cryptenroll.pkcs11-pin` If a PKCS#11 token is enrolled this may contain the PIN of the token. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Examples `crypttab(5)` and `systemd-measure(1)` contain various examples employing `systemd-cryptenroll`. # See Also `systemd(1)`, `systemd-cryptsetup@.service(8)`, `crypttab(5)`, `cryptsetup(8)`, `systemd-measure(1)` # systemd-cryptsetup-generator systemd systemd-cryptsetup-generator 8 systemd-cryptsetup-generator Unit generator for /etc/crypttab `/usr/lib/systemd/system-generators/systemd-cryptsetup-generator` # Description `systemd-cryptsetup-generator` is a generator that translates `/etc/crypttab` into native systemd units early at boot and when configuration of the system manager is reloaded. This will create `systemd-cryptsetup@.service(8)` units as necessary. `systemd-cryptsetup-generator` implements `systemd.generator(7)`. # Kernel Command Line `systemd-cryptsetup-generator` understands the following kernel command line parameters: `luks=`; `rd.luks=` Takes a boolean argument. Defaults to `yes`. If `no`, disables the generator entirely. `rd.luks=` is honored only in the initrd while `luks=` is honored by both the main system and in the initrd. `luks.crypttab=`; `rd.luks.crypttab=` Takes a boolean argument. Defaults to `yes`. If `no`, causes the generator to ignore any devices configured in `/etc/crypttab` (`luks.uuid=` will still work however). `rd.luks.crypttab=` is honored only in initrd while `luks.crypttab=` is honored by both the main system and in the initrd. `luks.uuid=`; `rd.luks.uuid=` Takes a LUKS superblock UUID as argument. This will activate the specified device as part of the boot process as if it was listed in `/etc/crypttab`. This option may be specified more than once in order to set up multiple devices. `rd.luks.uuid=` is honored only in the initrd, while `luks.uuid=` is honored by both the main system and in the initrd. If `/etc/crypttab` contains entries with the same UUID, then the name, keyfile and options specified there will be used. Otherwise, the device will have the name `luks-UUID`. If `/etc/crypttab` exists, only those UUIDs specified on the kernel command line will be activated in the initrd or the real root. `luks.name=`; `rd.luks.name=` Takes a LUKS super block UUID followed by an `=` and a name. This implies `rd.luks.uuid=` or `luks.uuid=` and will additionally make the LUKS device given by the UUID appear under the provided name. This parameter is the analogue of the first `crypttab(5)` field \. `rd.luks.name=` is honored only in the initrd, while `luks.name=` is honored by both the main system and in the initrd. `luks.data=`; `rd.luks.data=` Takes a LUKS super block UUID followed by a `=` and a block device specification for device hosting encrypted data. For those entries specified with `rd.luks.uuid=` or `luks.uuid=`, the data device will be set to the one specified by `rd.luks.data=` or `luks.data=` of the corresponding UUID. LUKS data device parameter is useful for specifying encrypted data devices with detached headers specified in `luks.options` entry containing `header=` argument. For example, `rd.luks.uuid=`b40f1abf-2a53-400a-889a-2eccc27eaa40 `rd.luks.options=`b40f1abf-2a53-400a-889a-2eccc27eaa40=header=/path/to/luks.hdr `rd.luks.data=`b40f1abf-2a53-400a-889a-2eccc27eaa40=/dev/sdx. Hence, in this case, we will attempt to unlock LUKS device assembled from data device `/dev/sdx` and LUKS header (metadata) put in `/path/to/luks.hdr` file. This syntax is for now only supported on a per-device basis, i.e. you have to specify LUKS device UUID. This parameter is the analogue of the second `crypttab(5)` field \. `rd.luks.data=` is honored only in the initrd, while `luks.data=` is honored by both the main system and in the initrd. `luks.key=`; `rd.luks.key=` Takes a password file name as argument or a LUKS super block UUID followed by a `=` and a password file name. For those entries specified with `rd.luks.uuid=` or `luks.uuid=`, the password file will be set to the one specified by `rd.luks.key=` or `luks.key=` of the corresponding UUID, or the password file that was specified without a UUID. It is also possible to specify an external device which should be mounted before we attempt to unlock the LUKS device. systemd-cryptsetup will use password file stored on that device. Device containing password file is specified by appending colon and a device identifier to the password file path. For example, `rd.luks.uuid=`b40f1abf-2a53-400a-889a-2eccc27eaa40 `rd.luks.key=`b40f1abf-2a53-400a-889a-2eccc27eaa40=/keyfile:LABEL=keydev. Hence, in this case, we will attempt to mount file system residing on the block device with label `keydev`. This syntax is for now only supported on a per-device basis, i.e. you have to specify LUKS device UUID. This parameter is the analogue of the third `crypttab(5)` field \. `rd.luks.key=` is honored only in the initrd, while `luks.key=` is honored by both the main system and in the initrd. `luks.options=`; `rd.luks.options=` Takes a LUKS super block UUID followed by an `=` and a string of options separated by commas as argument. This will override the options for the given UUID. If only a list of options, without a UUID, is specified, they apply to any UUIDs not specified elsewhere, and without an entry in `/etc/crypttab`. This parameter is the analogue of the fourth `crypttab(5)` field \. It is possible to specify an external device which should be mounted before we attempt to unlock the LUKS device. systemd-cryptsetup will assemble LUKS device by combining data device specified in `luks.data` with detached LUKS header found in `header=` argument. For example, `rd.luks.uuid=`b40f1abf-2a53-400a-889a-2eccc27eaa40 `rd.luks.options=`b40f1abf-2a53-400a-889a-2eccc27eaa40=header=/luks.hdr:LABEL=hdrdev `rd.luks.data=`b40f1abf-2a53-400a-889a-2eccc27eaa40=/dev/sdx. Hence, in this case, we will attempt to mount file system residing on the block device with label `hdrdev`, and look for `luks.hdr` on that file system. Said header will be used to unlock (decrypt) encrypted data stored on /dev/sdx. This syntax is for now only supported on a per-device basis, i.e. you have to specify LUKS device UUID. `rd.luks.options=` is honored only by initial RAM disk (initrd) while `luks.options=` is honored by both the main system and in the initrd. # See Also `systemd(1)`, `crypttab(5)`, `systemd-cryptsetup@.service(8)`, `systemd-cryptenroll(1)`, `cryptsetup(8)`, `systemd-fstab-generator(8)` # systemd-cryptsetup systemd systemd-cryptsetup 8 systemd-cryptsetup systemd-cryptsetup@.service Full disk decryption logic systemd-cryptsetup OPTIONS attach VOLUME SOURCE-DEVICE KEY-FILE CRYPTTAB-OPTIONS systemd-cryptsetup OPTIONS detach VOLUME `systemd-cryptsetup@.service` `system-systemd\x2dcryptsetup.slice` # Description `systemd-cryptsetup` is used to set up (with `attach`) and tear down (with `detach`) access to an encrypted block device. It is primarily used via `systemd-cryptsetup@.service` during early boot, but may also be called manually. The positional arguments `VOLUME`, `SOURCE-DEVICE`, `KEY-FILE`, and `CRYPTTAB-OPTIONS` have the same meaning as the fields in `crypttab(5)`. `systemd-cryptsetup@.service` is a service responsible for providing access to encrypted block devices. It is instantiated for each device that requires decryption. `systemd-cryptsetup@.service` instances are part of the `system-systemd\x2dcryptsetup.slice` slice, which is destroyed only very late in the shutdown procedure. This allows the encrypted devices to remain up until filesystems have been unmounted. `systemd-cryptsetup@.service` will ask for hard disk passwords via the [password agent logic](https://systemd.io/PASSWORD_AGENTS/), in order to query the user for the password using the right mechanism at boot and during runtime. At early boot and when the system manager configuration is reloaded, `/etc/crypttab` is translated into `systemd-cryptsetup@.service` units by `systemd-cryptsetup-generator(8)`. In order to unlock a volume a password or binary key is required. `systemd-cryptsetup@.service` tries to acquire a suitable password or binary key via the following mechanisms, tried in order: 1. If a key file is explicitly configured (via the third column in `/etc/crypttab`), a key read from it is used. If a PKCS#11 token, FIDO2 token or TPM2 device is configured (using the `pkcs11-uri=`, `fido2-device=`, `tpm2-device=` options) the key is decrypted before use. 2. If no key file is configured explicitly this way, a key file is automatically loaded from `/etc/cryptsetup-keys.d/volume.key` and `/run/cryptsetup-keys.d/volume.key`, if present. Here too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before use. 3. If the `try-empty-password` option is specified then unlocking the volume with an empty password is attempted. 4. If the `password-cache=` option is set to `yes` or `read-only`, the kernel keyring is then checked for a suitable cached password from previous attempts. 5. Finally, the user is queried for a password, possibly multiple times, unless the `headless` option is set. If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails. # Credentials `systemd-cryptsetup` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used by `systemd-crypsetup@root.service` (generated by `systemd-gpt-auto-generator`) when passed in: `cryptsetup.passphrase` This credential specifies the passphrase of the LUKS volume. `cryptsetup.tpm2-pin` This credential specifies the TPM pin. `cryptsetup.fido2-pin` This credential specifies the FIDO2 token pin. `cryptsetup.pkcs11-pin` This credential specifies the PKCS11 token pin. `cryptsetup.luks2-pin` This credential specifies the pin requested by generic LUKS2 token modules. # See Also `systemd(1)`, `systemd-cryptsetup-generator(8)`, `crypttab(5)`, `systemd-cryptenroll(1)`, `cryptsetup(8)`, [TPM2 PCR Measurements Made by systemd](https://systemd.io/TPM2_PCR_MEASUREMENTS) # systemd-delta systemd systemd-delta 1 systemd-delta Find overridden configuration files systemd-delta OPTIONS PREFIX PREFIX / SUFFIX SUFFIX # Description `systemd-delta` may be used to identify and compare configuration files that override other configuration files. Files in `/etc/` have highest priority, files in `/run/` have the second highest priority, …, files in `/usr/lib/` have lowest priority. Files in a directory with higher priority override files with the same name in directories of lower priority. In addition, certain configuration files can have `.d` directories which contain "drop-in" files with configuration snippets which augment the main configuration file. "Drop-in" files can be overridden in the same way by placing files with the same name in a directory of higher priority (except that, in case of "drop-in" files, both the "drop-in" file name and the name of the containing directory, which corresponds to the name of the main configuration file, must match). For a fuller explanation, see `systemd.unit(5)`. The command line argument will be split into a prefix and a suffix. Either is optional. The prefix must be one of the directories containing configuration files (`/etc/`, `/run/`, `/usr/lib/`, …). If it is given, only overriding files contained in this directory will be shown. Otherwise, all overriding files will be shown. The suffix must be a name of a subdirectory containing configuration files like `tmpfiles.d`, `sysctl.d` or `systemd/system`. If it is given, only configuration files in this subdirectory (across all configuration paths) will be analyzed. Otherwise, all configuration files will be analyzed. If the command line argument is not given at all, all configuration files will be analyzed. See below for some examples. # Options The following options are understood: `-t`; `--type=` When listing the differences, only list those that are asked for. The list itself is a comma-separated list of desired difference types. Recognized types are: `masked` Show masked files `equivalent` Show overridden files that while overridden, do not differ in content. `redirected` Show files that are redirected to another. `overridden` Show overridden, and changed files. `extended` Show `*.conf` files in drop-in directories for units. `unchanged` Show unmodified files too. `--diff=` When showing modified files, when a file is overridden show a diff as well. This option takes a boolean argument. If omitted, it defaults to `true`. # Examples To see all local configuration: systemd-delta To see all runtime configuration: systemd-delta /run To see all system unit configuration changes: systemd-delta systemd/system To see all runtime "drop-in" changes for system units: systemd-delta --type=extended /run/systemd/system # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd.unit(5)` # systemd-detect-virt systemd systemd-detect-virt 1 systemd-detect-virt Detect execution in a virtualized environment systemd-detect-virt OPTIONS # Description `systemd-detect-virt` detects execution in a virtualized environment. It identifies the virtualization technology and can distinguish full machine virtualization from container virtualization. `systemd-detect-virt` exits with a return value of 0 (success) if a virtualization technology is detected, and non-zero (error) otherwise. By default, any type of virtualization is detected, and the options `--container` and `--vm` can be used to limit what types of virtualization are detected. When executed without `--quiet` will print a short identifier for the detected virtualization technology. The following technologies are currently identified:
Known virtualization technologies (both VM, i.e. full hardware virtualization, and container, i.e. shared kernel virtualization)
Type ID Product
VM qemu QEMU software virtualization, without KVM
kvm Linux KVM kernel virtual machine, in combination with QEMU. Not used for other virtualizers using the KVM interfaces, such as Oracle VirtualBox or Amazon EC2 Nitro, see below.
amazon Amazon EC2 Nitro using Linux KVM
zvm s390 z/VM
vmware VMware Workstation or Server, and related products
microsoft Hyper-V, also known as Viridian or Windows Server Virtualization
oracle Oracle VM VirtualBox (historically marketed by innotek and Sun Microsystems), for legacy and KVM hypervisor
powervm IBM PowerVM hypervisor — comes as firmware with some IBM POWER servers
xen Xen hypervisor (only domU, not dom0)
bochs Bochs Emulator
uml User-mode Linux
parallels Parallels Desktop, Parallels Server
bhyve bhyve, FreeBSD hypervisor
qnx QNX hypervisor
acrn ACRN hypervisor
apple Apple virtualization framework
sre LMHS SRE hypervisor
google Google Compute Engine
Container openvz OpenVZ/Virtuozzo
lxc Linux container implementation by LXC
lxc-libvirt Linux container implementation by libvirt
systemd-nspawn systemd's minimal container implementation, see systemd-nspawn(1)
docker Docker container manager
podman Podman container manager
rkt rkt app container runtime
wsl Windows Subsystem for Linux
proot proot userspace chroot/bind mount emulation
pouch Pouch Container Engine
If multiple virtualization solutions are used, only the "innermost" is detected and identified. That means if both machine and container virtualization are used in conjunction, only the latter will be identified (unless `--vm` is passed). Windows Subsystem for Linux is not a Linux container, but an environment for running Linux userspace applications on top of the Windows kernel using a Linux-compatible interface. WSL is categorized as a container for practical purposes. Multiple WSL environments share the same kernel and services should generally behave like when being run in a container. When executed with `--cvm`, instead of printing the virtualization technology, it will display the confidential virtual machine technology, if any. The following technologies are currently identified:
Known confidential virtualization technologies
Arch ID
x86_64 sev
sev-es
sev-snp
tdx
s390x protvirt
arm64 cca
# Options The following options are understood: `-c`; `--container` Only detects container virtualization (i.e. shared kernel virtualization). `-v`; `--vm` Only detects hardware virtualization. `-r`; `--chroot` Detect whether invoked in a `chroot(2)` environment. In this mode, no output is written, but the return value indicates whether the process was invoked in a `chroot()` environment or not. `--private-users` Detect whether invoked in a user namespace. In this mode, no output is written, but the return value indicates whether the process was invoked inside of a user namespace or not. See `user_namespaces(7)` for more information. `--cvm` Detect whether invoked in a confidential virtual machine. The result of this detection may be used to disable features that should not be used in confidential VMs. It must not be used to release security sensitive information. The latter must only be released after attestation of the confidential environment. `-q`; `--quiet` Suppress output of the virtualization technology identifier. `--list` Output all currently known and detectable container and VM environments. `--list-cvm` Output all currently known and detectable confidential virtualization technologies. # Exit status If a virtualization technology is detected, 0 is returned, a non-zero code otherwise. # See Also `systemd(1)`, `systemd-nspawn(1)`, `chroot(2)`, `namespaces(7)` # systemd-dissect systemd systemd-dissect 1 systemd-dissect mount.ddi Dissect Discoverable Disk Images (DDIs) systemd-dissect OPTIONS IMAGE systemd-dissect OPTIONS --mount IMAGE PATH systemd-dissect OPTIONS --umount PATH systemd-dissect OPTIONS --attach IMAGE systemd-dissect OPTIONS --detach PATH systemd-dissect OPTIONS --list IMAGE systemd-dissect OPTIONS --mtree IMAGE systemd-dissect OPTIONS --with IMAGE COMMAND systemd-dissect OPTIONS --copy-from IMAGE PATH TARGET systemd-dissect OPTIONS --copy-to IMAGE SOURCE PATH systemd-dissect OPTIONS --make-archive IMAGE TARGET systemd-dissect OPTIONS --discover systemd-dissect OPTIONS --validate IMAGE systemd-dissect OPTIONS --shift IMAGE UIDBASE # Description `systemd-dissect` is a tool for introspecting and interacting with file system OS disk images, specifically Discoverable Disk Images (DDIs). It supports four different operations: 1. Show general OS image information, including the image's `os-release(5)` data, machine ID, partition information and more. 2. Mount an OS image to a local directory. In this mode it will dissect the OS image and mount the included partitions according to their designation onto a directory and possibly sub-directories. 3. Unmount an OS image from a local directory. In this mode it will recursively unmount the mounted partitions and remove the underlying loop device, including all the partition sub-devices. 4. Copy files and directories in and out of an OS image. The tool may operate on three types of OS images: 1. OS disk images containing a GPT partition table envelope, with partitions marked according to the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). 2. OS disk images containing just a plain file-system without an enveloping partition table. (This file system is assumed to be the root file system of the OS.) 3. OS disk images containing a GPT or MBR partition table, with a single partition only. (This partition is assumed to contain the root file system of the OS.) OS images may use any kind of Linux-supported file systems. In addition they may make use of LUKS disk encryption, and contain Verity integrity information. Note that qualifying OS images may be booted with `systemd-nspawn(1)`'s `--image=` switch, and be used as root file system for system service using the `RootImage=` unit file setting, see `systemd.exec(5)`. Note that the partition table shown when invoked without command switch (as listed below) does not necessarily show all partitions included in the image, but just the partitions that are understood and considered part of an OS disk image. Specifically, partitions of unknown types are ignored, as well as duplicate partitions (i.e. more than one per partition type), as are root and `/usr/` partitions of architectures not compatible with the local system. In other words: this tool will display what it operates with when mounting the image. To display the complete list of partitions use a tool such as `fdisk(8)`. The `systemd-dissect` command may be invoked as `mount.ddi` in which case it implements the `mount(8)` "external helper" interface. This ensures disk images compatible with `systemd-dissect` can be mounted directly by `mount` and `fstab(5)`. For details see below. # Commands If neither of the command switches listed below are passed the specified disk image is opened and general information about the image and the contained partitions and their use is shown. `--mount`; `-m` Mount the specified OS image to the specified directory. This will dissect the image, determine the OS root file system — as well as possibly other partitions — and mount them to the specified directory. If the OS image contains multiple partitions marked with the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification) multiple nested mounts are established. This command expects two arguments: a path to an image file and a path to a directory where to mount the image. To unmount an OS image mounted like this use the `--umount` operation. When the OS image contains LUKS encrypted or Verity integrity protected file systems appropriate volumes are automatically set up and marked for automatic disassembly when the image is unmounted. LUKS volumes carrying a TPM2 token (as enrolled via the `--tpm2-device=` option of `systemd-cryptenroll(1)`) are unlocked via the local TPM2 automatically, before a passphrase is requested. This may be turned off via the `$SYSTEMD_DISSECT_TPM2_UNLOCK` environment variable. Note that this requires privileges: when invoked unprivileged, images are mounted via `systemd-mountfsd.service(8)`, which does not currently support unlocking via TPM2. The OS image may either be specified as path to an OS image stored in a regular file or may refer to block device node (in the latter case, the block device must be the "whole" device, i.e. not a partition device). (The other supported commands described here support this, too.) All mounted file systems are checked with the appropriate `fsck(8)` implementation in automatic fixing mode, unless explicitly turned off (`--fsck=no`) or read-only operation is requested (`--read-only`). Note that this functionality is also available in `mount(8)` via a command such as `mount -t ddi myimage.raw targetdir/`, as well as in `fstab(5)`. For details, see below. `-M` This is a shortcut for `--mount --mkdir`. `--umount`; `-u` Unmount an OS image from the specified directory. This command expects one argument: a directory where an OS image was mounted. All mounted partitions will be recursively unmounted, and the underlying loop device will be removed, along with all its partition sub-devices. `-U` This is a shortcut for `--umount --rmdir`. `--attach` Attach the specified disk image to an automatically allocated loopback block device, and print the path to the loopback block device to standard output. This is similar to an invocation of `losetup --find --show --partscan`, but will validate the image as DDI before attaching, and derive the correct sector size to use automatically. Moreover, it ensures the per-partition block devices are created before returning and attempts to enable direct IO mode, if possible. Takes a path to a disk image file. Use `--relax` to attach images that do not qualify as DDI. If combined with `--quiet` output of the block device name is suppressed. `--detach` Detach the specified disk image from a loopback block device. This undoes the effect of `--attach` above. This expects either a path to a loopback block device as an argument, or the path to the backing image file. In the latter case, it will automatically determine the right device to detach. `--list`; `-l` Prints the paths of all the files and directories in the specified OS image or directory to standard output. `--mtree` Generates a BSD `mtree(8)` compatible file manifest of the specified disk image or directory. This is useful for comparing image contents in detail, including inode information and other metadata. While the generated manifest will contain detailed inode information, it currently excludes extended attributes, file system capabilities, MAC labels, `chattr(1)` file flags, `btrfs(5)` subvolume information, and various other file metadata. File content information is shown via a SHA256 digest. Additional fields might be added in future. Note that inode information such as link counts, inode numbers and timestamps is excluded from the output on purpose, as it typically complicates reproducibility. `--with` Runs the specified command with the specified OS image mounted. This will mount the image to a temporary directory, switch the current working directory to it, and invoke the specified command line as child process. Once the process ends it will unmount the image again, and remove the temporary directory. If no command is specified a shell is invoked. The image is mounted writable, use `--read-only` to switch to read-only operation. The invoked process will have the `$SYSTEMD_DISSECT_ROOT` environment variable set, containing the absolute path name of the temporary mount point, i.e. the same directory that is set as the current working directory. It will also have the `$SYSTEMD_DISSECT_DEVICE` environment variable set, containing the absolute path name of the loop device the image was attached to. `--copy-from`; `-x` Copies a file or directory from the specified OS image or directory into the specified location on the host file system. Expects three arguments: a path to an image file or directory, a source path (relative to the image's root directory) and a destination path (relative to the current working directory, or an absolute path, both outside of the image). If the destination path is omitted or specified as dash (`-`), the specified file is written to standard output. If the source path in the image file system refers to a regular file it is copied to the destination path. In this case, access mode, extended attributes and timestamps are copied as well, but file ownership is not. If the source path in the image refers to a directory, it is copied to the destination path, recursively with all containing files and directories, merging into existing directories and updating already existing files. In this case, the file ownership is copied too. `--copy-to`; `-a` Copies a file or directory from the specified location in the host file system into the specified OS image or directory. Expects three arguments: a path to an image file or directory, a source path (relative to the current working directory, or an absolute path, both outside of the image) and a destination path (relative to the image's root directory). If the source path is omitted or specified as dash (`-`), the data to write is read from standard input. If the source path in the host file system refers to a regular file, it is copied to the destination path. In this case, access mode, extended attributes and timestamps are copied as well, but file ownership is not. If the source path in the host file system refers to a directory it is copied to the destination path, recursively with all containing files and directories, merging into existing directories and updating already existing files.. In this case, the file ownership is copied too. As with `--mount` file system checks are implicitly run before the copy operation begins. `--make-archive` Generates an archive file from the specified disk image. Expects two arguments: the path to the disk image and optionally the output archive file path. If the latter is omitted the archive is written to standard output. The archive file format is determined automatically from the specified output archive file name, e.g. any path suffixed with `.tar.xz` will result in an xz compressed UNIX tarball (if the path is omitted an uncompressed UNIX tarball is created). See `libarchive(3)` for a list of supported archive formats and compression schemes. `--discover` Show a list of DDIs in well-known directories. This will show machine, portable service and system/configuration extension disk images in the usual directories `/usr/lib/machines/`, `/usr/lib/portables/`, `/usr/lib/confexts/`, `/var/lib/machines/`, `/var/lib/portables/`, `/var/lib/extensions/` and so on. `--validate` Validates the partition arrangement of a disk image (DDI), and ensures it matches the image policy specified via `--image-policy=`, if one is specified. This parses the partition table and probes the file systems in the image, but does not attempt to mount them (nor to set up disk encryption/authentication via LUKS/Verity). It does this taking the configured image dissection policy into account. Since this operation does not mount file systems, this command – unlike all other commands implemented by this tool – requires no privileges other than the ability to access the specified file. Prints "OK" and returns zero if the image appears to be in order and matches the specified image dissection policy. Otherwise, prints an error message and returns non-zero. `--shift` Recursively iterates through all inodes of the specified image and shifts the UIDs and GIDs the inodes are owned by into the specified UID range. Takes an image path and a UID base as parameter. The UID base can be specified numerically (in which case it must be a multiple of 65536, and either 0 or within the container or foreign UID range, as per [Users, Groups, UIDs and GIDs on systemd Systems](https://systemd.io/UIDS-GIDS/)), or as the symbolic identifier `foreign` which is shorthand to the foreign UID base. This command is useful for preparing directory container images for unprivileged use. Note that this command is intended for images that use the 16bit UIDs/GIDs range only, and it always ignores the upper 16bit of the current UID/GID ownership, combining the lower 16 bit with the target UID base. Use `systemd-dissect --shift /some/container/tree foreign` to shift a container image into the foreign UID range, or `systemd-dissect --shift /some/container/tree 0` to shift it to host UID range. # Options The following options are understood: `--read-only`; `-r` Operate in read-only mode. By default, `--mount` will establish writable mount points. If this option is specified they are established in read-only mode instead. `--fsck=no` Turn off automatic file system checking. By default, when an image is accessed for writing (by `--mount` or `--copy-to`) the file systems contained in the OS image are automatically checked using the appropriate `fsck(8)` command, in automatic fixing mode. This behavior may be switched off using `--fsck=no`. `--growfs=no` Turn off automatic growing of accessed file systems to their partition size, if marked for that in the GPT partition table. By default, when an image is accessed for writing (by `--mount` or `--copy-to`) the file systems contained in the OS image are automatically grown to their partition sizes, if bit 59 in the GPT partition flags is set for partition types that are defined by the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). This behavior may be switched off using `--growfs=no`. File systems are grown automatically on access if all of the following conditions are met: 1. The file system is mounted writable 2. The file system currently is smaller than the partition it is contained in (and thus can be grown) 3. The image contains a GPT partition table 4. The file system is stored on a partition defined by the Discoverable Partitions Specification 5. Bit 59 of the GPT partition flags for this partition is set, as per specification 6. The `--growfs=no` option is not passed. `--mkdir` If combined with `--mount` the directory to mount the OS image to is created if it is missing. Note that the directory is not automatically removed when the disk image is unmounted again. `--rmdir` If combined with `--umount` the specified directory where the OS image is mounted is removed after unmounting the OS image. `--discard=` Takes one of `disabled`, `loop`, `all`, `crypto`. If `disabled` the image is accessed with empty block discarding turned off. If `loop` discarding is enabled if operating on a regular file. If `crypt` discarding is enabled even on encrypted file systems. If `all` discarding is unconditionally enabled. `--in-memory` If specified an in-memory copy of the specified disk image is used. This may be used to operate with write-access on a (possibly read-only) image, without actually modifying the original file. This may also be used in order to operate on a disk image without keeping the originating file system busy, in order to allow it to be unmounted. `--root-hash=`; `--root-hash-sig=`; `--verity-data=` Configure various aspects of Verity data integrity for the OS image. Option `--root-hash=` specifies a hex-encoded top-level Verity hash to use for setting up the Verity integrity protection. Option `--root-hash-sig=` specifies the path to a file containing a PKCS#7 signature for the hash. This signature is passed to the kernel during activation, which will match it against signature keys available in the kernel keyring. If the kernel cannot validate it, the signature is checked against the certificates in `/etc/verity.d/`. If neither validates the signature, the image is only used if the image policy allows `verity` for the partition, see `--image-policy=`. Option `--verity-data=` specifies a path to a file with the Verity data to use for the OS image, in case it is stored in a detached file. It is recommended to embed the Verity data directly in the image, using the Verity mechanisms in the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). `--usr-hash=`; `--usr-hash-sig=` Similar to `--root-hash=` and `--root-hash-sig=`, but specifies hash and signature for the `/usr/` partition. Note that either the options for the root partition may be used or the ones for the `/usr/`, but not both in combination. `--loop-ref=` Configures the "reference" string the kernel shall report as backing file for the loopback block device. While this is supposed to be a path or filename referencing the backing file, this is not enforced and the kernel accepts arbitrary free-form strings, chosen by the user. Accepts arbitrary strings up to a length of 63 characters. This sets the kernel's `.lo_file_name` field for the block device. Note this is distinct from the `/sys/class/block/loopX/loop/backing_file` attribute file that always reports a path referring to the actual backing file. The latter is subject to mount namespace translation, the former is not. This setting is particularly useful in combination with the `--attach` command, as it allows later referencing the allocated loop device via `/dev/disk/by-loop-ref/…` symlinks. Example: first, set up the loopback device via `systemd-dissect attach --loop-ref=quux foo.raw`, and then reference it in a command via the specified filename: `cfdisk /dev/disk/by-loop-ref/quux`. `--loop-ref-auto` Similar to `--loop-ref=`, but automatically derive the reference string from the specified backing filename, truncating it if necessary. `--relax` If combined with `--attach`, skips validation of the image and attaches it to the loopback block device as it is, even if it does not qualify as DDI. If this switch is used, no image dissection takes place, and thus it is not guaranteed that the per-partition block devices are created before the command returns. May not be combined with any other command than `--attach`. `--mtree-hash=no` If combined with `--mtree`, turns off inclusion of file hashes in the mtree output. This makes the `--mtree` faster when operating on large images. `--copy-ownership=` Controls whether file ownership (user and group) is preserved when copying files with `--copy-from` or `--copy-to`. Takes a boolean, or `auto`. If `yes`, ownership is always preserved. If `no`, ownership is never preserved and the current user's UID/GID is used instead. If not specified or `auto`, ownership is preserved when copying directory trees, but not when copying individual regular files. `--system`; `--user` When used together with `--discover` controls whether to search for images installed system-wide or in the user's directories in `$HOME`. If neither switch is specified, will search within both scopes. `--all` If combined with `--discover`, also shows images that start with a dot, i.e. hidden images. `--quiet`; `-q` If combined with `--attach`, suppresses output of the used loopback block device path. # Exit status On success, 0 is returned, a non-zero failure code otherwise. If the `--with` command is used the exit status of the invoked command is propagated. # Invocation as `/sbin/mount.ddi` The `systemd-dissect` executable may be symlinked to `/sbin/mount.ddi`. If invoked through that it implements `mount(8)`'s "external helper" interface for the (pseudo) file system type `ddi`. This means conformant disk images may be mounted directly via # mount -t ddi myimage.raw targetdir/ in a fashion mostly equivalent to: # systemd-dissect --mount myimage.raw targetdir/ Note that since a single DDI may contain multiple file systems it should later be unmounted with `umount -R targetdir/`, for recursive operation. This functionality is particularly useful to mount DDIs automatically at boot via simple `/etc/fstab` entries. For example: /path/to/myimage.raw /images/myimage/ ddi defaults 0 0 When invoked this way the mount options `ro`, `rw`, `discard`, `nodiscard` map to the corresponding options listed above (i.e. `--read-only`, `--discard=all`, `--discard=disabled`). Mount options are *not* generically passed on to the file systems inside the images. # Examples
Generate a tarball from an OS disk image (`--with`)
# systemd-dissect --with foo.raw tar cz . >foo.tar.gz
or alternatively just:
Generate a tarball from an OS disk image (`--make-archive`)
# systemd-dissect --make-archive foo.raw foo.tar.gz
# See Also `systemd(1)`, `systemd-nspawn(1)`, `systemd.exec(5)`, `systemd.v(7)`, [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification), `mount(8)`, `umount(8)`, `fdisk(8)` # systemd-efivars-clear.service systemd systemd-efivars-clear.service 8 systemd-efivars-clear.service Request that the boot loader's EFI variables are erased on next boot `systemd-efivars-clear.service` `/usr/lib/systemd/systemd-efivars-clear` # Description `systemd-efivars-clear.service` is a service that requests that `systemd-boot(7)` erases all EFI variables owned by the boot loader and by systemd on the next boot. It does so by setting the `LoaderFactoryResetVariables` EFI variable. Note that this service does not immediately erase any variables, but simply asks the boot loader to do so at next boot, where the user will be asked for confirmation before the operation is done. After erasing the variables the boot loader reboots the system. The EFI variables erased are all those in the Boot Loader Interface vendor UUID namespace (`4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`) and in systemd's own vendor UUID namespace (`8cf2644b-4b0b-428f-9387-6d876050dc67`), with the exception of the `FactoryResetRequest` variable, which is retained so that the factory reset of the OS itself can take place on the subsequent boot. `systemd-efivars-clear.service` is typically hooked into the `factory-reset.target` unit in order to issue the request before an immediate reboot. A pending request is withdrawn again by `systemd-factory-reset cancel`, see `systemd-factory-reset(8)`. See [Factory Reset](https://systemd.io/FACTORY_RESET) for more information. # Options The following options are understood: `--graceful` Exit cleanly and execute no operation if the system was not booted via UEFI, or the boot loader does not support erasing EFI variables. # Kernel Command Line `systemd-efivars-clear` understands the following kernel command line parameters: `systemd.efivars_allow_clear=` Takes a boolean argument. If false the service will succeed, but instead of requesting the erase operation from the boot loader it will not execute any operation. If not specified defaults to true. # See Also `systemd(1)`, `systemd-boot(7)`, `systemd-tpm2-clear.service(8)`, `systemd-factory-reset-request.service(8)` # systemd-escape systemd systemd-escape 1 systemd-escape Escape strings for usage in systemd unit names systemd-escape OPTIONS STRING systemd-escape OPTIONS --stdin # Description `systemd-escape` may be used to escape strings for inclusion in systemd unit names. The command may be used to escape and to undo escaping of strings. The command takes any number of strings on the command line, and will process them individually, one after another. It will output them separated by spaces to stdout. If `--stdin` is specified, strings are instead read from standard input, one per line, and the result for each input line is written on a separate output line. By default, this command will escape the strings passed, unless `--unescape` is passed which results in the inverse operation being applied. If `--mangle` is given, a special mode of escaping is applied instead, which assumes the string is already escaped but will escape everything that appears obviously non-escaped. For details on the escaping and unescaping algorithms see the relevant section in `systemd.unit(5)`. # Options The following options are understood: `--suffix=` Appends the specified unit type suffix to the escaped string. Takes one of the unit types supported by systemd, such as `service` or `mount`. May not be used in conjunction with `--template=`, `--unescape` or `--mangle`. `--template=` Inserts the escaped strings in a unit name template. Takes a unit name template such as `foobar@.service`. With `--unescape`, expects instantiated unit names for this template and extracts and unescapes just the instance part. May not be used in conjunction with `--suffix=`, `--instance` or `--mangle`. `--stdin` Read strings from standard input, one per line, instead of from the command line. The line ending is not included in the string to escape or unescape, and the result for each line is written on a separate output line. This option may not be combined with command line strings. `--path`; `-p` When escaping or unescaping a string, assume it refers to a file system path. This simplifies the path (leading, trailing, and duplicate `/` characters are removed, no-op path `.` components are removed, and for absolute paths, leading `..` components are removed). After the simplification, the path must not contain `..`. This is particularly useful for generating strings suitable for unescaping with the `%f` specifier in unit files, see `systemd.unit(5)`. `--unescape`; `-u` Instead of escaping the specified strings, undo the escaping, reversing the operation. May not be used in conjunction with `--suffix=` or `--mangle`. `--mangle`; `-m` Like `--escape`, but only escape characters that are obviously not escaped yet, and possibly automatically append an appropriate unit type suffix to the string. May not be used in conjunction with `--suffix=`, `--template=` or `--unescape`. `--instance` With `--unescape`, unescape and print only the instance part of an instantiated unit name template. Results in an error for an uninstantiated template like `ssh@.service` or a non-template name like `ssh.service`. Must be used in conjunction with `--unescape` and may not be used in conjunction with `--template`. # Examples To escape a single string: $ systemd-escape 'Hallöchen, Meister' Hall\xc3\xb6chen\x2c\x20Meister To undo escaping on a single string: $ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister' Hallöchen, Meister To generate the mount unit for a path: $ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/" tmp-waldi-foobar.mount To generate instance names of three strings: $ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III' systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service To generate instance names from standard input: $ printf '%s\n' 'My Container 1' 'container/III' | systemd-escape --stdin --template=systemd-nspawn@.service systemd-nspawn@My\x20Container\x201.service systemd-nspawn@container-III.service To extract the instance part of an instantiated unit: $ systemd-escape -u --instance 'systemd-nspawn@My\x20Container\x201.service' My Container 1 To extract the instance part of an instance of a particular template: $ systemd-escape -u --template=systemd-nspawn@.service 'systemd-nspawn@My\x20Container\x201.service' My Container 1 # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd.unit(5)`, `systemctl(1)` # systemd-factory-reset-generator systemd systemd-factory-reset-generator 8 systemd-factory-reset-generator Pull factory-reset-now.target into the initial boot transaction when factory reset has been requested `/usr/lib/systemd/system-generators/systemd-factory-reset-generator` # Description `systemd-factory-reset-generator` is a generator that pulls `factory-reset-now.target` into the initial boot transaction when the factory reset operation has been requested, either via the `systemd.factory_reset=` kernel command line option or via the `FactoryResetRequest` EFI variable. `systemd-factory-reset-generator` implements `systemd.generator(7)`. # See Also `systemd(1)`, `systemd-factory-reset(8)`, [Factory Reset](https://systemd.io/FACTORY_RESET) # systemd-factory-reset systemd systemd-factory-reset 8 systemd-factory-reset systemd-factory-reset-request.service systemd-factory-reset-complete.service systemd-factory-reset.socket systemd-factory-reset@.service Request or complete a factory reset operation, or query current factory reset mode `/usr/lib/systemd/systemd-factory-reset` `systemd-factory-reset-request.service` `systemd-factory-reset-complete.service` `systemd-factory-reset.socket` `systemd-factory-reset@.service` # Description `systemd-factory-reset` is a tool that can query the current factory reset state, request factory reset operations or complete them. Some of the functionality is also available via the `/run/systemd/io.systemd.FactoryReset` Varlink service (implemented via the `systemd-factory-reset.socket`/`systemd-factory-reset@.service` units). See [Factory Reset](https://systemd.io/FACTORY_RESET) for an overview of the factory reset logic. # Commands The `/usr/lib/systemd/systemd-factory-reset` executable may also be invoked from the command line, taking one of the following command arguments: `status` Report current factory reset state. Reports one of `unsupported` (if the OS does not support a factory reset logic), `unspecified` (if no factory reset was requested, but it wasn't turned off explicitly either), `off` (if the factory reset logic was explicitly turned off via the kernel command line option), `on` (if the factory reset is currently enabled and executed), `complete` (if the factory reset logic ran during the current boot but is complete now), `pending` (if a factory reset has been requested for the next boot). Returns with an exit status of 0 if the factory reset mechanism is currently not in effect, 10 if a factory reset is currently being executed, or 11 if it is pending for the next boot. `request` Request a factory reset operation to be executed on next boot. Note that this is a relatively low-level operation. The primary interface for requesting a factory reset operation is by starting the `factory-reset.target` unit. This sets the `FactoryResetRequest` EFI variable, see below. This operation is executed when the `systemd-factory-reset-request.service` unit is started (which is typically one of the services hooked into and ordered before `factory-reset.target`). `cancel` Cancel any previously requested (but not yet executed) factory reset operation. `complete` Mark an ongoing factory reset operation as complete. This operation is executed when the `systemd-factory-reset-complete.service` unit is started (which is typically one of the services hooked into and ordered after `factory-reset-now.target`). # Options The following options are understood: `--retrigger` When used with the `complete` command retriggers all block devices, which might result in auto-discovered devices being usable that previously weren't because the factory reset logic was in place. `--quiet`; `-q` Suppresses the state output of `status`, but still sets the exit status as documented. # EFI Variables The following EFI variable is set and read by `systemd-factory-reset`, under the vendor UUID `8cf2644b-4b0b-428f-9387-6d876050dc67`, for communication between this boot and the next. `FactoryResetRequest` Set whenever a factory reset is requested from the next boot, deleted once the factory reset is complete. Contains JSON data describing the requesting OS, in order to avoid confusion in multi-boot systems. # See Also `systemd(1)`, `systemd-factory-reset-generator(8)`, `systemd.special(7)`, [Factory Reset](https://systemd.io/FACTORY_RESET) # systemd-firstboot systemd systemd-firstboot 1 systemd-firstboot systemd-firstboot.service Initialize basic system settings on or before the first boot-up of a system systemd-firstboot OPTIONS `systemd-firstboot.service` # Description The `systemd-firstboot.service` unit is one of the units which are used to initialize the machine configuration during "First Boot", i.e. when the system is freshly installed or after a factory reset. The `systemd(1)` manager itself will initialize `machine-id(5)` and preset all units, enabling or disabling them according to the `systemd.preset(5)` settings. `systemd-firstboot.service` is started later to interactively initialize basic system configuration. It is started only if `ConditionFirstBoot=yes` is met, which essentially means that `/etc/` is unpopulated, see `systemd.unit(5)` for details. System credentials may be used to inject configuration; those settings are not queried interactively. The `systemd-firstboot` command can also be used to non-interactively initialize an offline system image. The following settings may be configured: - The machine ID of the system - The system locale, more specifically the two locale variables `LANG=` and `LC_MESSAGES` - The system keyboard map - The system time zone - The system hostname - The machine tags - The kernel command line used when installing kernel images - The root user's password and shell Each of the fields may either be queried interactively by users, set non-interactively on the tool's command line, or be copied from a host system that is used to set up the system image. If a setting is already initialized, it will not be overwritten and the user will not be prompted for the setting. Note that this tool operates directly on the file system and does not involve any running system services, unlike `localectl(1)`, `timedatectl(1)` or `hostnamectl(1)`. This allows `systemd-firstboot` to operate on mounted but not booted disk images and in early boot. It is not recommended to use `systemd-firstboot` on the running system after it has been set up. # Options The following options are understood: `--root=root` Takes a directory path as an argument. All paths will be prefixed with the given alternate \ path, including config search paths. This is useful to operate on a system image mounted to the specified directory instead of the host system itself. `--image=path` Takes a path to a disk image file or block device node. If specified all operations are applied to file system in the indicated disk image. This is similar to `--root=` but operates on file systems stored in disk images or block devices. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). For further information on supported disk images, see `systemd-nspawn(1)`'s switch of the same name. `--locale=LOCALE`; `--locale-messages=LOCALE` Sets the system locale, more specifically the `LANG=` and `LC_MESSAGES` settings. The argument should be a valid locale identifier, such as `de_DE.UTF-8`. This controls the `locale.conf(5)` configuration file. `--keymap=KEYMAP` Sets the system keyboard layout. The argument should be a valid keyboard map, such as `de-latin1`. This controls the `KEYMAP` entry in the `vconsole.conf(5)` configuration file. `--timezone=TIMEZONE` Sets the system time zone. The argument should be a valid time zone identifier, such as `Europe/Berlin`. This controls the `localtime(5)` symlink. `--hostname=HOSTNAME` Sets the system hostname. The argument should be a hostname, compatible with DNS. This controls the `hostname(5)` configuration file. `--setup-machine-id` Initialize the system's machine ID to a random ID. This controls the `machine-id(5)` file. This option only works in combination with `--root=` or `--image=`. On a running system, `machine-id` is written by the manager with help from `systemd-machine-id-commit.service(8)`. `--machine-id=ID` Set the system's machine ID to the specified value. The same restrictions apply as to `--setup-machine-id`. `--machine-tags=TAG:TAG…` Set the machine tags to the specified colon-separated list. Machine tags are labels that may be used to classify and group machines for management purposes, for example to identify the role a machine plays in a deployment, the fleet or organizational unit it belongs to, or any other administrator-defined attribute. This controls the `TAGS=` field of `machine-info(5)`. See the description in that page for details of tag syntax. The tags may later be queried and changed with the `tags` command of `hostnamectl(1)`, and matched against with the `ConditionMachineTag=`/`AssertMachineTag=` unit settings, see `systemd.unit(5)`. Unlike most other settings, machine tags are not prompted for interactively. `--root-password=PASSWORD`; `--root-password-file=PATH`; `--root-password-hashed=HASHED_PASSWORD` Sets the password of the system's root user. This creates/modifies the `passwd(5)` and `shadow(5)` files. This setting exists in three forms: `--root-password=` accepts the password to set directly on the command line, `--root-password-file=` reads it from a file and `--root-password-hashed=` accepts an already hashed password on the command line. See `shadow(5)` for more information on the format of the hashed password. Note that it is not recommended to specify plaintext passwords on the command line, as other users might be able to see them simply by invoking `ps(1)`. `--root-shell=SHELL` Sets the shell of the system's root user. This creates/modifies the `passwd(5)` file. `--kernel-command-line=CMDLINE` Sets the system's kernel command line. This controls the `/etc/kernel/cmdline` file which is used by `kernel-install(8)`. `--prompt-locale`; `--prompt-keymap`; `--prompt-timezone`; `--prompt-hostname`; `--prompt-root-password`; `--prompt-root-shell` Prompt the user interactively for a specific basic setting. Note that any explicit configuration settings specified on the command line take precedence, and the user is not prompted for it. `--prompt` Query the user for locale, keymap, timezone, hostname, root's password, and root's shell. This is equivalent to specifying `--prompt-locale`, `--prompt-keymap`, `--prompt-timezone`, `--prompt-hostname`, `--prompt-root-password`, `--prompt-root-shell` in combination. `--prompt-keymap-auto` If invoked from a virtual terminal TTY equivalent to `--prompt-keymap`, otherwise has no effect. Or in other words, only prompts interactively for a keymap if a local keyboard is used for interactivity that requires it. `--copy-locale`; `--copy-keymap`; `--copy-timezone`; `--copy-root-password`; `--copy-root-shell` Copy a specific basic setting from the host. This only works in combination with `--root=` or `--image=`. `--copy` Copy locale, keymap, time zone, root password and shell from the host. This is equivalent to specifying `--copy-locale`, `--copy-keymap`, `--copy-timezone`, `--copy-root-password`, `--copy-root-shell` in combination. `--force` Write configuration even if the relevant files already exist. Without this option, `systemd-firstboot` does not modify or replace existing files. Note that when configuring the root account, even with this option, `systemd-firstboot` only modifies the entry of the `root` user, leaving other entries in `/etc/passwd` and `/etc/shadow` intact. `--reset` If specified, all existing files that are configured by `systemd-firstboot` are removed. Note that the files are removed regardless of whether they'll be configured with a new value or not. This operation ensures that the next boot of the image will be considered a first boot, and `systemd-firstboot` will prompt again to configure each of the removed files. `--delete-root-password` Removes the password of the system's root user, enabling login as root without a password unless the root account is locked. Note that this is extremely insecure and hence this option should not be used lightly. `--welcome=` Takes a boolean argument. By default, when prompting the user for configuration options a brief welcome text is shown before the first question is asked. Pass false to this option to turn off the welcome text. `--chrome=` Takes a boolean argument. By default the initial setup screen will show reverse color "chrome" bars at the top and the bottom of the terminal screen, which may be disabled by setting this option to false. `--mute-console=` Takes a boolean argument. If true kernel log output and service manager status output to the system console is temporarily disabled while `systemd-firstboot` is running, so that its own output is not interrupted. Defaults to false. # Credentials `systemd-firstboot` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `passwd.hashed-password.root`; `passwd.plaintext-password.root` A hashed or plaintext version of the root password to use, in place of prompting the user. These credentials are equivalent to the same ones defined for the `systemd-sysusers.service(8)` service. `passwd.shell.root` Specifies the shell binary to use for the specified account. Equivalent to the credential of the same name defined for the `systemd-sysusers.service(8)` service. `firstboot.locale`; `firstboot.locale-messages` These credentials specify the locale settings to set during first boot, in place of prompting the user. `firstboot.keymap` This credential specifies the keyboard setting to set during first boot, in place of prompting the user. Note the relationship to the `vconsole.keymap` credential understood by `systemd-vconsole-setup.service(8)`: both ultimately affect the same setting, but `firstboot.keymap` is written into `/etc/vconsole.conf` on first boot (if not already configured), and then read from there by `systemd-vconsole-setup`, while `vconsole.keymap` is read on every boot, and is not persisted to disk (but any configuration in `vconsole.conf` will take precedence if present). `firstboot.timezone` This credential specifies the system timezone setting to set during first boot, in place of prompting the user. `firstboot.hostname` This credential specifies the static system hostname to set during first boot. The user will not be prompted for the hostname. Note that this controls the static hostname, not the transient hostname, and only has an effect on first boot, unlike `system.hostname`. `firstboot.machine-tags` This credential specifies the machine tags to set during first boot, as a colon-separated list, equivalent to the `--machine-tags=` switch described above. The tags are written into the `TAGS=` field of `/etc/machine-info` (if that file is not already present), and only have an effect on first boot. If the list contains invalid tags it is ignored in its entirety. Note that by default the `systemd-firstboot.service` unit file is set up to inherit the listed credentials from the service manager. Thus, when invoking a container with an unpopulated `/etc/` for the first time it is possible to configure the root user's password to be `systemd` like this: # systemd-nspawn --image=… --set-credential=firstboot.locale:de_DE.UTF-8 … Note that these credentials are only read and applied during the first boot. Once they are applied they remain applied for subsequent boots, and the credentials are not considered anymore. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Kernel Command Line `systemd.firstboot=` Takes a boolean argument or the special value `headless`, defaults to on. If off, `systemd-firstboot.service` will not interactively query the user for basic settings at first boot, even if those settings are not initialized yet. If set to `headless`, interactive prompts are suppressed just like with `no`, but non-interactive auto-configuration that requires no user input is still performed (for example, selecting the sole installed locale, or applying settings passed in via credentials). # See Also `systemd(1)`, `locale.conf(5)`, `vconsole.conf(5)`, `localtime(5)`, `hostname(5)`, `machine-id(5)`, `shadow(5)`, `systemd-machine-id-setup(1)`, `localectl(1)`, `timedatectl(1)`, `hostnamectl(1)` # systemd-fsck@.service systemd systemd-fsck@.service 8 systemd-fsck@.service systemd-fsck-root.service systemd-fsck-usr.service systemd-fsck File system checker logic `systemd-fsck@.service`, `systemd-fsck-root.service`, `systemd-fsck-usr.service`, `/usr/lib/systemd/systemd-fsck` # Description `systemd-fsck@.service`, `systemd-fsck-root.service`, and `systemd-fsck-usr.service` are services responsible for file system checks. They are instantiated for each device that is configured for file system checking. `systemd-fsck-root.service` and `systemd-fsck-usr.service` are responsible for file system checks on the root and /usr file system, respectively, but only if the root filesystem was not checked in the initrd. `systemd-fsck@.service` is used for all other file systems and for the root file system in the initrd. These services are started at boot if `passno` in `/etc/fstab` for the file system is set to a value greater than zero, but only if it is also configured to be mounted at boot (i.e. without `noauto` option). The file system check for root is performed before the other file systems. Other file systems may be checked in parallel, except when they are on the same rotating disk. `systemd-fsck` does not know any details about specific filesystems, and simply executes file system checkers specific to each filesystem type (`fsck.type`). These checkers will decide if the filesystem should actually be checked based on the time since last check, number of mounts, unclean unmount, etc. `systemd-fsck-root.service` and `systemd-fsck-usr.service` will activate `reboot.target` if `fsck(8)` returns the "System should reboot" condition, or `emergency.target` if `fsck` returns the "Filesystem errors left uncorrected" condition. `systemd-fsck@.service` will fail if `fsck(8)` returns either the "System should reboot" or the "Filesystem errors left uncorrected" condition. For filesystems listed in `/etc/fstab` without `nofail` or `noauto` options, `local-fs.target` will then activate `emergency.target`. # Kernel Command Line `systemd-fsck` understands these kernel command line parameters: `fsck.mode=` One of `auto`, `force`, `skip`. Controls the mode of operation. The default is `auto`, and ensures that file system checks are done when the file system checker deems them necessary. `force` unconditionally results in full file system checks. `skip` skips any file system checks. `fsck.repair=` One of `preen`, `yes`, `no`. Controls the mode of operation. The default is `preen`, and will automatically repair problems that can be safely fixed. `yes` will answer yes to all questions by fsck and `no` will answer no to all questions. # Credentials `systemd-fsck` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `fsck.mode`; `fsck.repair` The contents of the credentials are parsed in the same way as the kernel command line options of the same name. See above for more details. Note that by default the `systemd-fsck@.service`, `systemd-fsck-root.service`, and `systemd-fsck-usr.service` unit files are set up to inherit both `fsck.mode` and `fsck.repair` credentials from the service manager. # See Also `systemd(1)`, `fsck(8)`, `systemd-quotacheck@.service(8)`, `fsck.btrfs(8)`, `fsck.cramfs(8)`, `fsck.ext4(8)`, `fsck.fat(8)`, `fsck.hfsplus(8)`, `fsck.minix(8)`, `fsck.ntfs(8)`, `fsck.xfs(8)` # systemd-fstab-generator systemd systemd-fstab-generator 8 systemd-fstab-generator Unit generator for /etc/fstab `/usr/lib/systemd/system-generators/systemd-fstab-generator` # Description `systemd-fstab-generator` is a generator that translates `/etc/fstab` (see `fstab(5)` for details) into native systemd units early at boot and when configuration of the system manager is reloaded. This will instantiate mount and swap units as necessary. The `passno` field is treated like a simple boolean, and the ordering information is discarded. However, if the root file system is checked, it is checked before all the other file systems. See `systemd.mount(5)` and `systemd.swap(5)` for more information about special `/etc/fstab` mount options this generator understands. One special topic is handling of symbolic links. Historical init implementations supported symlinks in `/etc/fstab`. Because mount units will refuse mounts where the target is a symbolic link, this generator will resolve any symlinks as far as possible when processing `/etc/fstab` in order to enhance backwards compatibility. If a symlink target does not exist at the time that this generator runs, it is assumed that the symlink target is the final target of the mount. `systemd-fstab-generator` implements `systemd.generator(7)`. # Kernel Command Line `systemd-fstab-generator` understands the following kernel command line parameters: `fstab=`; `rd.fstab=` Takes a boolean argument. Defaults to `yes`. If `no`, causes the generator to ignore any mounts or swap devices configured in `/etc/fstab`. `rd.fstab=` is honored only in the initrd, while `fstab=` is honored by both the main system and the initrd. `root=` Configures the operating system's root filesystem to mount when running in the initrd. This accepts a device node path (usually `/dev/disk/by-uuid/…` or `/dev/disk/by-label/…` or similar), or the special values `gpt-auto`, `gpt-auto-force`, `dissect`, `dissect-force`, `fstab`, `tmpfs`, `bind:…`, and `off`. Set to `gpt-auto`, `gpt-auto-force`, `dissect`, `dissect-force` to explicitly request automatic root file system discovery, implemented in `systemd-gpt-auto-generator(8)`. Use `fstab` to explicitly request automatic root file system discovery via the initrd `/etc/fstab` rather than via kernel command line. Use `tmpfs` in order to mount a `tmpfs(5)` file system as root file system of the OS. This is useful in combination with `mount.usr=` (see below) in order to combine a volatile root file system with a separate, immutable `/usr/` file system. Also see `systemd.volatile=` below. Use `bind:…` to bind mount another directory as operating system root filesystems (added in v258). Expects an absolute path name referencing an existing directory within the initrd's file hierarchy to boot into. Since the resulting root file system is supposed to behave like a regular OS root, the bind mount is established with the `dev`, `suid` and `exec` options (i.e. the `nodev`, `nosuid` and `noexec` flags that would otherwise be inherited from the file system the source directory resides on, such as `/run/`, are cleared), unless overridden via `rootflags=`. Set to `off` to turn off mounting of a root file system. Note that further `root=` values may be supported, implemented in additional packages. `rootfstype=` Takes the root filesystem type that will be passed to the mount command. `rootfstype=` is honored by the initrd. `rootflags=` Takes the root filesystem mount options to use. `rootflags=` is honored by the initrd. Note that unlike most kernel command line options this setting does not override settings made in configuration files (specifically: the mount option string in `/etc/fstab`). See `systemd-remount-fs.service(8)`. `mount.usr=` Takes the `/usr/` filesystem to be mounted by the initrd. If `mount.usrfstype=` or `mount.usrflags=` is set, then the mount configured via `mount.usr=` will default to the same value set in `root=`. Set to `dissect` to explicitly request automatic `/usr/` file system discovery, implemented in `systemd-gpt-auto-generator(8)`. Set to `off` to turn off mounting of a separate `/usr/` file system. `mount.usr=` is honored by the initrd. `mount.usrfstype=` Takes the `/usr/` filesystem type that will be passed to the mount command. If `mount.usr=` or `mount.usrflags=` is set, then `mount.usrfstype=` will default to the value set in `rootfstype=`. Otherwise, this value will be read from the `/usr/` entry in `/etc/fstab` on the root filesystem. `mount.usrfstype=` is honored by the initrd. `mount.usrflags=` Takes the `/usr/` filesystem mount options to use. If `mount.usr=` or `mount.usrfstype=` is set, then `mount.usrflags=` will default to the value set in `rootflags=`. Otherwise, this value will be read from the `/usr/` entry in `/etc/fstab` on the root filesystem. `mount.usrflags=` is honored by the initrd. `roothash=`; `usrhash=` These options are primarily read by `systemd-veritysetup-generator(8)`. When set this indicates that the root file system (or `/usr/`) shall be mounted from Verity volumes with the specified hashes. If these kernel command line options are set the root (or `/usr/`) file system is thus mounted from a device mapper volume `/dev/mapper/root` (or `/dev/mapper/usr`). `systemd.volatile=` Controls whether the system shall boot up in volatile mode. Takes a boolean argument or the special values `state` and `overlay`. If `no` (the default), this generator makes no changes to the mount tree and the system is booted up in normal mode. If `yes` the generator ensures `systemd-volatile-root.service(8)` is run in the initrd. This service changes the mount table before transitioning to the host system, so that a volatile memory file system (`tmpfs`) is used as root directory, with only `/usr/` mounted into it from the configured root file system, in read-only mode. This way the system operates in fully stateless mode, with all configuration and state reset at boot and lost at shutdown, as `/etc/` and `/var/` will be served from the (initially unpopulated) volatile memory file system. If set to `state` the generator will leave the root directory mount point unaltered, however will mount a `tmpfs` file system to `/var/`. In this mode the normal system configuration (i.e. the contents of `/etc/`) is in effect (and may be modified during system runtime), however the system state (i.e. the contents of `/var/`) is reset at boot and lost at shutdown. If this setting is set to `overlay` the root file system is set up as `overlayfs` mount combining the read-only root directory with a writable `tmpfs`, so that no modifications are made to disk, but the file system may be modified nonetheless with all changes being lost at reboot. Note that in none of these modes the root directory, `/etc/`, `/var/` or any other resources stored in the root file system are physically removed. It's thus safe to boot a system that is normally operated in non-volatile mode temporarily into volatile mode, without losing data. Note that with the exception of `overlay` mode, enabling this setting will only work correctly on operating systems that can boot up with only `/usr/` mounted, and are able to automatically populate `/etc/`, and also `/var/` in case of `systemd.volatile=yes`. Also see `root=tmpfs` above, for a method to combine a `tmpfs` file system with a regular `/usr/` file system (as configured via `mount.usr=`). The main distinction between `systemd.volatile=yes`, and `root=tmpfs` in combination `mount.usr=` is that the former operates on top of a regular root file system and temporarily obstructs the files and directories above its `/usr/` subdirectory, while the latter does not hide any files, but simply mounts a unpopulated tmpfs as root file system and combines it with a user picked `/usr/` file system. `systemd.swap=` Takes a boolean argument or enables the option if specified without an argument. If disabled, causes the generator to ignore any swap devices configured in `/etc/fstab`. Defaults to enabled. `systemd.mount-extra=WHAT:WHERE[:FSTYPE[:OPTIONS]]`; `rd.systemd.mount-extra=WHAT:WHERE[:FSTYPE[:OPTIONS]]` Specifies the mount unit. Takes at least two and at most four fields separated with a colon (`:`). Each field is handled as the corresponding fstab field. This option can be specified multiple times. `rd.systemd.mount-extra=` is honored only in the initrd, while `systemd.mount-extra=` is honored by both the main system and the initrd. In the initrd, the mount point (and also source path if the mount is bind mount) specified in `systemd.mount-extra=` is prefixed with `/sysroot/`. Example: systemd.mount-extra=/dev/sda1:/mount-point:ext4:rw,noatime `systemd.swap-extra=WHAT[:OPTIONS]`; `rd.systemd.swap-extra=WHAT[:OPTIONS]` Specifies the swap unit. Takes the block device to be used as a swap device, and optionally takes mount options followed by a colon (`:`). This option can be specified multiple times. `rd.systemd.swap-extra=` is honored only in the initrd, while `systemd.swap-extra=` is honored by both the main system and the initrd. Example: systemd.swap-extra=/dev/sda2:x-systemd.makefs # System Credentials `fstab.extra` This credential may contain addition mounts to establish, in the same format as `fstab(5)`, with one mount per line. It is read in addition to `/etc/fstab`. # See Also `systemd(1)`, `fstab(5)`, `systemd.mount(5)`, `systemd.swap(5)`, `systemd-cryptsetup-generator(8)`, `systemd-gpt-auto-generator(8)`, `kernel-command-line(7)`, [Known Environment Variables](https://systemd.io/ENVIRONMENT/) # systemd-getty-generator systemd systemd-getty-generator 8 systemd-getty-generator Generator for enabling getty instances on the console `/usr/lib/systemd/system-generators/systemd-getty-generator` # Description `systemd-getty-generator` is a generator that automatically instantiates `serial-getty@.service` on the kernel consoles, if they can function as ttys and are not provided by the virtual console subsystem. It will also instantiate `serial-getty@.service` instances for virtualizer consoles, if execution in a virtualized environment is detected. If execution in a container environment is detected, it will instead enable `console-getty.service` for `/dev/console`, and `container-getty@.service` instances for additional container pseudo TTYs as requested by the container manager (see [`Container Interface`](https://systemd.io/CONTAINER_INTERFACE)). This should ensure that the user is shown a login prompt at the right place, regardless of which environment the system is started in. For example, it is sufficient to redirect the kernel console with a kernel command line argument such as `console=` to get both kernel messages and a getty prompt on a serial TTY. See [The kernel's command-line parameters](https://docs.kernel.org/admin-guide/kernel-parameters.html) for more information on the `console=` kernel parameter. `systemd-getty-generator` implements `systemd.generator(7)`. Further information about configuration of gettys can be found in [systemd for Administrators, Part XVI: Gettys on Serial Consoles (and Elsewhere)](https://0pointer.de/blog/projects/serial-console.html). # Kernel Command Line `systemd-getty-generator` understands the following `kernel-command-line(7)` parameters: `systemd.getty_auto=` This kernel command line option may be used to control the execution mode of the generator. Takes an optional boolean argument. Since v258, this also takes comma-separated list of special values: `credential`, `container`, `console`, and `builtin`. When `credential` is specified, the two credentials `getty.ttys.serial` and `getty.ttys.container` will be parsed. See System Credentials section below for more details. When `container` is specified, `console-getty.service` and `container-getty@.service` will be enabled when the system is running in a container. This option will be ignored when the system is not in a container. When `console` is specified, `serial-getty@.service` for active kernel consoles will be enabled. This option will be ignored when the system is running in a container. When `builtin` is specified, `serial-getty@.service` for available virtualizer consoles will be enabled. This option will be ignored when the system is running in a container. When yes, the above four options will be enabled. When no, all options are disabled and no service will be enabled. When the kernel command line option is specified without an argument, defaults to yes. The generator is enabled by default, and a false value may be used to disable it. # Environment `$SYSTEMD_GETTY_AUTO` This environment variable may be used to control the execution mode of the generator. Takes the same value as `systemd.getty_auto=` kernel command line option. # System Credentials `getty.auto` The system credential may be used to control the execution mode of the generator. Takes the same value as `systemd.getty_auto=` kernel command line option. `getty.ttys.serial`; `getty.ttys.container` These system credentials may be used to spawn additional login prompts on selected TTYs. The two credentials should contain a newline-separated list of TTY names to spawn instances of `serial-getty@.service` (in case of `getty.ttys.serial`) and `container-getty@.service` (in case of `getty.ttys.container`) on. Any lines starting with a `#` will be ignored. # See Also `systemd(1)`, `kernel-command-line(7)`, `systemd.system-credentials(7)`, `agetty(8)` # systemd-gpt-auto-generator systemd systemd-gpt-auto-generator 8 systemd-gpt-auto-generator Generator for automatically discovering and mounting root, /home/ , /srv/ , /var/ and /var/tmp/ partitions, as well as discovering and enabling swap partitions, based on GPT partition type GUIDs `/usr/lib/systemd/system-generators/systemd-gpt-auto-generator` # Description `systemd-gpt-auto-generator` is a unit generator that automatically discovers the root partition, `/home/`, `/srv/`, `/var/`, `/var/tmp/`, the EFI System Partition (ESP), the Extended Boot Loader Partition (XBOOTLDR), and swap partitions and creates mount and swap units for them, based on the partition type GUIDs of GUID partition tables (GPT). See [UEFI Specification](https://uefi.org/specifications), chapter 5 for more details. It implements the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). Note that this generator has no effect on non-GPT systems. It will also not create mount point configuration for directories which already contain files or if the mount point is explicitly configured in `fstab(5)`. Additionally no unit will be created for the ESP or the XBOOTLDR partition if mount entries are found in the `/boot/` or `/efi/` hierarchies in `fstab(5)`. If the units this generator creates are overridden, for example by units in directories with higher precedence, drop-ins and additional dependencies created by this generator might still be used. When run in the initial RAM disk (initrd) this generator can automatically search for the root file system. Specifically: - It will look for the root partition on the same physical disk where the EFI System Partition (ESP) is located. Note that support from the boot loader is required for this to work: the EFI variable `LoaderDevicePartUUID` of the `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` vendor UUID is used to determine from which partition (and hence disk) the system was booted. If the boot loader does not set this variable, this generator will not be able to detect the root partition. See the [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE) for details. - Alternatively, it will look for the root file system on a loopback block device whose `.lo_name` field is set to one of the literal strings `rootdisk` or `rootdisk.raw`. This field can be set via `losetup`'s `--loop-ref=` string. For images downloaded via `systemd-import-generator(8)` make sure to set the `blockdev` option and set the local name string to `rootdisk` to achieve this effect. Note that discovery of the root file system on loopback block devices like this is only done if `root=gpt-auto` or `root=dissect` is specified explicitly on the kernel command line, unlike the discovery based on the boot loader reported ESP which is also enabled if no `root=` parameter is specified at all. (The latter relies on `systemd-udevd.service`'s `/dev/gpt-auto-root` block device symlink generation). - It will also generate a unit file mounting the EFI System Partition (ESP) to `/sysefi/`, if applicable. Unlike the file systems mentioned above this mount is not activated by default however, but can be pulled in by services requiring ESP access from within the initrd. Note that this mount point is initrd-specific and does not make use of autofs. The ESP is typically mounted at a different place and via autofs once the system transitions out of the initrd. When run on the host system (i.e. after successfully transitioning out of the initrd into the root filesystem) this generator will look for all other partitions on the same physical disk as the root partition. For this discovery, boot loader support is not required. Moreover, it is not required that the root partition was automatically discovered by the initrd (as described above) for the discovery of the non-root file partitions to take place. Or in other words: automatic discovery of the root file system and of the non-root file systems are independent operations, that do not rely on each other, and are done during two distinct phases of the boot process (one in the initrd, the other after). These partitions will not be searched for on systems where the root file system is distributed on multiple disks, for example via btrfs RAID. The root partition can be configured explicitly by symlinking `/run/systemd/volatile-root` to `/dev/block/$major:$minor`. This is especially useful if the root mount has been replaced by some form of volatile file system (overlayfs). `systemd-gpt-auto-generator` is useful for centralizing file system configuration in the partition table and making configuration in `/etc/fstab` or on the kernel command line unnecessary. This generator looks for the partitions based on their partition type GUID. The following partition type GUIDs are identified: | Partition Type | GUID | Name | Mount Point | Explanation | |----|----|----|----|----| | `SD_GPT_ROOT_X86_64` | `4f68bce3-e8cd-4db1-96e7-fbcaf984b709` | `Root Partition (x86-64)` | `/` | The first partition with this type UUID, located on the same disk as the ESP used for booting, is used as the root file system `/` on AMD64 / 64-bit x86 systems. | | `SD_GPT_ROOT_ARM64` | `b921b045-1df0-41c3-af44-4c6f280d3fae` | `Root Partition (64-bit ARM)` | `/` | The first partition with this type UUID, located on the same disk as the ESP used for booting, is used as the root file system `/` on AArch64 / 64-bit ARM systems. | | `SD_GPT_ROOT_ALPHA` `SD_GPT_ROOT_ARC` `SD_GPT_ROOT_ARM` `SD_GPT_ROOT_ARM64` `SD_GPT_ROOT_IA64` `SD_GPT_ROOT_LOONGARCH64` `SD_GPT_ROOT_MIPS` `SD_GPT_ROOT_MIPS64` `SD_GPT_ROOT_MIPS_LE` `SD_GPT_ROOT_MIPS64_LE` `SD_GPT_ROOT_PARISC` `SD_GPT_ROOT_PPC` `SD_GPT_ROOT_PPC64` `SD_GPT_ROOT_PPC64_LE` `SD_GPT_ROOT_RISCV32` `SD_GPT_ROOT_RISCV64` `SD_GPT_ROOT_S390` `SD_GPT_ROOT_S390X` `SD_GPT_ROOT_TILEGX` `SD_GPT_ROOT_X86` `SD_GPT_ROOT_X86_64` `SD_GPT_USR_ALPHA` `SD_GPT_USR_ARC` `SD_GPT_USR_ARM` `SD_GPT_USR_IA64` `SD_GPT_USR_LOONGARCH64` `SD_GPT_USR_MIPS_LE` `SD_GPT_USR_MIPS64_LE` `SD_GPT_USR_PARISC` `SD_GPT_USR_PPC` `SD_GPT_USR_PPC64` `SD_GPT_USR_PPC64_LE` `SD_GPT_USR_RISCV32` `SD_GPT_USR_RISCV64` `SD_GPT_USR_S390` `SD_GPT_USR_S390X` `SD_GPT_USR_TILEGX` `SD_GPT_USR_X86` | … | Root partitions for other architectures | `/` | The first partition with the type UUID matching the architecture, located on the same disk as the ESP used for booting, is used as the root file system `/`. For the full list and constant values, see [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). | | `SD_GPT_HOME` | `933ac7e1-2eb4-4f13-b844-0e14e2aef915` | Home Partition | `/home/` | The first partition with this type UUID on the same disk as the root partition is mounted to `/home/`. | | `SD_GPT_SRV` | `3b8f8425-20e0-4f3b-907f-1a25a76f98e8` | Server Data Partition | `/srv/` | The first partition with this type UUID on the same disk as the root partition is mounted to `/srv/`. | | `SD_GPT_VAR` | `4d21b016-b534-45c2-a9fb-5c16e091fd2d` | Variable Data Partition | `/var/` | The first partition with this type UUID on the same disk as the root partition is mounted to `/var/` — under the condition its partition UUID matches the first 128 bit of the HMAC-SHA256 of the GPT type uuid of this partition keyed by the machine ID of the installation stored in `machine-id(5)`. This can be generated using `systemd-id128(1)`. | | `SD_GPT_TMP` | `7ec6f557-3bc5-4aca-b293-16ef5df639d1` | Temporary Data Partition | `/var/tmp/` | The first partition with this type UUID on the same disk as the root partition is mounted to `/var/tmp/`. | | `SD_GPT_SWAP` | `0657fd6d-a4ab-43c4-84e5-0933c84b4f4f` | Swap | n/a | All partitions with this type UUID on the same disk as the root partition are used as swap. | | `SD_GPT_ESP` | `c12a7328-f81f-11d2-ba4b-00a0c93ec93b` | EFI System Partition (ESP) | `/efi/` or `/boot/` once the system transitioned out of the initrd, `/sysefi/` before | The first partition with this type UUID located on the same disk as the root partition is mounted to `/boot/` or `/efi/`, see below. | | `SD_GPT_XBOOTLDR` | `bc13c2ff-59e6-4262-a352-b275fd6f7172` | Extended Boot Loader Partition | `/boot/` | The first partition with this type UUID located on the same disk as the root partition is mounted to `/boot/`, see below. | Partition Type GUIDs This generator understands the following attribute flags for partitions: | Flag | Value | Applicable to | Explanation | |----|----|----|----| | `SD_GPT_FLAG_READ_ONLY` | `0x1000000000000000` | `/`, `/home/`, `/srv/`, `/var/`, `/var/tmp/`, Extended Boot Loader Partition | Partition is mounted read-only | | `SD_GPT_FLAG_NO_AUTO` | `0x8000000000000000` | `/`, `/home/`, `/srv/`, `/var/`, `/var/tmp/`, Extended Boot Loader Partition | Partition is not mounted automatically | | `SD_GPT_FLAG_NO_BLOCK_IO_PROTOCOL` | `0x0000000000000002` | EFI System Partition (ESP) | Partition is not mounted automatically | Partition Attribute Flags The `/home/`, `/srv/`, `/var/`, `/var/tmp/` and swap partitions may be encrypted in LUKS format. In this case, a device mapper device is set up under the names `/dev/mapper/home`, `/dev/mapper/srv`, `/dev/mapper/var`, `/dev/mapper/tmp` or `/dev/mapper/swap`. Note that this might create conflicts if the same partition is listed in `/etc/crypttab` with a different device mapper device name. When systemd is running in the initrd the `/` partition may be encrypted with LUKS as well. In this case, a device mapper device is set up under the name `/dev/mapper/root`, and a `sysroot.mount` is set up that mounts the device under `/sysroot`. For more information, see `bootup(7)`. Mount and automount units for the EFI System Partition (ESP) and Extended Boot Loader Partition (XBOOTLDR) are generated on EFI systems. If the disk contains an XBOOTLDR partition, as defined in the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification), it is made available at `/boot/`. This generator creates an automount unit; the mount will only be activated on-demand when accessed. The mount point will be created if necessary. The ESP is mounted to `/boot/` if that directory is not used for XBOOTLDR, and otherwise to `/efi/`. Same as for `/boot/`, an automount unit is used. The mount point will be created if necessary. These apply once the system transitioned out of the initrd phase. Before that, if components in the initrd require ESP access, it will be mounted to `/sysefi/`. No configuration is created for mount points that are configured in `fstab(5)` or when the target directory contains files. When using this generator in conjunction with btrfs file systems, make sure to set the correct default subvolumes on them, using `btrfs subvolume set-default`. If the system was booted via `systemd-stub(7)` and the stub reported to userspace that the kernel image was measured to a TPM2 PCR, then any discovered root and `/var/` volume identifiers (and volume encryption keys, in case they are encrypted) will be automatically measured into PCR 15 on activation, via `systemd-pcrfs@.service(8)`. Moreover, information about the LUKS key slot used to unlock the volume is measured into NvPCR `cryptsetup`. Finally, if the root or `/usr/` partition is protected via Verity its root hash and the serial/issuer of the key used for the provided root hash signature (if any) are measured into the NvPCR `verity`. Mount constraint metadata contained in the file systems is validated by pulling in `systemd-validatefs@.service(8)` for generated mounts. `systemd-gpt-auto-generator` implements `systemd.generator(7)`. # Kernel Command Line `systemd-gpt-auto-generator` understands the following kernel command line parameters: `systemd.gpt_auto`; `rd.systemd.gpt_auto` Those options take an optional boolean argument, and default to yes. The generator is enabled by default, and a false value may be used to disable it (e.g. `systemd.gpt_auto=0`). `systemd.image_policy=` Takes an image dissection policy string as argument (as per `systemd.image-policy(7)`), and allows enforcing a policy on dissection and use of the automatically discovered GPT partition table entries. Note that the specified image policy is not taken into account for automatic root or `/usr/` file system discovery unless `root=dissect`/`mount.usr=dissect` (or `root=dissect-force`) are specified. (The policy will always be applied to the other auto-discoverable partition types.) `systemd.image_filter=` Takes an image dissection filter string as argument (as per `systemd.image-filter(7)`), and allows enforcing a set of globbing patterns on the partition matching of the automatically discovered GPT partition table entries. Note that the specified image filter is not taken into account for automatic root or `/usr/` file system discovery unless `root=dissect`/`mount.usr=dissect` (or `root=dissect-force`) are specified. (The filter will always be applied to the other auto-discoverable partition types.) `root=`; `rootfstype=`; `rootflags=` When `root=` is used with the special value `gpt-auto`, basic automatic discovery of the root partition based on the GPT partition type is enabled. Use of the root partition is delayed until factory reset mode is left, in case it is enabled during the current boot. See [Factory Reset](https://systemd.io/FACTORY_RESET) for more information on that. If `gpt-auto-force` is specified automatic discovery of the root partition is enabled, ignoring any factory reset mode. If `root=` is set to the special value `dissect` full automatic discovery of the root partition based on GPT partition information is enabled. This is a superset of `root=gpt-auto`, as it automatically configures Verity partitions (including signature-based setup) following the logic defined for that in the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification/). Moreover it takes the configured image policy and image filter into account for all partition types, including the root file system. `root=dissect` will wait for the factory reset phase to be completed if it is in effect before activating the root file system. Use `root=dissect-force` to ignore the factory reset phase and activate the root file system immediately. Any other value (i.e. besides `gpt-auto`, `gpt-auto-force`, `dissect`, `dissect-force`) disables automatic root file system discovery. If `root=` is not specified at all on the kernel command line automatic discovery of the root partition via the ESP reported by the boot loader is also enabled (taking factory reset state into account, i.e. equivalent to `root=gpt-auto`), however in this case discovery based on the loopback block device `.lo_name` field is not enabled. The `rootfstype=` and `rootflags=` options are used to select the file system type and options when the root file system is automatically discovered. `mount.usr=`; `mount.usrfstype=`; `mount.usrflags=` Similar to `root=`, `rootfstype=`, `rootflags=` (see above), but applies to the `/usr/` partition instead. Note that the `gpt-auto`, `gpt-auto-force`, `dissect-force` settings that `root=` understands are not supported by `mount.usr=` (however `dissect` is). Also note that automatic partition discovery for `/usr/` must be enabled explicitly, unlike the discovery for the root file system, which is enabled if no `root=` parameter is passed at all. `rw`; `ro` Mount the root partition read-write or read-only *initially*. Note that unlike most kernel command line options these settings do not override configuration in the file system, and the file system may be remounted later. See `systemd-remount-fs.service(8)`. `systemd.swap=` Takes a boolean argument or enables the option if specified without an argument. If disabled, automatic discovery of swap partition(s) based on GPT partition type is disabled. Defaults to enabled. # See Also `systemd(1)`, `systemd.mount(5)`, `systemd.swap(5)`, `systemd-fstab-generator(8)`, `systemd-cryptsetup@.service(8)`, `systemd-pcrfs@.service(8)`, `systemd-validatefs@.service(8)`, `machine-id(5)`, `cryptsetup(8)`, `fstab(5)`, `btrfs(8)` # systemd-hibernate-resume-generator systemd systemd-hibernate-resume-generator 8 systemd-hibernate-resume-generator Unit generator for resume= kernel parameter `/usr/lib/systemd/system-generators/systemd-hibernate-resume-generator` # Description `systemd-hibernate-resume-generator` is a generator that initiates the procedure to resume the system from hibernation. When `resume=` kernel command line option or `HibernateLocation` EFI variable is detected, it enables the `systemd-hibernate-resume.service(8)` unit, which will instruct the kernel to resume the system from the hibernation image. # Kernel Command Line `systemd-hibernate-resume-generator` understands the following kernel command line parameters: `resume=` Takes a path to the resume device. Both persistent block device paths like `/dev/disk/by-foo/bar` and `fstab(5)`-style specifiers like `FOO=bar` are supported. `resume_offset=` Takes the page offset of the swap space from the resume device. Defaults to `0`. `resumeflags=` Takes the resume device mount options to use. Defaults `rootflags=` if not specified. `noresume` Do not try to resume from hibernation. If this parameter is present, `resume=` is ignored. # See Also `systemd(1)`, `systemd-hibernate-resume.service(8)`, `kernel-command-line(7)` # systemd-hibernate-resume.service systemd systemd-hibernate-resume.service 8 systemd-hibernate-resume.service systemd-hibernate-clear.service systemd-hibernate-resume Resume from hibernation `systemd-hibernate-resume.service` `systemd-hibernate-clear.service` `/usr/lib/systemd/systemd-hibernate-resume` # Description `systemd-hibernate-resume.service` initiates the resume from hibernation. `systemd-hibernate-resume` only supports the in-kernel hibernation implementation, see [Swap suspend](https://docs.kernel.org/power/swsusp.html). Internally, it works by writing the major:minor of selected device node to `/sys/power/resume`, along with the offset in memory pages (`/sys/power/resume_offset`) if supported. The resume device node is either passed directly through arguments, or automatically acquired from kernel command line options and/or `HibernateLocation` EFI variable. The latter will normally be cleared by `systemd-hibernate-resume.service` on resumption. If a stale variable is detected, it would be cleared by `systemd-hibernate-clear.service`. Failing to initiate a resume is not an error condition. It may mean that there was no resume image (e. g. if the system has been simply powered off and not hibernated). In such cases, the boot is ordinarily continued. # See Also `systemd(1)`, `systemd-hibernate-resume-generator(8)` # systemd-homed.service systemd systemd-homed.service 8 systemd-homed.service systemd-homed Home Area/User Account Manager `systemd-homed.service` `/usr/lib/systemd/systemd-homed` # Description `systemd-homed` is a system service that may be used to create, remove, change or inspect home areas (directories and network mounts and real or loopback block devices with a filesystem, optionally encrypted). Most of `systemd-homed`'s functionality is accessible through the `homectl(1)` command. See the [Home Directories](https://systemd.io/HOME_DIRECTORY) documentation for details about the format and design of home areas managed by `systemd-homed.service`. Each home directory managed by `systemd-homed.service` synthesizes a local user and group. These are made available to the system using the [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API), and thus may be browsed with `userdbctl(1)`. `systemd-homed.service` also manages blob directories for each home directory it manages. See [User Record Blob Directories](https://systemd.io/USER_RECORD_BLOB_DIRS) for more details. # Key Management User records are cryptographically signed with a public/private key pair (the signature is part of the JSON record itself). For a user to be permitted to log in locally the public key matching the signature of their user record must be installed. For a user record to be modified locally the private key matching the signature must be installed locally, too. The keys are stored in the `/var/lib/systemd/home/` directory: `/var/lib/systemd/home/local.private` The private key of the public/private key pair used for local records. Currently, only a single such key may be installed. `/var/lib/systemd/home/local.public` The public key of the public/private key pair used for local records. Currently, only a single such key may be installed. `/var/lib/systemd/home/*.public` Additional public keys. Any users whose user records are signed with any of these keys are permitted to log in locally. An arbitrary number of keys may be installed this way. All key files listed above are in PEM format. In order to migrate a home directory from a host `foobar` to another host `quux` it is hence sufficient to copy `/var/lib/systemd/home/local.public` from the host `foobar` to `quux`, maybe calling the file on the destination `/var/lib/systemd/home/foobar.public`, reflecting the origin of the key. If the user record should be modifiable on `quux` the pair `/var/lib/systemd/home/local.public` and `/var/lib/systemd/home/local.private` need to be copied from `foobar` to `quux`, and placed under the identical paths there, as currently only a single private key is supported per host. Note of course that the latter means that user records generated/signed before the key pair is copied in, lose their validity. # Signals `SIGUSR1` Upon reception of the `SIGUSR1` process signal `systemd-homed` will reestablish its file watches on `/home/` and rescan the directory for home directories. # See Also `systemd(1)`, `homed.conf(5)`, `homectl(1)`, `pam_systemd_home(8)`, `userdbctl(1)`, `org.freedesktop.home1(5)` # systemd-hostnamed.service systemd systemd-hostnamed.service 8 systemd-hostnamed.service systemd-hostnamed Daemon to control system hostname from programs `systemd-hostnamed.service` `/usr/lib/systemd/systemd-hostnamed` # Description `systemd-hostnamed.service` is a system service that may be used to change the system's hostname and related machine metadata from user programs. It is automatically activated on request and terminates itself when unused. It currently offers access to five variables: - The current hostname (Example: `dhcp-192-168-47-11`) - The static (configured) hostname (Example: `lennarts-computer`) - The pretty hostname (Example: `Lennart's Computer`) - A suitable icon name for the local host (Example: `computer-laptop`) - A chassis type (Example: `tablet`) The static hostname is stored in `/etc/hostname`, see `hostname(5)` for more information. The pretty hostname, chassis type, and icon name are stored in `/etc/machine-info`, see `machine-info(5)`. The tool `hostnamectl(1)` is a command line client to this service. See `org.freedesktop.hostname1(5)` and `org.freedesktop.LogControl1(5)` for a description of the D-Bus API. # See Also `systemd(1)`, `hostname(5)`, `machine-info(5)`, `hostnamectl(1)`, `sethostname(2)`, `org.freedesktop.hostname1(5)` # systemd-hwdb systemd systemd-hwdb 8 systemd-hwdb hardware database management tool systemd-hwdb options update systemd-hwdb options query modalias # Description `systemd-hwdb` expects a command and command specific arguments. It manages the binary hardware database. # Options `--usr` Generate in /usr/lib/udev instead of /etc/udev. `-r`; `--root=PATH` Alternate root path in the filesystem. `-s`; `--strict` When updating, return non-zero exit value on any parsing error. ## systemd-hwdb \[\\] update Update the binary database. ## systemd-hwdb \[\\] query \ Query database and print result. # See Also `systemd(1)` `hwdb(7)` # systemd-id128 systemd systemd-id128 1 systemd-id128 Generate and print sd-128 identifiers systemd-id128 OPTIONS new systemd-id128 OPTIONS machine-id systemd-id128 OPTIONS boot-id systemd-id128 OPTIONS invocation-id systemd-id128 OPTIONS var-partition-uuid systemd-id128 OPTIONS show NAME\|UUID # Description `id128` may be used to conveniently print `sd-id128(3)` UUIDs. What identifier is printed depends on the specific verb. With `new`, a new random identifier will be generated. With `machine-id`, the identifier of the current machine will be printed. See `machine-id(5)`. With `boot-id`, the identifier of the current boot will be printed. With `invocation-id`, the identifier of the current service invocation will be printed. This is available in systemd services. See `systemd.exec(5)`. With `show`, well-known IDs are printed (for now, only GPT partition type UUIDs), along with brief identifier strings. When no arguments are specified, all known IDs are shown. When arguments are specified, they may be the identifiers or ID values of one or more known IDs, which are then printed with their name, or arbitrary IDs, which are then printed with a placeholder name. Combine with `--uuid` to list the IDs in UUID style, i.e. the way GPT partition type UUIDs are usually shown. `machine-id`, `boot-id`, and `show` may be combined with the `--app-specific=app-id` switch to generate application-specific IDs. See `sd_id128_get_machine(3)` for the discussion when this is useful. Support for `show --app-specific=` was added in version 255. `var-partition-uuid` prints a UUID which, following the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification), should be used as the GPT partition UUID for `/var/`, being derived from the GPT partition type, keyed by the local `/etc/machine-id`. Added in version 257. # Options The following options are understood: `-p`; `--pretty` Generate output as programming language snippets. `-P`; `--value` Only print the value. May be combined with `-u`/`--uuid`. `-a app-id`; `--app-specific=app-id` With this option, identifiers will be printed that are the result of hashing the application identifier \ and another ID. The \ argument must be a valid sd-id128 string identifying the application. When used with `machine-id`, the other ID will be the machine ID as described in `machine-id(5)`, when used with `boot-id`, the other ID will be the boot ID, and when used with `show`, the other ID or IDs should be specified via the positional arguments. `-u`; `--uuid` Generate output as a UUID formatted in the "canonical representation", with five groups of digits separated by hyphens. See the Wikipedia entry for [Universally Unique Identifiers](https://en.wikipedia.org/wiki/Universally_unique_identifier#Format) for more discussion. # Exit status On success 0 is returned, and a non-zero failure code otherwise. # Examples
Show a well-known UUID
$ systemd-id128 show --value user-home 773f91ef66d449b5bd83d683bf40ad16 $ systemd-id128 show --value --uuid user-home 773f91ef-66d4-49b5-bd83-d683bf40ad16 $ systemd-id128 show 773f91ef-66d4-49b5-bd83-d683bf40ad16 NAME ID user-home 773f91ef66d449b5bd83d683bf40ad16
Generate an application-specific UUID
$ systemd-id128 machine-id -u 3a9d668b-4db7-4939-8a4a-5e78a03bffb7 $ systemd-id128 new -u 1fb8f24b-02df-458d-9659-cc8ace68e28a $ systemd-id128 machine-id -u -a 1fb8f24b-02df-458d-9659-cc8ace68e28a 47b82cb1-5339-43da-b2a6-1c350aef1bd1 $ systemd-id128 -Pu show 3a9d668b-4db7-4939-8a4a-5e78a03bffb7 \ -a 1fb8f24b-02df-458d-9659-cc8ace68e28a 47b82cb1-5339-43da-b2a6-1c350aef1bd1 On a given machine with the ID 3a9d668b-4db7-4939-8a4a-5e78a03bffb7, for the application 1fb8f24b-02df-458d-9659-cc8ace68e28a, we generate an application-specific machine ID (47b82cb1-5339-43da-b2a6-1c350aef1bd1). If we want to later recreate the same calculation on a different machine, we need to specify both IDs explicitly as parameters to `show`.
# See Also `systemd(1)`, `sd-id128(3)`, `sd_id128_get_machine(3)` # systemd-imds-generator systemd systemd-imds-generator 8 systemd-imds-generator Generator to automatically enable IMDS on supporting environments `/usr/lib/systemd/system-generators/systemd-imds-generator` # Description `systemd-imds-generator` is a generator that enables IMDS (Instance Metadata Service) functionality at boot on systems that support it. Specifically it does three things: - It pulls the `systemd-imdsd.socket` unit (which activates `systemd-imdsd@.service(8)`) into the initial transaction, which provides IMDS access to local applications via Varlink IPC. - It pulls the `systemd-imds-early-network.service` unit into the initial transaction, which generates a suitable `systemd.network(5)` network configuration file that allows early-boot network access to the IMDS functionality. - It pulls the `systemd-imds-import.service` unit into the initial transaction, which automatically imports various credentials from IMDS into the local system, storing them in `/run/credstore/`. By default, whether to pull in these services or not is decided based on `hwdb(7)` information, that detects various IMDS environments automatically. However, this logic may be overridden via `systemd.imds=`, see below. `systemd-imds-generator` implements `systemd.generator(7)`. # Kernel Command Line `systemd-imds-generator` understands the following kernel command line parameters: `systemd.imds=` Takes a boolean argument or the special value `auto`, and may be used to enable or disable the IMDS logic. Note that this controls only whether the relevant services (as listed above) are automatically pulled into the initial transaction, it has no effect if some other unit or the user explicitly activates the relevant units. If this option is not used (or set to `auto`) automatic detection of IMDS is used, see above. `systemd.imds.import=` Takes a boolean argument. If false the `systemd-imds-import.service` (see above) is not pulled into the initial transaction, i.e. no credentials are imported from IMDS. Defaults to true in the initrd, and false otherwise. # See Also `systemd(1)`, `systemd-imds(1)`, `systemd-imdsd@.service(8)`, `systemd.system-credentials(7)` # systemd-imds systemd systemd-imds 1 systemd-imds systemd-imds-import.service Cloud IMDS (Instance Metadata Service) tool `systemd-imds-import.service` systemd-imds OPTIONS KEY # Description `systemd-imds` is a tool for acquiring data from IMDS (Instance Metadata Service), as provided in many cloud environments. It is a client to `systemd-imdsd@.service(8)`, and provides access to IMDS data from shell environments. The tool can operate in one of five modes: - Without positional arguments (and without the `--well-known=` switch) general IMDS service data and a few well known fields are displayed in human friendly form. - With a positional argument (and without `--well-known=`) the IMDS data referenced by the specified key is acquired and written to standard output, in unprocessed form. IMDS keys are the part of the IMDS acquisition URL that are suffixed to the base URL. IMDS keys must begin with a slash (`/`). Note that IMDS keys are typically implementation-specific. - With the `--well-known=` option specified (see below), the indicated well-known field is written to standard output, in unprocessed form. The concept of well-known fields abstracts IMDS implementation differences to some level, exposing a unified interface for IMDS fields that typically exist on many different implementations, but under implementation-specific keys. - With the `--userdata` option specified (see below) the "userdata" provided via IMDS is written to standard output. Under the hood this is similar to `--well-known=userdata-base`, `--well-known=userdata` or `--well-known=userdata-base64`. Each of the three is tried in turn (in this order), and the first available is returned. For `--well-known=userdata-base` the `systemd-userdata` userdata item is requested. For `--well-known=userdata-base64` the returned data is automatically Base64-decoded. - With the `--import` option specified, various well known and userdata fields are imported into the local credential store, where they are used to configure and parameterize the system. For details see below. In addition, when invoked as a Varlink service (i.e. via socket activation through `systemd-imds-metrics.socket`), `systemd-imds` acts as an `io.systemd.Metrics` provider for `systemd-report(1)`. It exposes the detected cloud vendor and the well-known `hostname`, `region`, `zone`, `ipv4-public` and `ipv6-public` fields as metrics in the `io.systemd.InstanceMetadata.` namespace. The data is acquired on demand from `systemd-imdsd@.service(8)`, benefiting from its local cache. # Options and Commands `--well-known=`; `-K` Takes one of `hostname`, `region`, `zone`, `ipv4-public`, `ipv6-public`, `ssh-key`, `userdata`, `userdata-base`, `userdata-base64`. Acquires a specific "well-known" field from IMDS. Many of these fields are commonly supported by various IMDS implementations, but typically some fields are not. Note that if `--well-known=userdata-base` is used an additional subkey should be specified as positional argument, which encodes the specific userdata item to acquire. `--refresh=` Takes a time in seconds as argument, and indicates the required "freshness" of the data, in case cached data is used. `--cache=` Takes a boolean. If set to false local caching of IMDS is disabled, and the data is always acquired fresh from the IMDS endpoint. `--userdata`; `-u` Acquire this instance's IMDS user data, if available. See above for details. `--import` Acquires IMDS data and writes relevant fields as credentials to `/run/credstore/`. This currently covers: - If the IMDS user data is a valid JSON object containing a field `systemd.credentials` (with a JSON array as value) it is processed, importing arbitrary credentials listed in the array. Each array item must have a `name` field indicating the credential name. It may have one `text`, `data` or `encrypted` field, containing the credential data. If `text` is used the value shall be a literal string of the credential value. If `data` is used the value may be arbitrary binary data encoded in a Base64 string. If `encrypted` is used the value shall be a Base64 encoded encrypted credential. See `systemd.system-credentials(7)` for information about credentials that may be imported this way. - If the well-known `ssh-key` field is available, its value will be imported into the `ssh.authorized_keys.root` credential. - If the well-known `hostname` field is available, its value will be imported into the `firstboot.hostname` credential. This command is invoked by the `systemd-imds-import.service` run at boot. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-imdsd@.service(8)`, `systemd-imds-generator(8)`, `systemd-report(1)`, `systemd.system-credentials(7)` # systemd-imdsd@.service systemd systemd-imdsd@.service 8 systemd-imdsd@.service systemd-imdsd systemd-imdsd.socket systemd-imdsd-early-network.service Cloud IMDS (Instance Metadata Service) client `systemd-imdsd@.service` `systemd-imdsd.socket` `systemd-imdsd-early-network.service` `/usr/lib/systemd/systemd-imdsd` # Description `systemd-imdsd@.service` is a system service that provides local access to IMDS (Instance Metadata Service; or equivalent) functionality, as provided by many public clouds. The service provides a Varlink IPC interface via `/run/systemd/io.systemd.InstanceMetadata` to query IMDS fields. `systemd-imdsd-early-network.service` is a system service that generates a `systemd-networkd.service(8)` compatible `systemd.network(5)` file for configuring the early-boot network in order to be able to contact the IMDS endpoint. The `systemd-imds(1)` tool may be used to query information from this service. # Kernel Command Line Options The IMDS endpoint is typically determined automatically via `hwdb(7)` records, but can also be configured explicitly via the kernel command line, via the following options: `systemd.imds.network=` Takes one of `off`, `locked`, `unlocked`. Controls whether and how to set up networking for IMDS endpoint access. Unless set to `off` early boot networking is enabled, ensuring that the IMDS endpoint can be reached. If set to `locked` direct access to the IMDS endpoint by regular unprivileged processes is disabled via a "prohibit" route, so that any access must be done through `systemd-imdsd@.service` or its associated tools. If set to `unlocked` (the default) this "prohibit" route is not created, and regular unprivileged processes can directly contact IMDS. `systemd.imds.vendor=` A short string identifying the cloud vendor. Example: systemd.imds.vendor=foobarcloud `systemd.imds.token_url=` If a bearer token must be acquired to talk to the IMDS service, this is the URL to acquire it from. `systemd.imds.refresh_header_name=` Takes a HTTP header field name (excluding the `:`) that declares the header field for passing the TTL value (in seconds) to the HTTP server when acquiring a token. Only applies if `systemd.imds.token_url=` is set too. `systemd.imds.data_url=` Takes the base URL to acquire the IMDS data from (the IMDS "endpoint"). All data fields are acquired from below this URL. This URL should typically not end in `/`. The data URLs are concatenated from this base URL, the IMDS "key" and the suffix configured via `systemd.imds.data_url_suffix=` below. Well-known IMDS "keys" can be configured via the `systemd.imds.key=*` options below. Example: systemd.imds.data_url=http://169.254.169.254/metadata `systemd.imds.data_url_suffix=` If specified, this field is appended to the end of the data URL (after appending the IMDS "key" to the data base URL), see above. Example: systemd.imds.data_url_suffix=?api-version=2025-04-07&format=text `systemd.imds.token_header_name=` Takes a HTTP header field name (excluding the `:`) that declares the header field to pass the bearer token acquired from the token URL (see above) in. Only applies if `systemd.imds.token_url=` is set too. `systemd.imds.extra_header=` Takes a full HTTP header expression (both field name and value, separated by a colon `:`) to pass to the HTTP server when requesting data. May be used multiple times to set multiple headers. Example: systemd.imds.extra_header=Metadata:true `systemd.imds.address_ipv4=` Configures the IPv4 address the IMDS endpoint is contacted on. This should typically be the IP address also configured via `systemd.imds.data_url=` (if IPv4 is used) and is used to set up IP routing. Example: systemd.imds.address_ipv4=169.254.169.254 `systemd.imds.address_ipv6=` Configures the IPv6 address the IMDS endpoint is contacted on. This should typically be the IP address also configured via `systemd.imds.data_url=` (if IPv6 is used) and is used to set up IP routing. `systemd.imds.key.hostname=`; `systemd.imds.key.region=`; `systemd.imds.key.zone=`; `systemd.imds.key.ipv4_public=`; `systemd.imds.key.ipv6_public=`; `systemd.imds.key.ssh_key=`; `systemd.imds.key.userdata=`; `systemd.imds.key.userdata_base=`; `systemd.imds.key.userdata_base64=` Configures strings to concatenate to the data base URL (see above) to acquire data for various "well-known" fields. These strings must begin with a `/`. They should return the relevant data in plain text. A special case are the three "userdata" keys: the option `systemd.imds.key.userdata_base=` should be used if the IMDS service knows a concept of multiple userdata fields, and a field identifier thus still needs to be appended to the userdata base URL. The option `systemd.imds.key.userdata=` should be used if only a single userdata field is supported. The option `systemd.imds.key.userdata_base64=` should be used in the same case, but only if the userdata field is encoded in Base64. Example: systemd.imds.key.hostname=/instance/compute/osProfile/computerName # Credentials `systemd-imdsd@.service` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `imds.vendor`; `imds.vendor_token`; `imds.refresh_header_name`; `imds.data_url`; `imds.data_url_suffix`; `imds.token_header_name`; `imds.extra_header`; `imds.extra_header2`; `imds.extra_header3`; `imds.extra_header…`; `imds.address_ipv4`; `imds.address_ipv6`; `imds.key_hostname`; `imds.key_region`; `imds.key_zone`; `imds.key_ipv4_public`; `imds.key_ipv6_public`; `imds.key_ssh_key`; `imds.key_userdata`; `imds.key_userdata_base`; `imds.key_userdata_base64` The various IMDS endpoint parameters. The semantics are very close to those configurable via kernel command line, see above for the matching list. # See Also `systemd(1)`, `systemd-imds(1)`, `systemd-imds-generator(8)`, `systemd-networkd.service(8)` # systemd-import-generator systemd systemd-import-generator 8 systemd-import-generator Generator for automatically downloading disk images at boot `/usr/lib/systemd/system-generators/systemd-import-generator` # Description `systemd-import-generator` may be used to automatically download disk images (tarballs or DDIs) via `systemd-importd.service(8)` at boot, based on parameters on the kernel command line or via system credentials. This is useful for automatically deploying an `systemd-confext(8)`, `systemd-sysext(8)`, `systemd-nspawn(1)`/ `systemd-vmspawn(1)` or `systemd-portabled.service(8)` image at boot. This provides functionality equivalent to `importctl(1)`, but accessible via the kernel command line and system credentials. `systemd-import-generator` implements `systemd.generator(7)`. # Kernel Command Line `systemd-import-generator` understands the following `kernel-command-line(7)` parameters: `systemd.pull=` This option takes a colon separate triplet of option string, local target image name and remote URL. The local target image name can be specified as an empty string, in which case the name is derived from the specified remote URL. The remote URL must using the `http://`, `https://`, `file://` schemes. The option string itself is a comma separated list of options: rw; ro Controls whether to mark the local image as read-only. If not specified read-only defaults to off. verify= Controls whether to cryptographically validate the download before installing it in place. Takes one of `no`, `checksum`, or `signature` (the default if not specified). For details see the `--verify=` of `importctl(1)`. sysext; confext; machine; portable Controls the image class to download, and thus ultimately the target directory for the image, depending on this choice the target directory `/var/lib/extensions/`, `/var/lib/confexts/`, `/var/lib/machines/` or `/var/lib/portables/` is selected. Specification of exactly one of these options is mandatory. tar; raw Controls the type of resource to download, i.e. a (possibly compressed) tarball that needs to be unpacked into a file system tree, or (possibly compressed) raw disk image (DDI). Specification of exactly one of these options is mandatory. blockdev If this option is specified the downloaded image is attached to a loopback block device (via `systemd-loop@.service`) after completion. This permits booting from downloaded disk images. This is only supported for `raw` disk images. Note when this option is used with the purpose of mounting a disk image conforming to the [UAPI.3 Discoverable Disk Image Specification](https://uapi-group.org/specifications/specs/discoverable_disk_image/) as root file system, and the automatic GPT partition discovery logic as implemented by `systemd-gpt-auto-generator(8)` shall process it, it's essential to specify `rootdisk` as the local name for the import. Moreover, `root=gpt-auto` must be specified on the kernel command line explicitly. Also, prefix the `systemd.pull=` command line option with `rd.` to ensure it is executed in the initial RAM disk (initrd) already, also see below. bootorigin If this option is specified, in place of the URL a simple filename may be specified. If the system is booted via UEFI HTTP network booting the last component of the network boot origin URL is replaced by this filename and used as download source. This hence allows one to automatically derive the URLs for disk images from the original boot URL used to invoke the kernel or boot loader. If this option is used and the system is not actually booted via UEFI HTTP network booting, the download is gracefully skipped. Or in other words without other modifications it is possible to put together an initrd image that will boot from a local disk if available, or from downloaded disk image if used via network booting. runtime= Takes a boolean argument. If set to true, the image is downloaded below the `/run/` hierarchy, if set to false below the `/var/lib/` hierarchy. If not specified defaults to true in the initial RAM disk (initrd) and to false on the host system. `systemd.pull.success_action=`; `systemd.pull.failure_action=` Controls whether to execute an action such as reboot, power-off and similar after completing the download successfully, or unsuccessfully. See `SuccessAction=`/`FailureAction=` on `systemd.unit(5)` for details about the available actions. If not specified, no action is taken, and the system will continue to boot normally. These kernel command line options are interpreted by the host system only. If these options are prefixed with `rd.` they are interpreted by the initial RAM disk (initrd) instead. # Credentials `systemd-import-generator` supports the system credentials logic. The following credentials are used when passed in: `import.pull` This credential should be a text file, with each line referencing one download operation. Each line should follow the same format as the value of the `systemd.pull=` kernel command line option described above. # Examples
Download Configuration Extension
systemd.pull=raw,confext::https://example.com/myconfext.raw.gz With a kernel command line option like the above a configuration extension DDI is downloaded automatically at boot from the specified URL, validated cryptographically, uncompressed and installed.
Download System Extension (Without Validation)
systemd.pull=tar,sysext,verify=no::https://example.com/mysysext.tar.gz With a kernel command line option like the above a system extension tarball is downloaded automatically at boot from the specified URL, uncompressed and installed – without any cryptographic validation. This is useful for development purposes in virtual machines and containers. Warning: do not deploy a system with validation disabled like this!
Download root disk image (raw) into memory, for booting into it
rd.systemd.pull=raw,machine,verify=no,blockdev:image:https://example.com/image.raw.xz root=/dev/disk/by-loop-ref/image.raw-part2 This downloads the specified disk image, saving it locally under the name `image`, and attaches it to a loopback block device on completion. It then boots from the 2nd partition in the image.
Boot into disk image (raw), with URL derived from UEFI HTTP network booting
rd.systemd.pull=raw,machine,verify=no,blockdev,bootorigin:rootdisk:image.raw.xz root=gpt-auto This is similar to the previous example, but this time the source URL is automatically derived from the UEFI HTTP network boot URL. For example, if an UKI is booted from an URL `http://example.com/image.efi` this would result in a root disk being downloaded from `http://example.com/image.raw.xz`. Moreover this uses the `systemd-gpt-auto-generator(8)` logic to mount the root file system from the disk image.
Boot into disk image (tar), with URL derived from UEFI HTTP network booting
rd.systemd.pull=tar,machine,verify=no,bootorigin:root:image.tar.xz root=bind:/run/machines/root This is similar to the previous example, but instead of a raw (i.e. block device based) disk image the system boots into a tarball that is downloaded from the originating UEFI network server.
# See Also `systemd(1)`, `systemd-importd.service(8)`, `kernel-command-line(7)`, `systemd.system-credentials(7)`, `importctl(1)`, `systemd-loop@.service(8)`, `systemd-gpt-auto-generator(8)` # systemd-importd.service systemd systemd-importd.service 8 systemd-importd.service systemd-importd VM and container image import and export service `systemd-importd.service` `/usr/lib/systemd/systemd-importd` # Description `systemd-importd` is a system service that allows importing, exporting and downloading of disk images. It provides the implementation for `importctl(1)`'s `pull-raw`, `pull-tar`, `import-raw`, `import-tar`, `import-fs`, `export-raw`, and `export-tar` commands. See `org.freedesktop.import1(5)` and `org.freedesktop.LogControl1(5)` for a description of the D-Bus API. # See Also `systemd(1)`, `importctl(1)`, `systemd-machined.service(8)`, `systemd-nspawn(1)`, `org.freedesktop.import1(5)` # systemd-inhibit systemd systemd-inhibit 1 systemd-inhibit Execute a program with an inhibition lock taken systemd-inhibit OPTIONS COMMAND ARGUMENTS systemd-inhibit OPTIONS --list # Description `systemd-inhibit` may be used to execute a program with a shutdown, sleep, or idle inhibitor lock taken. The lock will be acquired before the specified command line is executed and released afterwards. Inhibitor locks may be used to block or delay system sleep and shutdown requests from the user, as well as automatic idle handling of the OS. This is useful to avoid system suspends while an optical disc is being recorded, or similar operations that should not be interrupted. For more information see [Inhibitor Locks](https://systemd.io/INHIBITOR_LOCKS). # Options The following options are understood: `--what=` Takes a colon-separated list of one or more operations to inhibit: `shutdown`, `sleep`, `idle`, `handle-power-key`, `handle-reboot-key`, `handle-suspend-key`, `handle-hibernate-key`, `handle-lid-switch`, for inhibiting reboot/power-off/halt/kexec/soft-reboot, suspending/hibernating, the automatic idle detection, or the low-level handling of the power/reboot/sleep key and the lid switch, respectively. If omitted, defaults to `idle:sleep:shutdown`, or to `sleep:shutdown` if `--mode=delay` is used, since delay locks are only supported for `sleep` and `shutdown`. `--who=` Takes a short, human-readable descriptive string for the program taking the lock. If not passed, defaults to the command line string. `--why=` Takes a short, human-readable descriptive string for the reason for taking the lock. Defaults to "Unknown reason". `--mode=` Takes `block`, `delay`, or `block-weak` and describes how the lock is applied. If `block` is used (the default), the lock prohibits any of the requested operations without time limit, and only privileged users may override it. The `block-weak` inhibitor lock type is similar to `block` but is not enforced against operations initiated by privileged clients or those owned by the user that also owns the inhibitor lock. If `delay` is used, the lock can only delay the requested operations for a limited time. If the time elapses, the lock is ignored and the operation executed. The time limit may be specified in `logind.conf(5)`. Note that `delay` is only available for `sleep` and `shutdown`. `--list` Lists all active inhibition locks instead of acquiring one. It can be filtered using `--what=`, `--who=`, `--why=`, or `--mode=`. # Exit status Returns the exit status of the executed program. # Example # systemd-inhibit wodim foobar.iso This burns the ISO image `foobar.iso` on a CD using `wodim(1)`, and inhibits system sleeping, shutdown and idle while doing so. # See Also `systemd(1)`, `logind.conf(5)` # systemd-integritysetup-generator systemd systemd-integritysetup-generator 8 systemd-integritysetup-generator Unit generator for integrity protected block devices `/usr/lib/systemd/system-generators/systemd-integritysetup-generator` # Description `systemd-integritysetup-generator` is a generator that translates `/etc/integritytab` entries into native systemd units early at boot. This will create `systemd-integritysetup@.service(8)` units as necessary. `systemd-integritysetup-generator` implements `systemd.generator(7)`. # See Also `systemd(1)`, `systemd-integritysetup@.service(8)`, `integritysetup(8)` # systemd-integritysetup@.service systemd systemd-integritysetup@.service 8 systemd-integritysetup@.service systemd-integritysetup Disk integrity protection logic `systemd-integritysetup@.service` `/usr/lib/systemd/systemd-integritysetup` # Description `systemd-integritysetup@.service` is a service responsible for setting up integrity protected block devices. It should be instantiated for each device that requires integrity protection. At early boot and when the system manager configuration is reloaded, entries from `integritytab(5)` are converted into `systemd-integritysetup@.service` units by `systemd-integritysetup-generator(8)`. `systemd-integritysetup@.service` calls `systemd-integritysetup`. # Commands The following commands are understood by `systemd-integritysetup`: `attach` \ \ \[\\] \[\\] Create a block device \ using \. See `integritytab(5)` and [ Kernel dm-integrity](https://docs.kernel.org/admin-guide/device-mapper/dm-integrity.html) documentation for details. `detach` \ Detach (destroy) the block device \. `help` Print short information about command syntax. # See Also `systemd(1)`, `integritytab(5)`, `systemd-integritysetup-generator(8)`, `integritysetup(8)` # systemd-journal-gatewayd.service systemd systemd-journal-gatewayd.service 8 systemd-journal-gatewayd.service systemd-journal-gatewayd.socket systemd-journal-gatewayd HTTP server for journal events `systemd-journal-gatewayd.service` `systemd-journal-gatewayd.socket` /usr/lib/systemd/systemd-journal-gatewayd OPTIONS # Description `systemd-journal-gatewayd` serves journal events over the network. Clients must connect using HTTP. The server listens on port 19531 by default. If `--cert=` is specified, the server expects HTTPS connections. The program is started by `systemd(1)` and expects to receive a single socket. Use `systemctl start systemd-journal-gatewayd.socket` to start the service, and `systemctl enable systemd-journal-gatewayd.socket` to have it started on boot. # Options The following options are understood: `--cert=` Specify the path to a file or `AF_UNIX` stream socket to read the server certificate from. The certificate must be in PEM format. This option switches `systemd-journal-gatewayd` into HTTPS mode and must be used together with `--key=`. `--key=` Specify the path to a file or `AF_UNIX` stream socket to read the secret server key corresponding to the certificate specified with `--cert=` from. The key must be in PEM format. `--trust=` Specify the path to a file or `AF_UNIX` stream socket to read a CA certificate from. The certificate must be in PEM format. `--system`; `--user` Limit served entries to entries from system services and the kernel, or to entries from services of current user. This has the same meaning as `--system` and `--user` options for `journalctl(1)`. If neither is specified, all accessible entries are served. `-m`; `--merge` Serve entries interleaved from all available journals, including other machines. This has the same meaning as `--merge` option for `journalctl(1)`. `-D DIR`; `--directory=DIR` Takes a directory path as argument. If specified, `systemd-journal-gatewayd` will serve the specified journal directory \ instead of the default runtime and system journal paths. `--file=GLOB` Takes a file glob as an argument. Serve entries from the specified journal files matching \ instead of the default runtime and system journal paths. May be specified multiple times, in which case files will be suitably interleaved. This has the same meaning as `--file=` option for `journalctl(1)`. # Supported URLs The following URLs are recognized: [/boots](/boots) Returns json-seq (RFC 7464) response containing JSON objects, each one containing boot number, its ID and the timestamps of the first and last message. Boots are returned starting with the latest boot first and use the same schema as `journalctl --list-boots --output json`. [/browse](/browse) Interactive browsing. [/entries\[?option1&option2=value…\]](/entries[?option1&option2=value…]) Retrieval of events in various formats. The `Accept:` part of the HTTP header determines the format. Supported values are described below. The `Range:` part of the HTTP header determines the range of events returned. Supported values are described below. GET parameters can be used to modify what events are returned. Supported parameters are described below. [/machine](/machine) Return a JSON structure describing the machine. Example: { "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446", "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7", "hostname" : "fedora", "os_pretty_name" : "Fedora 19 (Rawhide)", "virtualization" : "kvm", …} [/fields/](/fields/) Return a list of values of this field present in the logs. # Accept header `Accept: format` Recognized formats: `text/plain` The default. Plaintext syslog-like output, one line per journal entry (like `journalctl --output short`). `application/json` Entries are formatted as JSON data structures, one per line (like `journalctl --output json`). See [Journal JSON Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format) for more information. `text/event-stream` Entries are formatted as JSON data structures, wrapped in a format suitable for [ Server-Sent Events](https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events) (like `journalctl --output json-sse`). `application/vnd.fdo.journal` Entries are serialized into a binary (but mostly text-based) stream suitable for backups and network transfer (like `journalctl --output export`). See [Journal Export Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format) for more information. # Range header `Range: entries=[cursor][[:num_skip]:[num_entries]]` `Range: realtime=[since]:[until][[:num_skip]:num_entries]` where \ is a cursor string, defaults to the first entry, \ and \ are timestamps (seconds since 1970-01-01 00:00:00 UTC), \ is an integer, \ is an unsigned integer. Range defaults to all available events. If \ is negative and no \ is given, the last entry will be the reference point. # URL GET parameters Following parameters can be used as part of the URL: [follow](follow) wait for new events (like `journalctl --follow`, the number of events returned is not limited, unless \ is specified in the \ header). [discrete](discrete) Test that the specified cursor refers to an entry in the journal. Returns just this entry. [boot](boot) Limit events to the current boot of the system (like `journalctl -b`). [=](=) Match journal fields. See `systemd.journal-fields(7)`. # Examples Retrieve events from this boot from local journal in [Journal Export Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format): curl --silent -H'Accept: application/vnd.fdo.journal' \ 'http://localhost:19531/entries?boot' Listen for core dumps: curl 'http://localhost:19531/entries?follow&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1' # See Also `systemd(1)`, `journalctl(1)`, `systemd.journal-fields(7)`, `systemd-journald.service(8)`, `systemd-journal-remote.service(8)`, `systemd-journal-upload.service(8)` # systemd-journald.service systemd systemd-journald.service 8 systemd-journald.service systemd-journald.socket systemd-journald-dev-log.socket systemd-journald-audit.socket systemd-journald-metrics.socket systemd-journald@.service systemd-journald@.socket systemd-journald-varlink@.socket systemd-journald Journal service `systemd-journald.service`, `systemd-journald.socket`, `systemd-journald-dev-log.socket`, `systemd-journald-audit.socket`, `systemd-journald-metrics.socket`, `systemd-journald@.service`, `systemd-journald@.socket`, `systemd-journald-varlink@.socket`, `/usr/lib/systemd/systemd-journald` # Description `systemd-journald` is a system service that collects and stores logging data. It creates and maintains structured, indexed journals based on logging information that is received from a variety of sources: - Kernel log messages, via kmsg - Simple system log messages, via the `libc` `syslog(3)` call - Structured system log messages via the native Journal API, see `sd_journal_print(3)` and [Native Journal Protocol](https://systemd.io/JOURNAL_NATIVE_PROTOCOL) - Standard output and standard error of service units. For further details see below. - Audit records, originating from the kernel audit subsystem The daemon will implicitly collect numerous metadata fields for each log messages in a secure and unfakeable way. See `systemd.journal-fields(7)` for more information about the collected metadata. Log data collected by the journal is primarily text-based but can also include binary data where necessary. Individual fields making up a log record stored in the journal may be up to 2⁶⁴-1 bytes in size. The journal service stores log data either persistently below `/var/log/journal` or in a volatile way below `/run/log/journal/` (in the latter case, it is lost at reboot). By default, log data is stored persistently if `/var/log/journal/` exists during boot, with an implicit fallback to volatile storage otherwise. Use `Storage=` in `journald.conf(5)` to configure where log data is placed, independently of the existence of `/var/log/journal/`. Note that journald will initially use volatile storage, until a call to `journalctl --flush` (or sending `SIGUSR1` to journald) will cause it to switch to persistent logging (under the conditions mentioned above). This is done automatically on boot via `systemd-journal-flush.service`. On systems where `/var/log/journal/` does not exist yet but where persistent logging is desired (and the default `journald.conf` is used), it is sufficient to create the directory, and ensure it has the correct access modes and ownership: mkdir -p /var/log/journal systemd-tmpfiles --create --prefix /var/log/journal See `journald.conf(5)` for information about the configuration of this service. # Stream logging The systemd service manager invokes all service processes with standard output and standard error connected to the journal by default. This behaviour may be altered via the `StandardOutput=`/`StandardError=` unit file settings, see `systemd.exec(5)` for details. The journal converts the log byte stream received this way into individual log records, splitting the stream at newline (`\n`, ASCII `10`) and `NUL` bytes. If `systemd-journald.service` is stopped, the stream connections associated with all services are terminated. Further writes to those streams by the service will result in `EPIPE` errors. In order to react gracefully in this case, it is recommended that programs logging to standard output/error ignore such errors. If the `SIGPIPE` UNIX signal handler is not blocked or turned off, such write attempts will also result in such process signals being generated, see `signal(7)`. To mitigate this issue, systemd service manager explicitly turns off the `SIGPIPE` signal for all invoked processes by default (this may be changed for each unit individually via the `IgnoreSIGPIPE=` option, see `systemd.exec(5)` for details). After the standard output/standard error streams have been terminated they may not be recovered until the services they are associated with are restarted. Note that during normal operation, `systemd-journald.service` stores copies of the file descriptors for those streams in the service manager. If `systemd-journald.service` is restarted using `systemctl restart` or equivalent operation instead of a pair of separate `systemctl stop` and `systemctl start` commands (or equivalent operations), these stream connections are not terminated and survive the restart. It is thus safe to restart `systemd-journald.service`, but stopping it is not recommended. Note that the log record metadata for records transferred via such standard output/error streams reflect the metadata of the peer the stream was originally created for. If the stream connection is passed on to other processes (such as further child processes forked off the main service process), the log records will not reflect their metadata, but will continue to describe the original process. This is different from the other logging transports listed above, which are inherently record based and where the metadata is always associated with the individual record. In addition to the implicit standard output/error logging of services, stream logging is also available via the `systemd-cat(1)` command line tool. Currently, the number of parallel log streams `systemd-journald` will accept is limited to 4096. When this limit is reached further log streams may be established but will receive `EPIPE` right from the beginning. # Journal Namespaces Journal 'namespaces' are both a mechanism for logically isolating the log stream of projects consisting of one or more services from the rest of the system and a mechanism for improving performance. Multiple journal namespaces may exist simultaneously, each defining its own, independent log stream managed by its own instance of `systemd-journald`. Namespaces are independent of each other, both in the data store and in the IPC interface. By default, only a single "default namespace exists, managed by `systemd-journald.service` (and its associated socket units). Additional namespaces are created by starting an instance of the `systemd-journald@.service` service template. The instance name is the namespace identifier, which is a short string used for referencing the journal namespace. Service units may be assigned to a specific journal namespace through the `LogNamespace=` unit file setting, see `systemd.exec(5)` for details. The `--namespace=` switch of `journalctl(1)` may be used to view the log stream of a specific namespace. If the switch is not used the log stream of the default namespace is shown, i.e. log data from other namespaces is not visible. Services associated with a specific log namespace may log via `syslog(3)`, the native logging protocol of the journal and via stdout/stderr; the logging from all three transports is associated with the namespace. By default, only the default namespace will collect kernel and audit log messages. The `systemd-journald` instance of the default namespace is configured through `/etc/systemd/journald.conf` (see below), while the other instances are configured through `/etc/systemd/journald@NAMESPACE.conf`. The journal log data for the default namespace is placed in `/var/log/journal/MACHINE_ID` (see below) while the data for the other namespaces is located in `/var/log/journal/MACHINE_ID.NAMESPACE`. # Signals SIGUSR1 Request that journal data from `/run/` is flushed to `/var/` in order to make it persistent (if this is enabled). This must be used after `/var/` is mounted, as otherwise log data from `/run/` is never flushed to `/var/` regardless of the configuration. Use the `journalctl --flush` command to request flushing of the journal files, and wait for the operation to complete. See `journalctl(1)` for details. SIGUSR2 Request immediate rotation of the journal files. Use the `journalctl --rotate` command to request journal file rotation, and wait for the operation to complete. SIGRTMIN+1 Request that all unwritten log data is written to disk. Use the `journalctl --sync` command to trigger journal synchronization, and wait for the operation to complete. SIGHUP Upon reception of the `SIGHUP` process signal `systemd-journald` will reload its configuration values and update the kernel log buffer and journals to reflect the new configuration. If `ReadKmsg=` has changed, the kernel log buffer will be flushed and updated as part of the reload. The active journal (e.g., persistent, volatile) will continue to be used with the updated configuration. However, if the storage mode has changed from persistent to volatile and the current journal in use is the persistent journal, then the active journal will be switched to the volatile journal. # Credentials `systemd-journald` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `journal.forward_to_socket` May contain a socket address to which logs should be forwarded. See `ForwardToSocket=` in `journald.conf(5)`. `journal.storage` May be used to specify where journal files should be stored. See `Storage=` in `journald.conf(5)`. # Kernel Command Line A few configuration parameters from `journald.conf` may be overridden on the kernel command line: `systemd.journald.forward_to_syslog=`; `systemd.journald.forward_to_kmsg=`; `systemd.journald.forward_to_console=`; `systemd.journald.forward_to_wall=` Enables/disables forwarding of collected log messages to syslog, the kernel log buffer, the system console or wall. See `journald.conf(5)` for information about these settings. `systemd.journald.max_level_store=`; `systemd.journald.max_level_syslog=`; `systemd.journald.max_level_kmsg=`; `systemd.journald.max_level_console=`; `systemd.journald.max_level_wall=`; `systemd.journald.max_level_socket=` Controls the maximum log level of messages that are stored in the journal, forwarded to `syslog(3)`, kmsg, the console, `wall(1)`, or a socket. This kernel command line options override the settings of the same names in the `journald.conf(5)` file. Note that these kernel command line options are only honoured by the default namespace, see above. # Access Control Journal files are, by default, owned and readable by the `systemd-journal` system group but are not writable. Adding a user to this group thus enables them to read the journal files. By default, each user, with a UID outside the range of system users, dynamic service users, and the nobody user, will get their own set of journal files in `/var/log/journal/`. See [Users, Groups, UIDs and GIDs on systemd systems](https://systemd.io/UIDS-GIDS) for more details about UID ranges. These journal files will not be owned by the user, however, in order to avoid that the user can write to them directly. Instead, file system ACLs are used to ensure the user gets read access only. Additional users and groups may be granted access to journal files via file system access control lists (ACL). Distributions and administrators may choose to grant read access to all members of the `wheel` and `adm` system groups with a command such as the following: # setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/ Note that this command will update the ACLs both for existing journal files and for future journal files created in the `/var/log/journal/` directory. # Metrics `systemd-journald` is a metrics source for `systemd-report(1)`. If `systemd-journald-metrics.socket` is enabled, it implements the `io.systemd.Metrics` Varlink interface on `/run/systemd/report/io.systemd.JournalDaemon`, and reports the following counter metrics: `io.systemd.JournalDaemon.MessagesByPriority` The number of log messages received since boot, by priority. The metric field `priority` is set to one of `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, `debug`. `io.systemd.JournalDaemon.MessagesByTransport` The number of log messages received since boot, by transport. The metric field `transport` is set to one of `syslog`, `journal`, `stdout`, `audit`, `kernel`, matching the `_TRANSPORT=` journal field, see `systemd.journal-fields(7)`. Messages are counted when they are received, before any filtering (such as `LogLevelMax=`, `LogFilterPatterns=`, `MaxLevelStore=`, `Storage=none`) or rate limiting is applied. The counters hence include messages that are not stored in the journal. Messages generated by `systemd-journald` itself are not counted. The counters are kept across restarts of the service, but reset on reboot. Only the default journal namespace provides these metrics. # Files `/etc/systemd/journald.conf` Configure `systemd-journald` behavior. See `journald.conf(5)`. `/run/log/journal/machine-id/*.journal`; `/run/log/journal/machine-id/*.journal~`; `/var/log/journal/machine-id/*.journal`; `/var/log/journal/machine-id/*.journal~` `systemd-journald` writes entries to files in `/run/log/journal/machine-id/` or `/var/log/journal/machine-id/` with the `.journal` suffix. If the daemon is stopped uncleanly, or if the files are found to be corrupted, they are renamed using the `.journal~` suffix, and `systemd-journald` starts writing to a new file. `/run/` is used when `/var/log/journal` is not available, or when `Storage=volatile` is set in the `journald.conf(5)` configuration file. When `systemd-journald` ceases writing to a journal file, it will be renamed to `original-name@suffix.journal` (or `original-name@suffix.journal~`). Such files are "archived" and will not be written to any more. In general, it is safe to read or copy any journal file (active or archived). `journalctl(1)` and the functions in the `sd-journal(3)` library should be able to read all entries that have been fully written. `systemd-journald` will automatically remove the oldest archived journal files to limit disk use. See `SystemMaxUse=` and related settings in `journald.conf(5)`. `/dev/kmsg`; `/dev/log`; `/run/systemd/journal/dev-log`; `/run/systemd/journal/socket`; `/run/systemd/journal/stdout` Sockets and other file node paths that `systemd-journald` will listen on and are visible in the file system. In addition to these, `systemd-journald` can listen for audit events using `netlink(7)`, depending on whether `systemd-journald-audit.socket` is enabled or not. `/run/systemd/journal/counters` The message counters reported via the metrics described above. This file is internal to `systemd-journald` and not a stable interface. If journal namespacing is used these paths are slightly altered to include a namespace identifier, see above. # See Also `systemd(1)`, `journalctl(1)`, `journald.conf(5)`, `systemd.journal-fields(7)`, `sd-journal(3)`, `systemd-coredump(8)`, `setfacl(1)`, `sd_journal_print(3)`, `pydoc systemd.journal` # systemd-keyring-setup.service systemd systemd-keyring-setup.service 8 systemd-keyring-setup.service systemd-keyring-setup Enroll certificates into kernel keyrings `systemd-keyring-setup.service` /usr/lib/systemd/systemd-keyring-setup OPTIONS KEYRING # Description `systemd-keyring-setup.service` is an early boot service that enrolls X.509 certificates into the kernel keyrings used to verify signatures on dm-verity volumes, fs-verity files and BPF programs, and then seals these keyrings. The certificates are read from the [File Hierarchy for the Verification of OS Artifacts](https://uapi-group.org/specifications/specs/file_hierarchy_for_the_verification_of_os_artifacts/) (VOA). This allows the kernel to verify signatures with keys provided by the OS vendor or the local administrator, without rebuilding the kernel and without enrolling the keys into the firmware. The following keyrings are provisioned, each from a VOA *context* of the `kernel-keyring` purpose: | Keyring | VOA context | Used to verify | |----|----|----| | `.dm-verity` | `dm-verity` | Signatures of the root hashes of dm-verity volumes, such as those of Discoverable Disk Images set up by `systemd-veritysetup@.service(8)`, `systemd-dissect(1)` or the `RootImage=` setting of services | | `.fs-verity` | `fs-verity` | Built-in signatures of fs-verity protected files | | `.bpf` | `bpf` | Signatures of BPF programs | Keyrings and VOA contexts The kernel only uses the `.dm-verity` and `.bpf` keyrings once they have been sealed, and seals them itself while they are still empty, unless `dm_verity.keyring_unsealed=1` or `bpf.keyring_unsealed=1` is specified on the kernel command line, respectively. Hence, these options are required to provision the two keyrings, see below. The `.fs-verity` keyring is not sealed by the kernel, and is used as soon as it contains a key. For each keyring that is not sealed yet, the service enrolls the certificates it finds and then seals the keyring: it installs a restriction so that only certificates signed by a key in the keyring can be added afterwards, and removes the permission to change this restriction or the permissions of the keyring. The keyring is sealed even if no certificates were found, or if some of them could not be enrolled. Keys that were already in the keyring before the service ran are sealed in as well, and a warning is logged about them. The service runs both in the initrd and on the host. Usually, the keyrings are provisioned in the initrd, since the root file system might itself be a dm-verity volume that is verified with one of the enrolled keys. When the service runs again on the host, the keyrings have been sealed already. In this case, only certificates signed by a key that was enrolled earlier can be added, and all other certificates are rejected. Certificates that have been enrolled already are skipped. # Certificate Directories and Precedence Certificates are read from the VOA load paths `/etc/voa/`, `/run/voa/`, `/usr/local/share/voa/` and `/usr/share/voa/`, in order of decreasing priority. For each keyring, artifact verifiers are read from `OS/kernel-keyring/CONTEXT/x509/NAME-certificate.pem`, and trust anchors from `OS/trust-anchor-kernel-keyring/CONTEXT/x509/NAME-certificate.pem` below each load path. Both are enrolled into the same keyring, and only differ in how their usage is checked, see below. \ may consist of lowercase letters, digits, `.`, `_` and `-`, other files are ignored. Each file must contain a single PEM-encoded certificate. A file that contains more than one certificate is ignored as a whole. CA certificates should be placed in separate files among the trust anchors instead. Certificates are looked up for two OS identifiers derived from `os-release(5)`: the exact identifier, and the value of `ID=` alone. The exact identifier consists of the values of `ID=`, `VERSION_ID=`, `VARIANT_ID=`, `IMAGE_ID=` and `IMAGE_VERSION=`, separated by `:`. A field that is not set is left empty, and unset fields at the end are omitted. For example, `ID=debian` and `VERSION_ID=13` result in the identifiers `debian:13` and `debian`. If `ID=` is not set, `linux` is used. If one of the other fields contains characters that are not permitted by the VOA specification, only the value of `ID=` is used. If `ID=` itself contains such characters, no certificates are looked up. The `keyring-setup.os` credential may be used to specify the identifiers explicitly, see below. Note that the VOA specification requires different semantics than the usual logic for configuration files, where a file in a directory with higher priority replaces a file with the same name in a directory with lower priority. Instead, X.509 certificates are merged: all files in all load paths are used. A certificate that is found in more than one place is only enrolled once. If two different certificates have the same subject and key identifier, only one of them can be added to a keyring. In this case, certificates found for the exact OS identifier take precedence over the ones found for the value of `ID=` alone, and among those, the certificate from the load path with the highest priority is enrolled. A certificate may be masked by placing a symlink to `/dev/null` with the same file name in any of the load paths, usually in `/etc/voa/` or `/run/voa/`. As required by the VOA specification, a masked certificate is ignored in all load paths, including the ones with a higher priority than the one containing the symlink. Masking is meant as a substitute for revocation: if a certificate is considered compromised, a single symlink ensures that none of its copies is enrolled. Other symlinks are followed as long as they point to a location within the VOA hierarchy, and symlinks to certificate files only if the target has the same file name. To make sure that certificates cannot be placed by unprivileged users, files that are executable or world-writable, and directories that are world-writable, are ignored. Once a directory owned by an unprivileged user has been entered, the lookup does not continue into files or directories owned by anyone else. As required by the VOA specification, the usage of each certificate is checked against its purpose. An artifact verifier is ignored if it has an extended key usage extension that permits neither code signing nor any extended key usage, or a key usage extension that does not permit digital signatures. A trust anchor that is not a CA certificate is enrolled nonetheless, since self-signed certificates that act as their own trust anchor are common, but a message is logged about it. Certificates with invalid extensions are ignored. # Credentials `systemd-keyring-setup` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `keyring-setup.dm-verity.NAME`; `keyring-setup.fs-verity.NAME`; `keyring-setup.bpf.NAME` A PEM-encoded X.509 certificate to enroll into the `.dm-verity`, `.fs-verity` or `.bpf` keyring, respectively. \ may consist of lowercase letters, digits, `.`, `_` and `-`. As suggested by the VOA specification for certificates obtained from elsewhere, the certificate is not enrolled directly, but is first written to `/run/voa/OS/kernel-keyring/CONTEXT/x509/NAME-certificate.pem`, using the first OS identifier. Hence, masking and merging apply to it like to any other file in the hierarchy. Only the certificate itself is written there, so that a private key included in the credential is not made readable to other users. A credential that does not contain exactly one certificate is ignored. `keyring-setup.os` A whitespace-separated list of up to 64 OS identifiers to use instead of the ones derived from `os-release(5)`. This is useful for generic initrds, whose `os-release` does not match the one of the host. If the list is empty, too long or contains an invalid identifier, the credential is ignored and the identifiers derived from `os-release` are used. See `systemd.system-credentials(7)` for details about system credentials. # Options If one or more \ names, such as `.dm-verity`, are specified, only those keyrings are processed. Otherwise, all keyrings listed above are processed. The following options are understood: `--dry-run` Show which certificates would be enrolled into which keyring, and the current state of the keyrings, without changing anything. `--json=` is only supported together with `--dry-run`. # Exit status On success, 0 is returned. This includes the cases where a keyring does not exist, or has been provisioned by an earlier run already. If a certificate or a credential could not be used, for example because it is malformed, or because it is not signed by a key in a keyring that has been sealed already, 65 (`EX_DATAERR`) is returned. `systemd-keyring-setup.service` treats this exit status as success. On other failures, a different non-zero exit status is returned. # Kernel Command Line `dm_verity.keyring_unsealed=`; `bpf.keyring_unsealed=` These options are interpreted by the kernel. If set to `1`, the kernel leaves the `.dm-verity` or `.bpf` keyring unsealed during boot, so that it can be provisioned by `systemd-keyring-setup.service`. Otherwise, the kernel seals the keyring while it is still empty, and no certificates can be enrolled into it. # Security Considerations The enrolled certificates can only be trusted as much as the files they were read from. The intended deployment is to provision the keyrings from the initrd of a signed Unified Kernel Image, see `systemd-stub(7)`. Until a keyring is sealed, any sufficiently privileged process may add arbitrary keys to it. After it has been sealed, privileged processes may still remove keys from it, and add certificates that are signed by a key in the keyring, but they cannot add other keys, or change the restriction or the permissions of the keyring. The keyrings stay sealed until the next reboot. A soft reboot, see `systemd-soft-reboot.service(8)`, does not reset them. If dm-verity is built as a kernel module, unloading and reloading the module discards the `.dm-verity` keyring, including its seal, and creates a new, empty one. If `dm_verity.keyring_unsealed=1` is set, the new keyring may then be provisioned with arbitrary keys again. `systemd-keyring-setup` logs a warning if a keyring belongs to a loadable kernel module. For high-security setups, dm-verity should be built into the kernel. Note that kexec will unseal and empty the keyrings. If enabled and allowed, the caller may use it to load their own certificates into the chain of trust, so this is out of scope for this component and needs to be handled by the system integrators with an appropriate security policy. # See Also `systemd(1)`, `systemd-veritysetup@.service(8)`, `systemd-dissect(1)`, `systemd-stub(7)`, `systemd.system-credentials(7)`, `os-release(5)`, `keyctl(1)` # systemd-keyutil systemd systemd-keyutil 1 systemd-keyutil Perform various operations on private keys and X.509 certificates systemd-keyutil OPTIONS COMMAND # Description `systemd-keyutil` can be used to perform various operations on private keys and X.509 certificates. # Commands `validate` Checks that we can load the private key and certificate specified with `--private-key=` and `--certificate=` respectively. As a side effect, if the private key is loaded from a PIN-protected hardware token, this command can be used to cache the PIN in the kernel keyring. The `$SYSTEMD_ASK_PASSWORD_KEYRING_TIMEOUT_SEC` and `$SYSTEMD_ASK_PASSWORD_KEYRING_TYPE` environment variables can be used to control how long and in which kernel keyring the PIN is cached. `extract-public` This commands prints the public key in PEM format extracted from either the certificate given with `--certificate=` or the private key given with `--private-key=`. `extract-certificate` This command prints the X.509 certificate in PEM format extracted from the certificate given with `--certificate=`. This is useful when loading a certificate from an OpenSSL provider (e.g. a hardware token) and wanting to output a standalone PEM certificate that can be used without the provider. `pkcs7` This command embeds the PKCS#1 signature (RSA) provided with `--signature=` in a PKCS#7 signature using the certificate given with `--certificate=` and writes it to the file specified with `--output=` in PKCS#7 format (p7s). If `--content=` is provided it is included in the p7s, otherwise a "detached" signature is created. The `--hash-algorithm=` option, which defaults to `SHA256`, specifies what hash algorithm was used to generate the signature. # Options The following options are understood: `--private-key=PATH/URI`; `--private-key-source=TYPE[:NAME]`; `--certificate=PATH`; `--certificate-source=TYPE[:NAME]` Set the private key and certificate to use. The `--certificate=` option takes a path to a PEM encoded X.509 certificate or a URI that's passed to the OpenSSL provider configured with `--certificate-source`. The `--certificate-source` takes one of `file` or `provider`, with the latter being followed by a specific provider identifier, separated with a colon, e.g. `provider:pkcs11`. The `--private-key=` option can take a path or a URI that will be passed to the OpenSSL engine or provider, as specified by `--private-key-source=` as a `type:name` tuple, such as `engine:pkcs11`. `--signature=PATH` Input PKCS#1 signature for the `pkcs7` command. `--content=PATH` Input data that corresponds to the PKCS#1 signature for the `pkcs7` command, used for generating inline (i.e. non-"detached") PKCS#7 signatures. `--hash-algorithm=ALGORITHM` Hash algorithm used to generate the PKCS#1 signature for the `pkcs7` command. This should be a valid openssl digest algorithm; use `openssl list -digest-algorithms` to see a list of valid algorithms on your system. Defaults to `SHA256`. `--output=PATH` Output PKCS#7 signature for the `pkcs7` command. # See Also `systemd-sbsign(1)`, `systemd-measure(1)` # systemd-localed.service systemd systemd-localed.service 8 systemd-localed.service systemd-localed Locale bus mechanism `systemd-localed.service` `/usr/lib/systemd/systemd-localed` # Description `systemd-localed.service` is a system service that may be used as mechanism to change the system locale settings, as well as the console key mapping and default X11 key mapping. `systemd-localed` is automatically activated on request and terminates itself when it is unused. The tool `localectl(1)` is a command line client to this service. See `org.freedesktop.locale1(5)` and `org.freedesktop.LogControl1(5)` for a description of the D-Bus API. # See Also `systemd(1)`, `locale.conf(5)`, `vconsole.conf(5)`, `localectl(1)`, `loadkeys(1)`, `org.freedesktop.locale1(5)` # systemd-logind.service systemd systemd-logind.service 8 systemd-logind.service systemd-logind-metrics.socket systemd-logind Login manager `systemd-logind.service` `systemd-logind-metrics.socket` `/usr/lib/systemd/systemd-logind` # Description `systemd-logind` is a system service that manages user logins. It is responsible for: - Keeping track of users and sessions, their processes and their idle state. This is implemented by allocating a systemd slice unit for each user below `user.slice`, and a scope unit below it for each concurrent session of a user. Also, a per-user service manager is started as system service instance of `user@.service` for each logged in user. - Generating and managing session IDs. If auditing is available and an audit session ID is already set for a session, then this ID is reused as the session ID. Otherwise, an independent session counter is used. - Providing [polkit](https://www.freedesktop.org/wiki/Software/polkit)-based access for users for operations such as system shutdown or sleep - Implementing a shutdown/sleep inhibition logic for applications - Handling of power/sleep hardware keys - Multi-seat management - Session switch management - Device access management for users - Automatic spawning of text logins (gettys) on virtual console activation and user runtime directory management - Scheduled shutdown - Sending "wall" messages User sessions are registered with logind via the `pam_systemd(8)` PAM module. See `logind.conf(5)` for information about the configuration of this service. See `sd-login(3)` for information about the basic concepts of logind such as users, sessions and seats. See `org.freedesktop.login1(5)` and `org.freedesktop.LogControl1(5)` for information about the D-Bus APIs `systemd-logind` provides. In addition to the D-Bus interface, `systemd-logind` also provides a Varlink interface `io.systemd.Shutdown` for shutting down or rebooting the system. It supports `PowerOff`, `Reboot`, `Halt`, `KExec`, and `SoftReboot` methods. Each method accepts an optional `skipInhibitors` boolean parameter to bypass active block inhibitors (matching the `SD_LOGIND_SKIP_INHIBITORS` flag of the D-Bus interface). The interface can be queried with `varlinkctl introspect /run/systemd/io.systemd.Login io.systemd.Shutdown`. For more information see [Inhibitor Locks](https://systemd.io/INHIBITOR_LOCKS). If you are interested in writing a display manager that makes use of logind, please have look at [Writing Display Managers](https://systemd.io/WRITING_DISPLAY_MANAGERS). If you are interested in writing a desktop environment that makes use of logind, please have look at [Writing Desktop Environments](https://systemd.io/WRITING_DESKTOP_ENVIRONMENTS). # Metrics `systemd-logind` is a metrics source for `systemd-report(1)` and reports the following metrics: `io.systemd.Login.CurrentSessions` A gauge metric with the number of current sessions. The metric field `class` is set to the session class, see `$XDG_SESSION_CLASS` in `pam_systemd(8)`. `io.systemd.Login.SessionsStarted` A counter metric with the number of sessions started since boot, by session class. Sessions are counted under the class they have been created with. The metric field `class` is set as above. This counter is kept across restarts of the service, but reset on reboot. `io.systemd.Login.SuspendCounter` A counter metric with the number of suspend cycles since boot. The metric field `result` is set to `success` or `fail`. # Signal `SIGHUP` Reloads the service configuration file. # See Also `systemd(1)`, `systemd-user-sessions.service(8)`, `loginctl(1)`, `logind.conf(5)`, `pam_systemd(8)`, `sd-login(3)`, `org.freedesktop.login1(5)` # systemd-loop@.service systemd systemd-loop@.service 8 systemd-loop@.service Attach a loopback block device `systemd-loop@path.service` # Description `systemd-loop@.service` is a template service that may be used to automatically attach a loopback block device at boot (or later). Its instance string may reference an (escaped) file system path pointing to a disk image to attach as loopback block device. Use `systemd-escape(1)`'s `--path` to properly escape a file system path. This unit invokes `systemd-dissect --attach --relax --quiet --loop-ref-auto` on the specified files, see `systemd-dissect(1)` for details. # See Also `systemd(1)`, `systemd-dissect(1)`, `systemd-import-generator(8)` # systemd-machine-id-commit.service systemd systemd-machine-id-commit.service 8 systemd-machine-id-commit.service Commit a transient machine ID to disk `systemd-machine-id-commit.service` # Description `systemd-machine-id-commit.service` is an early boot service responsible for committing transient `/etc/machine-id` files to a writable disk file system. See `machine-id(5)` for more information about machine IDs. This service is started after `local-fs.target` in case `/etc/machine-id` is a mount point of its own (usually from a memory file system such as `tmpfs`) and /etc is writable. The service will invoke `systemd-machine-id-setup --commit`, which writes the current transient machine ID to disk and unmount the `/etc/machine-id` file in a race-free manner to ensure that file is always valid and accessible for other processes. See `systemd-machine-id-setup(1)` for details. The main use case of this service are systems where `/etc/machine-id` is read-only and initially not initialized. In this case, the system manager will generate a transient machine ID file on a memory file system, and mount it over `/etc/machine-id`, during the early boot phase. This service is then invoked in a later boot phase, as soon as `/etc/` has been remounted writable and the ID may thus be committed to disk to make it permanent. # See Also `systemd(1)`, `systemd-machine-id-setup(1)`, `machine-id(5)`, `systemd-firstboot(1)` # systemd-machine-id-setup systemd systemd-machine-id-setup 1 systemd-machine-id-setup Initialize the machine ID in /etc/machine-id systemd-machine-id-setup # Description `systemd-machine-id-setup` may be used by system installer tools to initialize the machine ID stored in `/etc/machine-id` at install time, with a provisioned or randomly generated ID. See `machine-id(5)` for more information about this file. If the tool is invoked without the `--commit` switch, `/etc/machine-id` is initialized with a valid, new machine ID if it is missing or empty. The new machine ID will be acquired in the following fashion: 1. If a valid machine ID is stored in `/run/machine-id`, the machine ID is copied and used to initialize the machine ID in `/etc/machine-id`. This step is skipped if `--root=` is specified or running in a chroot environment. 2. If a valid D-Bus machine ID is already configured for the system, the D-Bus machine ID is copied and used to initialize the machine ID in `/etc/machine-id`. 3. If a valid machine ID is provided through `system.machine_id` credential, the machine ID is copied and used to initialize the machine ID in `/etc/machine-id`. This step is skipped if `--root=` is specified or running in a chroot environment. 4. If run inside a KVM virtual machine and a UUID is configured (via the `-uuid` option), this UUID is used to initialize the machine ID. The caller must ensure that the UUID passed is sufficiently unique and is different for every booted instance of the VM. This step is skipped if `--root=` is specified or running in a chroot environment. 5. Similarly, if run inside a Linux container environment and a UUID is configured for the container, this is used to initialize the machine ID. For details, see the documentation of the [Container Interface](https://systemd.io/CONTAINER_INTERFACE). This step is skipped if `--root=` is specified or running in a chroot environment. 6. Otherwise, a new ID is randomly generated. The `--commit` switch may be used to commit a transient machined ID to disk, making it persistent. For details, see below. Use `systemd-firstboot(1)` to initialize the machine ID on mounted (but not booted) system images. # Options The following options are understood: `--root=path` Takes a directory path as argument. All paths operated on will be prefixed with the given alternate \ path, including the path for `/etc/machine-id` itself. `--image=path` Takes a path to a device node or regular file as argument. This is similar to `--root=` as described above, but operates on a disk image instead of a directory tree. `--commit` Commit a transient machine ID to disk. This command may be used to convert a transient machine ID into a persistent one. A transient machine ID file is one that was bind mounted from a memory file system (usually `tmpfs`) to `/etc/machine-id` during the early phase of the boot process. This may happen because `/etc/` is initially read-only and was missing a valid machine ID file at that point. This command will execute no operation if `/etc/machine-id` is not mounted from a memory file system, or if `/etc/` is read-only. The command will write the current transient machine ID to disk and unmount the `/etc/machine-id` mount point in a race-free manner to ensure that this file is always valid and accessible for other processes. This command is primarily used by the `systemd-machine-id-commit.service(8)` early boot service. `--print` Print the machine ID generated or committed after the operation is complete. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `machine-id(5)`, `systemd-machine-id-commit.service(8)`, `dbus-uuidgen(1)`, `systemd-firstboot(1)` # systemd-machine-tag@.service systemd systemd-machine-tag@.service 8 systemd-machine-tag@.service Add a machine tag to the host `systemd-machine-tag@.service` # Description `systemd-machine-tag@TAG.service` is a service template that adds the machine tag \ (taken from the instance name) to the host's list of machine tags. Whenever an instance of this template is pulled in, the corresponding tag is added; the operation is idempotent, so pulling it in repeatedly has no further effect. The primary use of this template is automatic, hardware-driven tagging: the `SYSTEMD_MACHINE_TAG` udev property, when set on a device, causes the matching instance of this template to be pulled in (via `SYSTEMD_WANTS=`), so that plugging in or detecting a specific device automatically tags the host. See `systemd.device(5)` for details on the `SYSTEMD_WANTS=` mechanism. Machine tags may be inspected and edited with the `tags` verb of `hostnamectl(1)`, and are stored in the `TAGS=` field of `machine-info(5)`. Each tag must be 1…255 characters long and consist only of ASCII alphanumeric characters, `-` and `.`. # See Also `systemd(1)`, `hostnamectl(1)`, `systemd-hostnamed.service(8)`, `machine-info(5)`, `udev(7)` # systemd-machine-tags.service systemd systemd-machine-tags.service 8 systemd-machine-tags.service Apply the machine tags configuration at boot `systemd-machine-tags.service` # Description `systemd-machine-tags.service` is an early boot service that applies the machine tag configuration declared in the `machine-tags.d/` directories, see `machine-tags.d(5)`, by invoking `hostnamectl tags --apply`, see `hostnamectl(1)`. The additions and removals declared there are applied on top of the tags already configured in the `TAGS=` field of `machine-info(5)`. The service is ordered before `sysinit.target`, so that the configured tags are in place before most other units are started and may be used in their `ConditionMachineTag=` settings, see `systemd.unit(5)`. # See Also `systemd(1)`, `machine-tags.d(5)`, `hostnamectl(1)`, `systemd-hostnamed.service(8)`, `systemd-machine-tag@.service(8)`, `machine-info(5)` # systemd-machined.service systemd systemd-machined.service 8 systemd-machined.service systemd-machined Virtual machine and container registration manager `systemd-machined.service` `/usr/lib/systemd/systemd-machined` # Description `systemd-machined` is a system service that keeps track of locally running virtual machines and containers. `systemd-machined` is useful for registering and keeping track of both OS containers (containers that share the host kernel but run a full init system of their own and behave in most regards like a full virtual operating system rather than just one virtualized app) and full virtual machines (virtualized hardware running normal operating systems and possibly different kernels). `systemd-machined` should *not* be used for registering/keeping track of application sandbox containers. A *machine* in the context of `systemd-machined` is supposed to be an abstract term covering both OS containers and full virtual machines, but not application sandboxes. Machines registered with machined are exposed in various ways in the system. For example: - Tools like `ps(1)` will show to which machine a specific process belongs in a column of its own, and so will [gnome-system-monitor](https://help.gnome.org/users/gnome-system-monitor/) or `systemd-cgls(1)`. - systemd's various tools (`systemctl(1)`, `journalctl(1)`, `loginctl(1)`, `hostnamectl(1)`, `timedatectl(1)`, `localectl(1)`, `machinectl(1)`, ...) support the `-M` switch to operate on local containers instead of the host system. - `systemctl list-machines` will show the system state of all local containers, connecting to the container's init system for that. - systemctl's `--recursive` switch has the effect of not only showing the locally running services, but recursively showing the services of all registered containers. - The `machinectl` command provides access to a number of useful operations on registered containers, such as introspecting them, rebooting, shutting them down, and getting a login prompt on them. - The `sd-bus(3)` library exposes the `sd_bus_open_system_machine(3)` call to connect to the system bus of any registered container. - The `nss-mymachines(8)` module makes sure all registered containers can be resolved via normal glibc `gethostbyname(3)` or `getaddrinfo(3)` calls. See `systemd-nspawn(1)` for some examples on how to run containers with OS tools. If you are interested in writing a VM or container manager that makes use of machined, please have look at [Writing Virtual Machine or Container Managers](https://systemd.io/WRITING_VM_AND_CONTAINER_MANAGERS). Also see the [New Control Group Interfaces](https://systemd.io/CONTROL_GROUP_INTERFACE). The daemon provides both a C library interface (which is shared with `systemd-logind.service(8)`) as well as a D-Bus interface and a Varlink interface. The library interface may be used to introspect and watch the state of virtual machines/containers. The bus interface provides the same but in addition may also be used to register or terminate machines. The Varlink interface may be used to register machines with optional extensions, e.g. with an SSH key / address; it can be queried with `varlinkctl introspect /run/systemd/machine/io.systemd.Machine io.systemd.Machine`. For more information please consult `sd-login(3)` and `org.freedesktop.machine1(5)` and `org.freedesktop.LogControl1(5)`. A small companion daemon `systemd-importd.service(8)` is also available, which implements importing, exporting, and downloading of container and VM images. For each container registered with `systemd-machined.service` that employs user namespacing, users/groups are synthesized for the used UIDs/GIDs. These are made available to the system using the [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API), and thus may be resolved with `userdbctl(1)` or the usual glibc NSS calls. # See Also `systemd(1)`, `machinectl(1)`, `systemd-nspawn(1)`, `nss-mymachines(8)`, `systemd.special(7)`, `org.freedesktop.machine1(5)`, `ssh(1)` # systemd-makefs@.service systemd systemd-makefs@.service 8 systemd-makefs@.service systemd-mkswap@.service systemd-growfs@.service systemd-growfs-root.service systemd-makefs systemd-growfs Creating and growing file systems on demand `systemd-makefs@device.service` `systemd-mkswap@device.service` `systemd-growfs@mountpoint.service` `systemd-growfs-root.service` `/usr/lib/systemd/systemd-makefs` \ \ `/usr/lib/systemd/systemd-growfs` \ # Description `systemd-makefs@.service`, `systemd-mkswap@.service`, `systemd-growfs@.service`, and `systemd-growfs-root.service` are used to implement the `x-systemd.makefs` and `x-systemd.growfs` options in `fstab(5)`, see `systemd.mount(5)`. They are instantiated for each device for which the file system or swap structure needs to be initialized, and for each mount point where the file system needs to be grown. These services are started at boot, either right before or right after the mount point or swap device are used. `systemd-makefs` knows very little about specific file systems and swap devices, and after checking that the block device does not already contain a file system or other content, it will execute binaries specific to each filesystem type (`/sbin/mkfs.type` or `/sbin/mkswap`). For certain file system types (currently ext2/ext3/`ext4(5)`, `btrfs(5)`, `xfs(5)`, f2fs, vfat) and for swap devices, it will configure reasonable defaults and set the file system label and UUID based on the device name. `systemd-growfs` knows very little about specific file systems and swap devices, and will instruct the kernel to grow the mounted filesystem to full size of the underlying block device. Nevertheless, it needs to know the `ioctl(2)` number specific to each file system, so only certain types are supported. Currently: `ext4(5)`, `btrfs(5)`, `xfs(5)`, and dm-crypt partitions (see `cryptsetup(8)`). If the creation of a file system or swap device fails, the mount point or swap is failed too. If the growing of a file system fails, a warning is emitted. # See Also `systemd(1)`, `systemd.mount(5)`, `systemd-fstab-generator(8)`, `systemd-repart(8)`, `mkfs.btrfs(8)`, `mkfs.cramfs(8)`, `mkfs.ext4(8)`, `mkfs.fat(8)`, `mkfs.hfsplus(8)`, `mkfs.minix(8)`, `mkfs.ntfs(8)`, `mkfs.xfs(8)` # systemd-measure systemd systemd-measure 1 systemd-measure Pre-calculate and sign expected TPM2 PCR 11 values for booted unified kernel images /usr/lib/systemd/systemd-measure OPTIONS # Description `systemd-measure` is a tool that may be used to pre-calculate and sign the expected TPM2 PCR 11 values that should be seen when a Linux [UAPI.5 Unified Kernel Image (UKI)](https://uapi-group.org/specifications/specs/unified_kernel_image/) based on `systemd-stub(7)` is booted up. It accepts paths to the ELF kernel image file, initrd image file, devicetree file, kernel command line file, `os-release(5)` file, boot splash file, and TPM2 PCR PEM public key file that make up the unified kernel image, and determines the PCR values expected to be in place after booting the image. Calculation starts with a zero-initialized PCR 11, and is executed in a fashion compatible with what `systemd-stub` does at boot. The result may optionally be signed cryptographically, to allow TPM2 policies that can only be unlocked if a certain set of kernels is booted, for which such a PCR signature can be provided. It usually does not make sense to call this tool directly when constructing a UKI. Instead, `ukify(1)` should be used; it will invoke `systemd-measure` and take care of embedding the resulting measurements into the UKI. # Commands The following commands are understood: `status` This is the default command if none is specified. This queries the local system's TPM2 PCR 11 values and displays them. The data is written in a similar format as the `calculate` command below, and may be used to quickly compare expectation with reality. `calculate` Pre-calculate the expected values seen in PCR register 11 after boot-up of a unified kernel image consisting of the components specified with `--linux=`, `--osrel=`, `--cmdline=`, `--initrd=`, `--ucode=`, `--splash=`, `--dtb=`, `--uname=`, `--sbat=`, `--pcrpkey=`, `--profile=`, `--dtbauto=`, `--hwids=`, see below. Only `--linux=` is mandatory. (Alternatively, specify `--current` to use the current values of PCR register 11 instead.) `sign` As with the `calculate` command, pre-calculate the expected value seen in TPM2 PCR register 11 after boot-up of a unified kernel image. Then, cryptographically sign the resulting values with the private/public key pair (RSA) configured via `--private-key=` and `--public-key=`. This will write a JSON object to standard output that contains signatures for all specified PCR banks (see the `--bank=` option below), which may be used to unlock encrypted credentials (see `systemd-creds(1)`) or LUKS volumes (see `systemd-cryptsetup@.service(8)`). This allows binding secrets to a set of kernels for which such PCR 11 signatures can be provided. Note that a TPM2 device must be available for this signing to take place, even though the result is not tied to any TPM2 device or its state. `policy-digest` As with the `sign` command, pre-calculate the expected value seen in TPM2 PCR register 11 after boot-up of a unified kernel image. Then, compute the resulting TPM2 policy and print its digest. This will write a JSON object to standard output that contains the policy digests for all specified PCR banks (see the `--bank=` option below), so that it may be signed offline, for the cases where the private key is not directly accessible. Each policy contains a `pol` field with the approved PolicyPCR digest and a `tbs` field with the data to sign. The two fields have the same value when no policy reference is specified. With `--policyref=`, `tbs` is the concatenation of `pol` and the digest of the policy reference. If `--public-key=` or `--certificate=` are specified, the JSON object will also contain the key fingerprint. # Options The following options are understood: `--linux=PATH`; `--osrel=PATH`; `--cmdline=PATH`; `--initrd=PATH`; `--ucode=PATH`; `--splash=PATH`; `--dtb=PATH`; `--uname=PATH`; `--sbat=PATH`; `--pcrpkey=PATH`; `--profile=PATH`; `--dtbauto=PATH`; `--hwids=PATH` When used with the `calculate` or `sign` verb, configures the files to read the unified kernel image components from. Each option corresponds with the equally named section in the unified kernel PE file. The `--linux=` switch expects the path to the ELF kernel file that the unified PE kernel will wrap. All switches except `--linux=` are optional. Each option may be used at most once. With the exception of `--profile=`, `--dtbauto=` and `--hwids=`, which have been added in version 257. `--current` When used with the `calculate` or `sign` verb, takes the PCR 11 values currently in effect for the system (which should typically reflect the hashes of the currently booted kernel). This can be used in place of `--linux=` and the other switches listed above. `--bank=DIGEST` Controls the PCR banks to pre-calculate the PCR values for – in case `calculate` or `sign` is invoked –, or the banks to show in the `status` output. May be used more then once to specify multiple banks. If not specified, defaults to the four banks `sha1`, `sha256`, `sha384`, `sha512`. Note that some operating systems disable support for SHA1-based signatures, in which case this operation will fail. Please consult your OS' documentation for details on how to override the OS security policy around this. `--private-key=PATH`; `--public-key=PATH`; `--certificate=PATH` These switches take paths to a pair of PEM encoded RSA key files, for use with the `sign` command. Note the difference between the `--pcrpkey=` and `--public-key=` switches. The former selects the data to include in the `.pcrpkey` PE section of the unified kernel image, the latter picks the public key of the key pair used to sign the resulting PCR 11 values. The former is the key that the booted system will likely use to lock disk and credential encryption to, the latter is the key used for unlocking such resources again. Hence, typically the same PEM key should be supplied in both cases. If the `--public-key=` is not specified but `--private-key=` is specified, the public key is automatically derived from the private key. `--certificate=` can be used to specify an X.509 certificate as an alternative to `--public-key=` since v256. `--private-key=PATH/URI`; `--private-key-source=TYPE[:NAME]`; `--certificate=PATH/URI`; `--certificate-source=TYPE[:NAME]` As an alternative to `--public-key=` for the `sign` command, these switches can be used to sign with an hardware token. The private key option can take a path or a URI that will be passed to the OpenSSL engine or provider, as specified by `--private-key-source=` as a type:name tuple, such as engine:pkcs11. The specified OpenSSL signing engine or provider will be used to sign. The `--certificate=` option also takes a path or a URI that will be passed to the OpenSSL provider, as specified by `--certificate-source=` as a `type:name` tuple, such as `provider:pkcs11`. Note that unlike `--private-key-source=` this option only supports providers and not engines. `--tpm2-device=PATH` Controls which TPM2 device to use. Expects a device node path referring to the TPM2 chip (e.g. `/dev/tpmrm0`). Alternatively the special value `auto` may be specified, in order to automatically determine the device node of a suitable TPM2 device (of which there must be exactly one). The special value `list` may be used to enumerate all suitable TPM2 devices currently discovered. `--phase=PHASE` Controls which boot phases to calculate expected PCR 11 values for. This takes a series of colon-separated strings that encode boot "paths" for entering a specific phase of the boot process. Each of the specified strings is measured by the `systemd-pcrphase-initrd.service`, `systemd-pcrphase-sysinit.service`, and `systemd-pcrphase.service(8)` into PCR 11 during different milestones of the boot process. This switch may be specified multiple times to calculate PCR values for multiple boot phases at once. If not used defaults to `enter-initrd`, `enter-initrd:leave-initrd`, `enter-initrd:leave-initrd:sysinit`, `enter-initrd:leave-initrd:sysinit:ready`, i.e. calculates expected PCR values for the boot phase in the initrd, during early boot, during later boot, and during system runtime, but excluding the phases before the initrd or when shutting down. This setting is honoured both by `calculate` and `sign`. When used with the latter it is particularly useful for generating PCR signatures that can only be used for unlocking resources during specific parts of the boot process. For further details about PCR boot phases, see `systemd-pcrphase.service(8)`. `--append=PATH` When generating a PCR JSON signature (via the `sign` command), combine it with a previously generated PCR JSON signature, and output it as one. The specified path must refer to a regular file that contains a valid JSON PCR signature object. The specified file is not modified. It will be read first, then the newly generated signature appended to it, and the resulting object is written to standard output. Use this to generate a single JSON object consisting from signatures made with a number of signing keys (for example, to have one key per boot phase). The command will suppress duplicates: if a specific signature is already included in a JSON signature object it is not added a second time. `--policyref=STRING` When generating a PCR JSON signature or policy digest (via the `sign` or `policy-digest` command), bind the generated signatures to the specified policy reference. The policy reference is an opaque string that is included in the data that is signed, and is also incorporated into the authorization policy of any TPM2 resource that is locked against these signatures (via the `TPM2_PolicyAuthorize` assertion). As a result, a signed policy is only accepted for a resource whose authorization policy was created with the same policy reference. Signed policies created with a different policy reference are rejected, even if they are produced with the same signing key. This can be used together with `--phase=` and `--append=` to bind signatures for different boot phases to different policy references, so that a single signing key can produce signatures that are each scoped to an individual phase or combination of phases. The corresponding policy reference is selected when locking a resource, for example via the `--tpm2-public-key-policyref=` option of `systemd-cryptenroll(1)` and `systemd-repart(8)`. It is recommended to use this option to create a signed policy just for the initrd boot phase by combining it with `--phase=enter-initrd` for secrets that should only be recoverable from the initrd, particularly FDE keys. # Examples
Generate a unified kernel image, and calculate the expected TPM PCR 11 value
$ ukify build \ --linux=vmlinux \ --initrd=initrd.cpio \ --os-release=@os-release.txt \ --cmdline=@cmdline.txt \ --splash=splash.bmp \ --devicetree=devicetree.dtb \ --measure \ --output=vmlinux.efi 11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7 11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651 11:sha384=1cf67dff4757e61e5...7f49ad720be02fd07263e1f93061243aec599d1ee4b4 11:sha512=8e79acd3ddbbc8282...0c3e8ec0c714821032038f525f744960bcd082d937da `ukify(1)` internally calls `systemd-measure`. The output with hashes is from `systemd-measure`.
Generate a private/public key pair, a unified kernel image, and a TPM PCR 11 signature for it, and embed the signature and the public key in the image
$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private-key.pem ..+.+++++++++......+.........+......+.......+....+.....+.+...+.......... $ openssl rsa -pubout -in tpm2-pcr-private-key.pem -out tpm2-pcr-public-key.pem $ systemd-measure sign \ --linux=vmlinux \ --osrel=os-release.txt \ --cmdline=cmdline.txt \ --initrd=initrd.cpio \ --splash=splash.bmp \ --dtb=devicetree.dtb \ --pcrpkey=tpm2-pcr-public-key.pem \ --bank=sha1 \ --bank=sha256 \ --private-key=tpm2-pcr-private-key.pem \ --public-key=tpm2-pcr-public-key.pem >tpm2-pcr-signature.json $ ukify build \ --linux=vmlinux \ --initrd=initrd.cpio \ --os-release=@os-release.txt \ --cmdline=@cmdline.txt \ --splash=splash.bmp \ --devicetree=devicetree.dtb \ --pcr-private-key=tpm2-pcr-private-key.pem \ --pcr-public-key=tpm2-pcr-public-key.pem \ --pcr-banks=sha1,sha256 \ --output=vmlinuz.efi Later on, enroll the signed PCR policy on a LUKS volume: # systemd-cryptenroll --tpm2-device=auto \ --tpm2-public-key=tpm2-pcr-public-key.pem \ --tpm2-signature=tpm2-pcr-signature.json \ /dev/sda5 And then unlock the device with the signature: # systemd-cryptsetup attach \ volume5 /dev/sda5 - \ tpm2-device=auto,tpm2-signature=/path/to/tpm2-pcr-signature.json Note that when the generated unified kernel image `vmlinux.efi` is booted, the signature and public key files will be placed at locations `systemd-cryptenroll` and `systemd-cryptsetup` will look for anyway, and thus these paths do not actually need to be specified.
Introduce a second public key, signing the same kernel PCR measurements, but only for the initrd boot phase
This example extends the previous one, but we now introduce a second signing key that is only used to sign PCR policies restricted to the initrd boot phase. This can be used to lock down root volumes in a way that they can only be unlocked before the transition to the host system. Thus we have two classes of secrets or credentials: one that can be unlocked during the entire runtime, and the other that can only be used in the initrd. $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private-key.pem .+........+.+........+.......+...+...+........+....+......+..+.......... $ openssl rsa -pubout -in tpm2-pcr-private-key.pem -out tpm2-pcr-public-key.pem $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-initrd-private-key.pem ..+.......++........+........+......+........+....+.....+.+..+.......... $ openssl rsa -pubout -in tpm2-pcr-initrd-private-key.pem -out tpm2-pcr-initrd-public-key.pem $ ukify build \ --linux=vmlinux-1.2.3 \ --initrd=initrd.cpio \ --os-release=@os-release.txt \ --cmdline=@cmdline.txt \ --splash=splash.bmp \ --devicetree=devicetree.dtb \ --pcr-private-key=tpm2-pcr-private-key.pem \ --pcr-public-key=tpm2-pcr-public-key.pem \ --phases=enter-initrd,enter-initrd:leave-initrd,enter-initrd:leave-initrd:sysinit,enter-initrd:leave-initrd:sysinit:ready \ --pcr-banks=sha1,sha256 \ --pcr-private-key=tpm2-pcr-initrd-private-key.pem \ --pcr-public-key=tpm2-pcr-initrd-public-key.pem \ --phases=enter-initrd \ --uname=1.2.3 \ --output=vmlinux-1.2.3.efi + /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \ --osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \ --splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \ --private-key=tpm2-pcr-private-key.pem --public-key=tpm2-pcr-public-key.pem \ --phase=enter-initrd --phase=enter-initrd:leave-initrd \ --phase=enter-initrd:leave-initrd:sysinit \ --phase=enter-initrd:leave-initrd:sysinit:ready + /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \ --osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \ --splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \ --private-key=tpm2-pcr-initrd-private-key.pem \ --public-key=tpm2-pcr-initrd-public-key.pem \ --phase=enter-initrd Wrote unsigned vmlinux-1.2.3.efi `ukify` prints out both invocations of `systemd-measure` as informative output (the lines starting with `+`); this allows us to see how `systemd-measure` is called. It then merges the output of both invocations into the `.pcrsig` section. `systemd-measure` may also do this merge itself using the `--append=` option. Note that in this example the `.pcrpkey` PE section contains the key specified by the first `--pcr-private-key=` option, covering all boot phases. The `.pcrpkey` section is used in the default policies of `systemd-cryptenroll` and `systemd-creds`. To use the stricter policy bound to `tpm2-pcr-initrd-public-key.pem`, specify `--tpm2-public-key=` on the command line of those tools.
Using a policy reference to add a signature only for the initrd boot phase
This example is an alternative approach to the previous one, but rather than introducing a second signing key, we re-use the same signing key to sign a PCR policy that is restricted to the initrd boot phase and use the `--policyref=` option so that secrets or credentials can be bound only to this more restricted policy, using this reference. $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private-key.pem .+........+.+........+.......+...+...+........+....+......+..+.......... $ openssl rsa -pubout -in tpm2-pcr-private-key.pem -out tpm2-pcr-public-key.pem $ ukify build \ --linux=vmlinux-1.2.3 \ --initrd=initrd.cpio \ --os-release=@os-release.txt \ --cmdline=@cmdline.txt \ --splash=splash.bmp \ --devicetree=devicetree.dtb \ --pcrpkey=tpm2-pcr-public-key.pem \ --pcr-private-key=tpm2-pcr-private-key.pem \ --phases=enter-initrd,enter-initrd:leave-initrd,enter-initrd:leave-initrd:sysinit,enter-initrd:leave-initrd:sysinit:ready \ --policyref= \ --pcr-banks=sha1,sha256 \ --pcr-private-key=tpm2-pcr-private-key.pem \ --phases=enter-initrd \ --policyref=initrd \ --uname=1.2.3 \ --output=vmlinux-1.2.3.efi + /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \ --osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \ --splash=splash.bmp --pcrpkey=tpm2-pcr-public-key.pem --initrd=initrd.cpio \ --bank=sha1 --bank=sha256 --private-key=tpm2-pcr-private-key.pem \ --phase=enter-initrd --phase=enter-initrd:leave-initrd \ --phase=enter-initrd:leave-initrd:sysinit \ --phase=enter-initrd:leave-initrd:sysinit:ready --policyref= + /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \ --osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \ --splash=splash.bmp --pcrpkey=tpm2-pcr-public-key.pem --initrd=initrd.cpio \ --bank=sha1 --bank=sha256 --private-key=tpm2-pcr-initrd-private-key.pem \ --phase=enter-initrd --policyref=initrd Wrote unsigned vmlinux-1.2.3.efi `ukify` prints out both invocations of `systemd-measure` as informative output (the lines starting with `+`); this allows us to see how `systemd-measure` is called. It then merges the output of both invocations into the `.pcrsig` section. `systemd-measure` may also do this merge itself using the `--append=` option. Note that in this example, the `.pcrsig` PE section contains signed policies covering all boot phases bound to the same empty policy reference, and a more restricted signed policy for just the initrd boot phase bound to the `initrd` policy reference. To use the stricter policy, supply `--tpm2-policyref=initrd` to `systemd-cryptenroll`. To use the more relaxed policy that includes all boot phases, omit the `--tpm2-policyref=` of `systemd-cryptenroll`. Note that policies for `systemd-creds` cannot currently bind to signed policies with a non-empty policy reference.
# Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-stub(7)`, `ukify(1)`, `systemd-creds(1)`, `systemd-cryptsetup@.service(8)`, `systemd-pcrphase.service(8)` # systemd-modules-load.service systemd systemd-modules-load.service 8 systemd-modules-load.service systemd-modules-load Load kernel modules at boot `systemd-modules-load.service` `/usr/lib/systemd/systemd-modules-load` # Description `systemd-modules-load.service` is an early boot service that loads kernel modules. It reads static configuration from files in `/usr/` and `/etc/`, but also runtime configuration from `/run/` and the kernel command line (see below). See `modules-load.d(5)` for information about the configuration format of this service and paths where configuration files can be created. # Kernel Command Line `systemd-modules-load.service` understands the following kernel command line parameters: `modules_load=`; `rd.modules_load=` Takes a comma-separated list of kernel modules to statically load during early boot. The option prefixed with `rd.` is read in the initrd only. # See Also `systemd(1)`, `modules-load.d(5)` # systemd-mount systemd systemd-mount 1 systemd-mount systemd-umount Establish and destroy transient mount or auto-mount points systemd-mount OPTIONS WHAT WHERE systemd-mount OPTIONS --tmpfs NAME WHERE systemd-mount OPTIONS --list systemd-mount OPTIONS --umount WHAT\|WHERE # Description `systemd-mount` may be used to create and start a transient `.mount` or `.automount` unit of the file system \ on the mount point \. In many ways, `systemd-mount` is similar to the lower-level `mount(8)` command, however instead of executing the mount operation directly and immediately, `systemd-mount` schedules it through the service manager job queue, so that it may pull in further dependencies (such as parent mounts, or a file system checker to execute a priori), and may make use of the auto-mounting logic. The command takes either one or two arguments. If only one argument is specified it should refer to a block device or regular file containing a file system (e.g. `/dev/sdb1` or `/path/to/disk.img`). The block device or image file is then probed for a file system label and other metadata, and is mounted to a directory below `/run/media/system/` whose name is generated from the file system label. In this mode the block device or image file must exist at the time of invocation of the command, so that it may be probed. If the device is found to be a removable block device (e.g. a USB stick), an automount point is created instead of a regular mount point (i.e. the `--automount=` option is implied, see below). If the option `--tmpfs` is specified, then the argument is interpreted as the path where the new temporary file system shall be mounted. If two arguments are specified, the first indicates the mount source (the \) and the second indicates the path to mount it on (the \). In this mode no probing of the source is attempted, and a backing device node does not have to exist. However, if this mode is combined with `--discover`, device node probing for additional metadata is enabled, and – much like in the single-argument case discussed above – the specified device has to exist at the time of invocation of the command. Use the `--list` command to show a terse table of all local, known block devices with file systems that may be mounted with this command. `systemd-umount` can be used to unmount a mount or automount point. It is the same as `systemd-mount` `--umount`. # Options The following options are understood: `--no-block` Do not synchronously wait for the requested operation to finish. If this is not specified, the job will be verified, enqueued and `systemd-mount` will wait until the mount or automount unit's start-up is completed. By passing this argument, it is only verified and enqueued. `-l`; `--full` Do not ellipsize the output when `--list` is specified. `--quiet`; `-q` Suppresses additional informational output while running. `--discover` Enable probing of the mount source. This switch is implied if a single argument is specified on the command line. If passed, additional metadata is read from the device to enhance the unit to create. For example, a descriptive string for the transient units is generated from the file system label and device model. Moreover, if a removable block device (e.g. USB stick) is detected an automount unit instead of a regular mount unit is created, with a short idle timeout, in order to ensure the file-system is placed in a clean state quickly after each access. `--type=`; `-t` Specifies the file system type to mount (e.g. `vfat` or `ext4`). If omitted or set to `auto`, the file system type is determined automatically. `--options=`; `-o` Additional mount options for the mount point. `--owner=USER` Let the specified user \ own the mounted file system. This is done by appending `uid=` and `gid=` options to the list of mount options. Only certain file systems support this option. `--fsck=` Takes a boolean argument, defaults to on. Controls whether to run a file system check immediately before the mount operation. In the automount case (see `--automount=` below) the check will be run the moment the first access to the device is made, which might slightly delay the access. `--description=` Provide a description for the mount or automount unit. See `Description=` in `systemd.unit(5)`. `--property=`; `-p` Sets a unit property for the mount unit that is created. This takes an assignment in the same format as `systemctl(1)`'s `set-property` command. `--automount=` Takes a boolean argument. Controls whether to create an automount point or a regular mount point. If true an automount point is created that is backed by the actual file system at the time of first access. If false a plain mount point is created that is backed by the actual file system immediately. Automount points have the benefit that the file system stays unmounted and hence in clean state until it is first accessed. In automount mode the `--timeout-idle-sec=` switch (see below) may be used to ensure the mount point is unmounted automatically after the last access and an idle period passed. If this switch is not specified, it defaults to false. If not specified and `--discover` is used (or only a single argument passed, which implies `--discover`, see above), and the file system block device is detected to be removable, it is set to true, in order to increase the chance that the file system is in a fully clean state if the device is unplugged abruptly. `-A` Equivalent to `--automount=yes`. `--timeout-idle-sec=` Takes a time value that controls the idle timeout in automount mode. If set to `infinity` (the default) no automatic unmounts are done. Otherwise, the file system backing the automount point is detached after the last access and the idle timeout passed. See `systemd.time(7)` for details on the time syntax supported. This option has no effect if only a regular mount is established, and automounting is not used. Note that if `--discover` is used (or only a single argument passed, which implies `--discover`, see above), and the file system block device is detected to be removable, `--timeout-idle-sec=1s` is implied. `--automount-property=` Similar to `--property=`, but applies additional properties to the automount unit created, instead of the mount unit. `--bind-device` Controls whether the generated mount/automount unit shall be bound to the backing device's lifetime. This setting is especially useful in automount mode. If set, the units will be stopped automatically when the backing device vanishes. By default, the automount unit stays around, and subsequent accesses will block until backing device is replugged. This option has no effect in case of non-device mounts, such as network or virtual file system mounts. If `--discover` is used (or only a single argument passed, which implies `--discover`, see above), and the file system block device is detected to be removable, this option is implied. Note that mount units by default gain a `Requires=` dependency on the backing device. This behavior can be controlled via `x-systemd.device-bound=` mount option, see `systemd.mount(5)` for details. In particular, `x-systemd.device-bound=no` takes precedence over this option, which suppresses device dependencies both in the generated mount units and what's implied by service manager. `--list` Instead of establishing a mount or automount point, print a terse list of block devices containing file systems that may be mounted with `systemd-mount`, along with useful metadata such as labels, etc. `-u`; `--umount` Stop the mount and automount units corresponding to the specified mount points \ or the devices \. `systemd-mount` with this option or `systemd-umount` can take multiple arguments which can be mount points, devices, `/etc/fstab` style node names, or backing files corresponding to loop devices, like `systemd-mount --umount /path/to/umount /dev/sda1 UUID=xxxxxx-xxxx LABEL=xxxxx /path/to/disk.img`. Note that when `-H` or `-M` is specified, only absolute paths to mount points are supported. `-G`; `--collect` Unload the transient unit after it completed, even if it failed. Normally, without this option, all mount units that mount and failed are kept in memory until the user explicitly resets their failure state with `systemctl reset-failed` or an equivalent command. On the other hand, units that stopped successfully are unloaded immediately. If this option is turned on the "garbage collection" of units is more aggressive, and unloads units regardless of whether they exited successfully or failed. This option is a shortcut for `--property=CollectMode=inactive-or-failed`, see the explanation for `CollectMode=` in `systemd.unit(5)` for further information. `-T`; `--tmpfs` Create and mount a new `tmpfs` file system on \, with an optional \ that defaults to `tmpfs`. The file system is mounted with the top-level directory mode determined by the `umask(2)` setting of the caller, i.e. `rwxrwxrwx` masked by the umask of the caller. This matches what `mkdir(1)` does, but is different from the kernel default of `rwxrwxrwxt`, i.e. a world-writable directory with the sticky bit set. `--canonicalize=` Controls whether the specified path shall be canonicalized on the client side before requesting the operation or not. Takes a boolean parameter, defaults to true. Note that for non-local operation (i.e. when `--machine=` or --`--host=` are used) canonicalization is implicitly turned off. Canonicalization of path entails resolving of symlinks, `..` path elements and `LABEL=`/`UUID=` style device node expansion. If canonicalization is disabled and the path contains a symlink element, `..`, or a `LABEL=`/`UUID=`/… expansion the operation will fail. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # The udev Database If `--discover` is used, `systemd-mount` honors a couple of additional udev properties of block devices: `SYSTEMD_MOUNT_OPTIONS=` The mount options to use, if `--options=` is not used. `SYSTEMD_MOUNT_WHERE=` The file system path to place the mount point at, instead of the automatically generated one. # Example Use a udev rule like the following to automatically mount all USB storage plugged in: ACTION=="add", SUBSYSTEMS=="usb", SUBSYSTEM=="block", ENV{ID_FS_USAGE}=="filesystem", \ RUN{program}+="/usr/bin/systemd-mount --no-block --automount=yes --collect $devnode" # See Also `systemd(1)`, `mount(8)`, `systemctl(1)`, `systemd.unit(5)`, `systemd.mount(5)`, `systemd.automount(5)`, `systemd-run(1)` # systemd-mountfsd.service systemd systemd-mountfsd.service 8 systemd-mountfsd.service systemd-mountfsd Disk Image File System Mount Service `systemd-mountfsd.service` `/usr/lib/systemd/systemd-mountfsd` # Description `systemd-mountfsd` is a system service that dissects disk images, and returns mount file descriptors for the file systems contained therein to clients, via a Varlink IPC API. The disk images provided must contain a raw file system image or must follow the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification/). Before mounting any file systems authenticity of the disk image is established in one or a combination of the following ways: 1. If the disk image is located in a regular file in one of the directories `/var/lib/machines/`, `/var/lib/portables/`, `/var/lib/extensions/`, `/var/lib/confexts/` or their counterparts in the `/etc/`, `/run/`, `/usr/lib/` it is assumed to be trusted. 2. If the disk image contains a Verity enabled disk image, along with a signature partition with a key in the kernel keyring or in `/etc/verity.d/*.crt` (and related directories) the disk image is considered trusted. Note that the GPT partition table of the disk image is parsed by the kernel to discover its contents and `systemd-mountfsd` assumes that the GPT parser is robust against malformed input and applies no security policies or checks around it. This service provides one [Varlink](https://varlink.org/) service: `io.systemd.MountFileSystem` which accepts a file descriptor to a regular file or block device, and returns a number of file descriptors referring to an `fsmount()` file descriptor the client may then attach to a path of their choice. The returned mounts are automatically allowlisted in the per-user-namespace allowlist maintained by `systemd-nsresourced.service(8)`. The file systems are automatically `fsck(8)`'ed before mounting. # See Also `systemd(1)`, `systemd-nsresourced.service(8)` # systemd-mstack systemd systemd-mstack 1 systemd-mstack mount.mstack Mstack Discoverable Disk Images (DDIs) systemd-mstack OPTIONS IMAGE systemd-mstack OPTIONS --mount IMAGE PATH systemd-mstack OPTIONS --umount PATH # Description `systemd-mstack` is a tool for introspecting and interacting with `.mstack/` mount stack directories, as described in `systemd.mstack(7)`. It supports three different operations: 1. Show general mount stack information, including all described `overlayfs` layers and bind mounts. 2. Mount a mount stack to a local directory. 3. Unmount a mount stack from a local directory. The `systemd-mstack` command may be invoked as `mount.mstack` in which case it implements the `mount(8)` "external helper" interface. This ensures mount stack directories compatible with `systemd-mstack` can be mounted directly by `mount` and `fstab(5)`. For details see below. # Commands If neither of the command switches listed below are passed the specified mount stack is opened and general information about it is shown, including a list of all defined layers. `--mount`; `-m` Mount the specified mount stack to the specified directory. To unmount a mount stack directory mounted like this use the `--umount` operation. Note that this functionality is also available in `mount(8)` via a command such as `mount -t mstack mystack.mstack targetdir/`, as well as in `fstab(5)`. For details, see below. `-M` This is a shortcut for `--mount --mkdir`. `--umount`; `-u` Unmount a mount stack from the specified directory. This command expects one argument: a directory where mount stack was mounted. All mounted mounts will be recursively unmounted `-U` This is a shortcut for `--umount --rmdir`. # Options The following options are understood: `--read-only`; `-r` Operate in read-only mode. By default, `--mount` will establish writable mount points. If this option is specified they are established in read-only mode instead. `--mkdir` If combined with `--mount` the directory to mount the mount stack to is created if it is missing. Note that the directory is not automatically removed when the mount stack is unmounted again. `--rmdir` If combined with `--umount` the specified directory where the mount stack is mounted is removed after unmounting it. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Invocation as `/sbin/mount.mstack` The `systemd-mstack` executable may be symlinked to `/sbin/mount.mstack`. If invoked through that it implements `mount(8)`'s "external helper" interface for the (pseudo) file system type `mstack`. This means conformant mount stack directories may be mounted directly via # mount -t mstack mystack.mstack targetdir/ in a fashion mostly equivalent to: # systemd-mstack --mount mystack.mstack targetdir/ Note that since a single mount stack may contain multiple mount points it should later be unmounted with `umount -R targetdir/`, for recursive operation. This functionality is particularly useful to mount mount stacks automatically at boot via simple `/etc/fstab` entries. For example: /path/to/mystack.nspawn /images/mystack/ mstack defaults 0 0 When invoked this way the mount options `ro`, `rw` map to the corresponding options listed above (i.e. `--read-only`). # See Also `systemd(1)`, `systemd.mstack(7)`, `systemd-nspawn(1)`, `systemd.exec(5)`, `mount(8)`, `umount(8)` # systemd-mute-console systemd systemd-mute-console 1 systemd-mute-console systemd-mute-console@.service systemd-mute-console.socket Temporarily mute kernel log output and service manager status output to the system console systemd-mute-console OPTIONS `systemd-mute-console@.service` `systemd-mute-console.socket` # Description The `systemd-mute-console` tool and service may be used to temporarily mute the log output of the kernel as well as the status output of the service manager to the system console. It may be used by tools running on the console to ensure their terminal output is not interrupted by unrelated messages. The tool can be invoked directly in which case it will mute the two outputs and then issue an `sd_notify(3)` `READY=1` notification once that is completed. On `SIGINT` or `SIGTERM` output is unmuted again. Alternatively it can be invoked via Varlink IPC. # Options The following options are understood: `--kernel=bool`; `--pid1=bool` Individually controls which output to mute. If true is specified the respective output is muted, if false the output is left as is. Defaults to true. # See Also `systemd(1)`, `systemd-firstboot(1)` # systemd-network-generator.service systemd systemd-network-generator.service 8 systemd-network-generator.service systemd-network-generator Generate network configuration from the kernel command line `systemd-network-generator.service` `/usr/lib/systemd/systemd-network-generator` # Description `systemd-network-generator.service` is a system service that translates `ip=` and related settings on the kernel command line (see below) into `systemd.network(5)`, `systemd.netdev(5)`, and `systemd.link(5)` configuration files understood by `systemd-networkd.service(8)` and `systemd-udevd.service(8)`. Files are generated in `/run/systemd/network/`. Note: despite the name, this generator executes as a normal systemd service and is *not* an implementation of the `systemd.generator(7)` concept. # Kernel command line options This tool understands the following options: `ip=`; `nameserver=`; `rd.route=`; `rd.peerdns=` Translated into `systemd.network(5)` files. In addition to the parameters `dracut.cmdline(7)` defines the `ip=` option accepts the special value `link-local`. If selected, the network interfaces will be configured for link-local addressing (IPv4LL, IPv6LL) only, DHCP or IPv6RA will not be enabled. `ifname=`; `net.ifname_policy=` Translated into `systemd.link(5)` files. `vlan=`; `bond=`; `bridge=`; `bootdev=` Translated into `systemd.netdev(5)` files. `BOOTIF=`; `rd.bootif=` When `BOOTIF` is specified in the interface field of `ip=`, it is treated as a special placeholder rather than a real interface name. Then, in combination with the MAC address provided by `BOOTIF=`, this is translated into a `systemd.network(5)` file which matches on the provided MAC address. When `rd.bootif=0` is passed, this functionality is disabled, and the `BOOTIF=` option is ignored. See `dracut.cmdline(7)` for details on the usage of these options. See `dracut.cmdline(7)` and `systemd-udevd.service(8)` for option syntax and details. # Credentials `systemd-network-generator` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `network.conf.*`; `network.link.*`; `network.netdev.*`; `network.network.*` 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: a passed credential `network.link.50-foobar` will be copied into a configuration 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 to supply them via separate credentials directly to `systemd-networkd.service(8)`. Note that by default the `systemd-networkd.service(8)` service is set up to inherit the these credentials from the service manager. # See Also `systemd(1)`, `systemd-networkd.service(8)`, `dracut(8)` # systemd-networkd-wait-online.service systemd systemd-networkd-wait-online.service 8 systemd-networkd-wait-online.service systemd-networkd-wait-online@.service systemd-networkd-wait-online Wait for network to come online `systemd-networkd-wait-online.service` `systemd-networkd-wait-online@.service` `/usr/lib/systemd/systemd-networkd-wait-online` # Description `systemd-networkd-wait-online` is a oneshot system service (see `systemd.service(5)`), that waits for the network to be configured. By default, it will wait for all links it is aware of and which are managed by `systemd-networkd.service(8)` to be fully configured or failed, and for at least one link to be online. Here, online means that the link's operational state is equal or higher than `degraded`. The threshold can be configured by `--operational-state=` option. The service `systemd-networkd-wait-online.service` invokes `systemd-networkd-wait-online` without any options. Thus, it waits for all managed interfaces to be configured or failed, and for at least one to be online. The service `systemd-networkd-wait-online@.service` takes an interface name, and invokes `systemd-networkd-wait-online` with `-i` and the specified interface name. Thus, wait for the specified interface to be configured and online. For example, `systemd-networkd-wait-online@eth0.service` waits for `eth0` to be configured by `systemd-networkd` and online. # Options The following options are understood: `-i` \\[:\\[:\\]\]; `--interface=INTERFACE:MIN_OPERSTATE:MAX_OPERSTATE` Network interface to wait for before deciding if the system is online. This is useful when a system has several interfaces which will be configured, but a particular one is necessary to access some network resources. When used, all other interfaces are ignored. This option may be used more than once to wait for multiple network interfaces. When this option is specified multiple times, then `systemd-networkd-wait-online` waits for all specified interfaces to be online. Optionally, required minimum and maximum operational states can be specified after a colon `:`. Please see `networkctl(1)` for possible operational states. If the operational state is not specified here, then the value from `RequiredForOnline=` in the corresponding `.network` file is used if present, and `degraded` otherwise. `--ignore=INTERFACE` Network interfaces to be ignored when deciding if the system is online. By default, only the loopback interface is ignored. This option may be used more than once to ignore multiple network interfaces. `-o` \\[:\\]; `--operational-state=MIN_OPERSTATE:MAX_OPERSTATE` Takes a minimum operational state and an optional maximum operational state. Please see `networkctl(1)` for possible operational states. If set, the specified value overrides `RequiredForOnline=` settings in `.network` files. But this does not override operational states specified in `--interface=` option. `-4`; `--ipv4` Waiting for an IPv4 address of each network interface to be configured. If this option is specified with `--any`, then `systemd-networkd-wait-online` exits with success when at least one interface becomes online and has an IPv4 address. If the required minimum operational state is below `routable`, then each link (or at least one link with `--any`) must have an IPv4 link-local or routable address. If the required minimum operational state is `routable`, then each link must have an IPv4 routable address. If neither `--ipv4` nor `--ipv6` is specified, then the value from `RequiredFamilyForOnline=` in the corresponding `.network` file is used if present. `-6`; `--ipv6` Waiting for an IPv6 address of each network interface to be configured. If this option is specified with `--any`, then `systemd-networkd-wait-online` exits with success when at least one interface becomes online and has an IPv6 address. If the required minimum operational state is below `routable`, then each link (or at least one link with `--any`) must have an IPv6 link-local or routable address. If the required minimum operational state is `routable`, then each link must have an IPv6 routable address. If neither `--ipv4` nor `--ipv6` is specified, then the value from `RequiredFamilyForOnline=` in the corresponding `.network` file is used if present. `--dns` Waiting for DNS servers to be accessible on each interface. If this option is specified with `--any`, then `systemd-networkd-wait-online` exits with success when at least one interface becomes online and has an accessible DNS server. If a link has the property `DefaultRoute=yes` (either because the `DNSDefaultRoute=` network property is explicitly configured, or because the link does not have any "routing-only" domains), or if the search domain "." is configured, then wait for link-specific DNS servers to be accessible. Otherwise, allow global DNS servers to satisfy the condition. `--any` Even if several interfaces are in configuring state, `systemd-networkd-wait-online` exits with success when at least one interface becomes online. When this option is specified with `--interface=`, then `systemd-networkd-wait-online` waits for one of the specified interfaces to be online. This option is useful when some interfaces may not have carrier on boot. `--timeout=SECS` Fail the service if the network is not online by the time the timeout elapses. A timeout of 0 disables the timeout. Defaults to 120 seconds. `-q`; `--quiet` Suppress log messages. # See Also `systemd(1)`, `systemd.service(5)`, `systemd-networkd.service(8)`, `networkctl(1)` # systemd-networkd.service systemd systemd-networkd.service 8 systemd-networkd.service systemd-networkd Network manager `systemd-networkd.service` `/usr/lib/systemd/systemd-networkd` # Description `systemd-networkd` is a system service that manages networks. It detects and configures network devices as they appear, as well as creating virtual network devices. Certain low-level settings of physical network devices (e.g. device names and altnames) as well as the creation of SR-IOV virtual functions on physical network interfaces may be managed by `systemd-udevd(8)` according to the contents of `systemd.link(5)` files. `systemd-networkd` will create "virtual" network devices (e.g. bridges and tunnels) based on the configuration in `systemd.netdev(5)` files, respecting the \[Match\] sections in those files. `systemd-networkd` will manage network addresses and routes for any link for which it finds a `.network` file with an appropriate \[Match\] section, see `systemd.network(5)`. For those links, it will flush existing network addresses and routes when bringing up the device (except when directed not to). Any links not matched by one of the `.network` files will be ignored. It is also possible to explicitly tell `systemd-networkd` to ignore a link by using the `Unmanaged=yes` option, see `systemd.network(5)`. When `systemd-networkd` exits, it generally leaves existing network devices and configuration intact. This makes it possible to transition from the initrd and to restart the service without breaking connectivity. This also means that when configuration is updated and `systemd-networkd` is restarted, netdev interfaces for which configuration was removed will not be dropped, and may need to be cleaned up manually. `systemd-networkd` may be introspected and controlled at runtime using `networkctl(1)`. See `org.freedesktop.network1(5)` and `org.freedesktop.LogControl1(5)` for a description of the D-Bus API. # Configuration Files The configuration files are read from the files located in the system network directory `/usr/lib/systemd/network`, the volatile runtime network directory `/run/systemd/network` and the local administration network directory `/etc/systemd/network`. Networks are configured in `.network` files, see `systemd.network(5)`, and virtual network devices are configured in `.netdev` files, see `systemd.netdev(5)`. # See Also `networkctl(1)`, `systemd(1)`, `systemd.link(5)`, `systemd.network(5)`, `systemd.netdev(5)`, `systemd-networkd-wait-online.service(8)`, `systemd-network-generator.service(8)`, `org.freedesktop.network1(5)` # systemd-notify systemd systemd-notify 1 systemd-notify Notify service manager about start-up completion and other daemon status changes systemd-notify OPTIONS VARIABLE=VALUE systemd-notify --exec OPTIONS VARIABLE=VALUE ; -- CMDLINE systemd-notify --fork OPTIONS -- CMDLINE # Description `systemd-notify` may be called by service scripts to notify the invoking service manager about status changes. It can be used to send arbitrary information, encoded in an environment-block-like list of strings. Most importantly, it can be used for start-up completion notification. This is mostly just a wrapper around `sd_notify()` and makes this functionality available to shell scripts. For details see `sd_notify(3)`. The command line may carry a list of environment variables to send as part of the status update. Note that systemd will refuse reception of status updates from this command unless `NotifyAccess=` is appropriately set for the service unit this command is called from. See `systemd.service(5)` for details. Note that `sd_notify()` notifications may be attributed to units correctly only if either the sending process is still around at the time the service manager processes the message, or if the sending process is explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked off the process, i.e. on all processes that match `NotifyAccess=``main` or `NotifyAccess=``exec`. Conversely, if an auxiliary process of the unit sends an `sd_notify()` message and immediately exits, the service manager might not be able to properly attribute the message to the unit, and thus will ignore it, even if `NotifyAccess=``all` is set for it. To address this `systemd-notify` will wait until the notification message has been processed by the service manager. When `--no-block` is used, this synchronization for reception of notifications is disabled, and hence the aforementioned race may occur if the invoking process is not the service manager or spawned by the service manager. `systemd-notify` will first attempt to invoke `sd_notify()` pretending to have the PID of the parent process of `systemd-notify` (i.e. the invoking process). This will only succeed when invoked with sufficient privileges. On failure, it will then fall back to invoking it under its own PID. This behaviour is useful in order that when the tool is invoked from a shell script the shell process — and not the `systemd-notify` process — appears as sender of the message, which in turn is helpful if the shell process is the main process of a service, due to the limitations of `NotifyAccess=``all`. Use the `--pid=` switch to tweak this behaviour. # Options The following options are understood: `--ready` Inform the invoking service manager about service start-up or configuration reload completion. This is equivalent to `systemd-notify READY=1`. For details about the semantics of this option see `sd_notify(3)`. `--reloading` Inform the invoking service manager about the beginning of a configuration reload cycle. This is equivalent to `systemd-notify RELOADING=1` (but implicitly also sets a `MONOTONIC_USEC=` field as required for `Type=notify-reload` services, see `systemd.service(5)` for details). For details about the semantics of this option see `sd_notify(3)`. `--stopping` Inform the invoking service manager about the beginning of the shutdown phase of the service. This is equivalent to `systemd-notify STOPPING=1`. For details about the semantics of this option see `sd_notify(3)`. `--pid=` Inform the service manager about the main PID of the service. Takes a PID as argument. If the argument is specified as `auto` or omitted, the PID of the process that invoked `systemd-notify` is used, except if that's the service manager. If the argument is specified as `self`, the PID of the `systemd-notify` command itself is used, and if `parent` is specified the calling process' PID is used — even if it is the service manager. `--pid=auto` is equivalent to `systemd-notify --pid=$PID`. For details about the semantics of this option see `sd_notify(3)`. `systemd-notify` will first attempt to invoke `sd_notify()` pretending to have the PID specified with `--pid=`. This will only succeed when invoked with sufficient privileges. On failure, it will then fall back to invoking it under its own PID. Effectively, this means that a privileged invocation of `systemd-notify --pid=` may circumvent `NotifyAccess=main` or `NotifyAccess=exec` restrictions enforced for a service. If this switch is used in an unprivileged `systemd-notify` invocation from a process that shall become the new main process of a service — and which is not the process forked off by the service manager (or the current main process) —, then it is essential to set `NotifyAccess=all` in the service unit file, or otherwise the notification will be ignored for security reasons. See `systemd.service(5)` for details. `--uid=USER` Set the user ID to send the notification from. Takes a UNIX user name or numeric UID. When specified the notification message will be sent with the specified UID as sender, in place of the user the command was invoked as. This option requires sufficient privileges in order to be able manipulate the user identity of the process. `--status=` Send a free-form human-readable status string for the daemon to the service manager. This option takes the status string as argument. This is equivalent to `systemd-notify STATUS=…`. For details about the semantics of this option see `sd_notify(3)`. This information is shown in `systemctl(1)`'s `status` output, among other places. `--booted` Returns 0 if the system was booted up with systemd, non-zero otherwise. If this option is passed, no message is sent. This option is hence unrelated to the other options. For details about the semantics of this option, see `sd_booted(3)`. An alternate way to check for this state is to call `systemctl(1)` with the `is-system-running` command. It will output `offline` if the system was not booted with systemd, though the return value has a different meaning. `--no-block` Do not synchronously wait for the requested operation to finish. Use of this option is only recommended when `systemd-notify` is spawned by the service manager, or when the invoking process is directly spawned by the service manager and has enough privileges to allow `systemd-notify` to send the notification on its behalf. Sending notifications with this option set is prone to race conditions in all other cases. `--exec` If specified `systemd-notify` will execute another command line after it completed its operation, replacing its own process. If used, the list of assignments to include in the message sent must be followed by a `;` character (as separate argument), followed by the command line to execute. This permits "chaining" of commands, i.e. issuing one operation, followed immediately by another, without changing PIDs. Note that many shells interpret `;` as their own separator for command lines, hence when `systemd-notify` is invoked from a shell the semicolon must usually be escaped as `\;`. `--fd=` Send a file descriptor along with the notification message. This is useful when invoked in services that have the `FileDescriptorStoreMax=` setting enabled, see `systemd.service(5)` for details. The specified file descriptor must be passed to `systemd-notify` when invoked. This option may be used multiple times to pass multiple file descriptors in a single notification message. To use this functionality from a `bash(1)` shell, use an expression like the following: systemd-notify --fd=4 --fd=5 4
Start-up Notification and Status Updates
A simple shell daemon that sends start-up notifications after having set up its communication channel. During runtime it sends further status updates to the init system: #!/bin/sh mkfifo /tmp/waldo systemd-notify --ready --status="Waiting for data…" while : ; do read -r a < /tmp/waldo systemd-notify --status="Processing $a" # Do something with $a … systemd-notify --status="Waiting for data…" done # See Also `systemd(1)`, `systemctl(1)`, `systemd.unit(5)`, `systemd.service(5)`, `sd_notify(3)`, `sd_booted(3)` # systemd-nsresourced.service systemd systemd-nsresourced.service 8 systemd-nsresourced.service systemd-nsresourced User Namespace Resource Delegation Service `systemd-nsresourced.service` `/usr/lib/systemd/systemd-nsresourced` # Description `systemd-nsresourced` is a system service that permits transient delegation of a UID/GID range to a user namespace (see `user_namespaces(7)`) allocated by a client, via a Varlink IPC API. Unprivileged clients may allocate a user namespace, and then request a UID/GID range to be assigned to it via this service. The user namespace may then be used to run containers and other sandboxes, and/or apply it to an id-mapped mount. Allocations of UIDs/GIDs this way are transient: when a user namespace goes away, its UID/GID range is returned to the pool of available ranges. In order to ensure that clients cannot gain persistency in their transient UID/GID range a BPF-LSM based policy is enforced that refuses to create inodes — or change ownership of them — that would end up owned by a transient UID/GID on a file system outliving the user namespace the range was assigned to. Writes to file systems the user namespace allocated itself are hence permitted, as those are torn down together with it, and so are writes through id-mapped mounts that translate the transient range into something else before it reaches the disk. As a stacking file system such as `overlayfs` writes to a separate upper layer that would not be covered by the checks on the overlay mount itself, mounting a writable `overlayfs` instance is refused for these user namespaces unless its upper layer, too, is torn down together with the user namespace, or is an id-mapped mount that translates the transient range away before it reaches the disk. The policy does not cover `cgroupfs`, whose superblock is shared system-wide and cannot be id-mapped: the only part of it a transient range owns is the cgroup subtree delegated to the user namespace (see below), which is torn down together with the user namespace, hence user namespaces may freely create cgroups below it. `systemd-nsresourced` automatically ensures that any registered UID ranges show up in the system's NSS database via the [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API). Currently, only UID/GID ranges consisting of either exactly 1 or exactly 65536 UIDs/GIDs can be registered with this service. Moreover, UIDs and GIDs are always allocated together, and symmetrically. The allocation API supports *delegated ranges*: additional UID/GID ranges that are mapped 1:1 into the user namespace rather than being translated to a target UID/GID. These delegated ranges enable nested user namespace scenarios where a container needs to create child user namespaces with their own transient UID ranges. Normally, the kernel restricts which UIDs can be mapped into a user namespace to those that are also mapped in the parent. Delegated ranges solve this by pre-allocating additional ranges that are visible inside the user namespace and can be used by nested `AllocateUserRange()` calls. Up to 16 delegated ranges can be requested per user namespace, each of size 65536. The ranges are allocated from the container UID ranges as per [Users, Groups, UIDs and GIDs on systemd Systems](https://systemd.io/UIDS-GIDS). The allocation API also supports *identity mappings*: instead of allocating a transient UID/GID range, the user namespace can be configured to map the caller's UID/GID to root (UID 0) inside the namespace, or to itself. Identity mappings can be combined with delegated ranges to enter a privileged user namespace from which the container can be set up after which the container can run in one of the delegated ranges. Identity mapped users are not subject to BPF-LSM write restrictions unlike the transient ranges. Additionally, the allocation API supports mapping the *foreign UID range* into the user namespace. When this option is enabled, the foreign UID range is mapped 1:1 into the user namespace, allowing processes inside to access and manipulate files owned by the foreign UID range. The service provides API calls to delegate mounts (referenced via their mount file descriptors as per Linux `fsmount()` API), to pass ownership of a cgroup subtree to the user namespace and to delegate a virtual Ethernet device pair to the user namespace. When used in combination this is sufficient to implement fully unprivileged container environments, as implemented by `systemd-nspawn(1)`, fully unprivileged `RootImage=` (see `systemd.exec(5)`) or fully unprivileged disk image tools such as `systemd-dissect(1)`. This service provides one [Varlink](https://varlink.org/) service: `io.systemd.NamespaceResource` allows registering user namespaces, and assign mounts, cgroups and network interfaces to it. Note that combining usage of `systemd-nsresourced` and systems based on `/etc/subuid` and `/etc/subgid` might result in undefined behavior if UID or GID ranges defined in those files overlap with the UID or GID ranges used by nsresourced (the foreign UID range). # See Also `systemd(1)`, `systemd-mountfsd.service(8)`, `systemd-nspawn(1)`, `systemd.exec(5)`, `systemd-dissect(1)`, `user_namespaces(7)` # systemd-oomd.service systemd systemd-oomd.service 8 systemd-oomd.service systemd-oomd A userspace out-of-memory (OOM) killer `systemd-oomd.service` `/usr/lib/systemd/systemd-oomd` # Description `systemd-oomd` is a system service that uses cgroups-v2 and pressure stall information (PSI) to monitor and take corrective action before an OOM occurs in the kernel space. You can enable monitoring and actions on units by setting `ManagedOOMSwap=` and `ManagedOOMMemoryPressure=` in the unit configuration, see `systemd.resource-control(5)`. `systemd-oomd` retrieves information about such units from `systemd(1)` when it starts and watches for subsequent changes. Cgroups of units with `ManagedOOMSwap=` or `ManagedOOMMemoryPressure=` set to `kill` will be monitored. `systemd-oomd` periodically polls PSI statistics for the system and those cgroups to decide when to take action. If the configured limits are exceeded, `systemd-oomd` will select a cgroup to terminate, and send `SIGKILL` to all processes in it. Note that only descendant cgroups are eligible candidates for killing; the unit with its property set to `kill` is not a candidate (unless one of its ancestors set their property to `kill`). Also only leaf cgroups and cgroups with `memory.oom.group` set to `1` are eligible candidates; see `OOMPolicy=` in `systemd.service(5)`. `oomctl(1)` can be used to list monitored cgroups and pressure information. See `oomd.conf(5)` for more information about the configuration of this service. See `org.freedesktop.oom1(5)` and `org.freedesktop.LogControl1(5)` for a description of the D-Bus API. # System requirements and configuration The system must be running systemd with a full unified cgroup hierarchy for the expected cgroups-v2 features. Furthermore, memory accounting must be turned on for all units monitored by `systemd-oomd`. The easiest way to turn on memory accounting is by ensuring the value for `DefaultMemoryAccounting=` is set to `true` in `systemd-system.conf(5)`. The kernel must be compiled with PSI support. This is available in Linux 4.20 and above. It is highly recommended for the system to have swap enabled for `systemd-oomd` to function optimally. With swap enabled, the system spends enough time swapping pages to let `systemd-oomd` react. Without swap, the system enters a livelocked state much more quickly and may prevent `systemd-oomd` from responding in a reasonable amount of time. See ["In defence of swap: common misconceptions"](https://chrisdown.name/2018/01/02/in-defence-of-swap.html) for more details on swap. Any swap-based actions on systems without swap will be ignored. While `systemd-oomd` can perform pressure-based actions on such a system, the pressure increases will be more abrupt and may require more tuning to get the desired thresholds and behavior. Be aware that if you intend to enable monitoring and actions on `user.slice`, `user-$UID.slice`, or their ancestor cgroups, it is highly recommended that your programs be managed by the systemd user manager to prevent running too many processes under the same session scope (and thus avoid a situation where memory intensive tasks trigger `systemd-oomd` to kill everything under the cgroup). If you're using a desktop environment like GNOME or KDE, it already spawns many session components with the systemd user manager. # Usage Recommendations `ManagedOOMSwap=` works with the system-wide swap values, so setting it on the root slice `-.slice`, and allowing all descendant cgroups to be eligible candidates may make the most sense. `ManagedOOMMemoryPressure=` tends to work better on the cgroups below the root slice. For units which tend to have processes that are less latency sensitive (e.g. `system.slice`), a higher limit like the default of 60% may be acceptable, as those processes can usually ride out slowdowns caused by lack of memory without serious consequences. However, something like `user@$UID.service` may prefer a much lower value like 40%. # Options `-n`; `--dry-run` Do a dry run of `systemd-oomd`: when a kill is triggered, print it to the log instead of killing the cgroup. The short option `-n` was added in version 262. # Signals `SIGHUP` Upon reception of the `SIGHUP` process signal `systemd-oomd` will reload its configuration file. # See Also `systemd(1)`, `systemd-system.conf(5)`, `systemd.resource-control(5)`, `oomd.conf(5)`, `oomctl(1)`, `org.freedesktop.oom1(5)` # systemd-path systemd systemd-path 1 systemd-path List and query system and user paths systemd-path OPTIONS NAME # Description `systemd-path` may be used to query system and user paths. The tool makes many of the paths described in `file-hierarchy(7)` available for querying. When invoked without arguments, a list of known paths and their current values is shown. When at least one argument is passed, the path with this name is queried and its value shown. The variables whose name begins with `search-` do not refer to individual paths, but instead to a list of colon-separated search paths, in their order of precedence. Note that paths which depend on environment variables are computed with `systemd-path`'s invoked environment, and not the system or user manager's environment. As such, the output of `systemd-path` may not reflect the behavior of manager processes. # Options The following options are understood: `--suffix=` Printed paths are suffixed by the specified string. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `file-hierarchy(7)` # systemd-pcrlock systemd systemd-pcrlock 8 systemd-pcrlock systemd-pcrlock-file-system.service systemd-pcrlock-firmware-code.service systemd-pcrlock-firmware-config.service systemd-pcrlock-machine-id.service systemd-pcrlock-make-policy.service systemd-pcrlock-secureboot-authority.service systemd-pcrlock-secureboot-policy.service Analyze and predict TPM2 PCR states and generate an access policy from the prediction /usr/lib/systemd/systemd-pcrlock OPTIONS # Description `systemd-pcrlock` is a tool that may be used to analyze and predict TPM2 PCR measurements, and generate TPM2 access policies from the prediction which it stores in a TPM2 NV index (i.e. in the TPM2 non-volatile memory). This may then be used to restrict access to TPM2 objects (such as disk encryption keys) to system boot-ups in which only specific, trusted components are used. `systemd-pcrlock` uses as input for its analysis and prediction: - The UEFI firmware TPM2 event log (i.e. `/sys/kernel/security/tpm0/binary_bios_measurements`) of the current boot. - The userspace TPM2 event log (i.e. `/run/log/systemd/tpm2-measure.log`) of the current boot. - The current PCR state of the TPM2 chip. - Boot component definition files (`*.pcrlock` and `*.pcrlock.d/*.pcrlock`, see `systemd.pcrlock(5)`) that each define expected measurements for one component of the boot process, permitting alternative variants for each. (Variants may be used to bless multiple kernel versions or boot loader versions at the same time.) It uses these inputs to generate a combined event log, validating it against the PCR states. It then attempts to recognize event log records and matches them against the defined components. For each PCR where this can be done comprehensively (i.e. where all listed records and all defined components have been matched) this may then be used to predict future PCR measurements, taking the alternative variants defined for each component into account. This prediction may then be converted into a TPM2 access policy (consisting of TPM2 `PolicyPCR` and `PolicyOR` items), which is then stored in an NV index in the TPM2. This may be used to then lock secrets (such as disk encryption keys) to these policies (via a TPM2 `PolicyAuthorizeNV` policy). Use tools such as `systemd-cryptenroll(1)` or `systemd-repart(8)` to bind disk encryption to such a `systemd-pcrlock` TPM2 policy. Specifically, see the `--tpm2-pcrlock=` switches of these tools. The access policy logic requires a TPM2 device that implements the `PolicyAuthorizeNV` command, i.e. implements TPM 2.0 version 1.38 or newer. # Commands The following commands are understood: `log` This reads the combined TPM2 event log, validates it, matches it against the current PCR values, and outputs both in tabular form. Combine with `--json=` to generate output in JSON format. `cel` This reads the combined TPM2 event log and writes it to STDOUT in [TCG Canonical Event Log Format (CEL-JSON)](https://trustedcomputinggroup.org/resource/canonical-event-log-format/). `list-components` Shows a list of component definitions and their variants, i.e. the `*.pcrlock` files discovered in `/var/lib/pcrlock.d/`, `/usr/lib/pcrlock.d/`, and the other supported directories. See `systemd.pcrlock(5)` for details on these files and the full list of directories searched. `predict` Predicts the PCR state on future boots. This will analyze the TPM2 event log as described above, recognize components, and then generate all possible resulting PCR values for all combinations of component variants. Note that no prediction is made for PCRs whose value does not match the event log records, for which unrecognized measurements are discovered or for which components are defined that cannot be found in the event log. This is a safety measure to ensure that any generated access policy can be fulfilled correctly on current and future boots. `make-policy` This predicts the PCR state for future boots, much like the `predict` command above. It then uses this data to generate a TPM2 access policy which it stores in a TPM2 NV index. The prediction and information about the used TPM2 and its NV index are written to `/var/lib/systemd/pcrlock.json`. The NV index is allocated on first invocation, and updated on subsequent invocations. The NV index contents may be changed (and thus the policy stored in it updated) by providing an access PIN. This PIN is normally generated automatically and stored in encrypted form (with an access policy binding it to the NV index itself) in the aforementioned JSON policy file. This PIN may be chosen by the user, via the `--recovery-pin=` switch. If specified it may be used as alternative path of access to update the policy. If the new prediction matches the old this command terminates quickly and executes no further operation. (Unless `--force` is specified, see below.) Starting with v256, a copy of the `/var/lib/systemd/pcrlock.json` policy file is encoded in a credential (see `systemd-creds(1)` for details) and written to the EFI System Partition or XBOOTLDR partition, in the `/loader/credentials/` subdirectory. There it is picked up at boot by `systemd-stub(7)` and passed to the invoked initrd, where it can be used to unlock the root file system (which typically contains `/var/`, which is where the primary copy of the policy is located, which hence cannot be used to unlock the root file system). The credential file is named after the boot entry token of the installation (see `bootctl(1)`), which is configurable via the `--entry-token=` switch, see below. `remove-policy` Removes a previously generated policy. Deletes the `/var/lib/systemd/pcrlock.json` file, and deallocates the NV index. `is-supported` Checks if the local TPM2 supports all functionality for `systemd-pcrlock` to work correctly. This does similar tests as `systemd-analyze has-tpm2`, but also checks for supported of the TPM2 operations requires by `systemd-pcrlock`. Outputs one of `no`, `partial` (in case some parts of TPM2 support are available in hardware, firmware, OS, but not complete), `obsolete` (if TPM2 support is available in hardware, firmware and OS, but the operations required for `systemd-pcrlock` are missing), `yes`. Returns an exit status of zero if full support is available, otherwise non-zero. If combined with `--quiet`, suppresses the output of the string. Currently, this checks for support for the PolicAuthorizeNV TPM2 command, as well as for support of the SHA-256 hash algorithm. `lock-firmware-code`; `unlock-firmware-code` Generates/removes `.pcrlock` files based on the TPM2 event log of the current boot covering all records for PCRs 0 ("platform-code") and 2 ("external-code"). This operation allows locking the boot process to the current version of the firmware of the system and its extension cards. This operation should only be used if the system vendor does not provide suitable pcrlock data ahead of time. Note that this data only matches the current version of the firmware. If a firmware update is applied this data will be out-of-date and any access policy generated from it will no longer pass. It is thus recommended to invoke `unlock-firmware-code` before doing a firmware update, followed by `make-policy` to refresh the policy. `systemd-pcrlock lock-firmware-code` is invoked automatically at boot via the `systemd-pcrlock-firmware-code.service` unit, if enabled. This ensures that an access policy managed by `systemd-pcrlock` is automatically locked to the new firmware version whenever the policy has been relaxed temporarily, in order to cover for firmware updates, as described above. The files are only generated from the event log if the event log matches the current TPM2 PCR state. This writes/removes the files `/var/lib/pcrlock.d/250-firmware-code-early.pcrlock.d/generated.pcrlock` and `/var/lib/pcrlock.d/550-firmware-code-late.pcrlock.d/generated.pcrlock`. `lock-firmware-config`; `unlock-firmware-config` This is similar to `lock-firmware-code`/`unlock-firmware-code` but locks down the firmware configuration, i.e. PCRs 1 ("platform-config") and 3 ("external-config"). This functionality should be used with care as in most scenarios a minor firmware configuration change should not invalidate access policies to TPM2 objects. Also note that some systems measure unstable and unpredictable information (e.g. current CPU voltages, temperatures, as part of SMBIOS data) to these PCRs, which means this form of lockdown cannot be used reliably on such systems. Use this functionality only if the system and hardware is well known and does not suffer by these limitations, for example in virtualized environments. Use `unlock-firmware-config` before making firmware configuration changes. If the `systemd-pcrlock-firmware-config.service` unit is enabled it will automatically generate a pcrlock file from the new measurements. This writes/removes the files `/var/lib/pcrlock.d/250-firmware-config-early.pcrlock.d/generated.pcrlock` and `/var/lib/pcrlock.d/550-firmware-config-late.pcrlock.d/generated.pcrlock`. `lock-secureboot-policy`; `unlock-secureboot-policy` Generates/removes a `.pcrlock` file based on the SecureBoot policy currently enforced. This looks at the SecureBoot, PK, KEK, db, dbx, dbt, dbr EFI variables and predicts their measurements to PCR 7 ("secure-boot-policy") on the next boot. Use `unlock-secureboot-policy` before applying SecureBoot policy updates. If the `systemd-pcrlock-secureboot-policy.service` unit is enabled it will automatically generate a pcrlock file from the policy discovered. This writes/removes the file `/var/lib/pcrlock.d/230-secureboot-policy.pcrlock.d/generated.pcrlock`. `lock-secureboot-authority`; `unlock-secureboot-authority` Generates/removes a `.pcrlock` file based on the SecureBoot authorities used to validate the boot path. SecureBoot authorities are the specific SecureBoot database entries that where used to validate the UEFI PE binaries executed at boot. This looks at the event log of the current boot, and uses relevant measurements on PCR 7 ("secure-boot-policy"). This writes/removes the file `/var/lib/pcrlock.d/620-secureboot-authority.pcrlock.d/generated.pcrlock`. `lock-gpt` \[\\]; `unlock-gpt` Generates/removes a `.pcrlock` file based on the GPT partition table of the specified disk. If no disk is specified automatically determines the block device backing the root file system. This locks the state of the disk partitioning of the booted medium, which firmware measures to PCR 5 ("boot-loader-config"). This writes/removes the file `/var/lib/pcrlock.d/600-gpt.pcrlock.d/generated.pcrlock`. `lock-pe` \[\\]; `unlock-pe` Generates/removes a `.pcrlock` file based on the specified PE binary. This is useful for predicting measurements the firmware makes to PCR 4 ("boot-loader-code") if the specified binary is part of the UEFI boot process. Use this on boot loader binaries and suchlike. Use `lock-uki` (see below) for PE binaries that are unified kernel images (UKIs). Expects a path to the PE binary as argument. If not specified, reads the binary from STDIN instead. The pcrlock file to write must be specified via the `--pcrlock=` switch. `lock-uki` \[\\]; `unlock-uki` Generates/removes a `.pcrlock` file based on the specified UKI PE binary. This is useful for predicting measurements the firmware makes to PCR 4 ("boot-loader-code"), and `systemd-stub(7)` makes to PCR 11 ("kernel-boot"), if the specified UKI is booted. This is a superset of `lock-pe`. Expects a path to the UKI PE binary as argument. If not specified, reads the binary from STDIN instead. The pcrlock file to write must be specified via the `--pcrlock=` switch. `lock-machine-id`; `unlock-machine-id` Generates/removes a `.pcrlock` file based on `/etc/machine-id`. This is useful for predicting measurements `systemd-pcrmachine.service(8)` makes to PCR 15 ("system-identity"). This writes/removes the file `/var/lib/pcrlock.d/820-machine-id.pcrlock`. `lock-file-system` \[\\]; `unlock-file-system` \[\\] Generates/removes a `.pcrlock` file based on file system identity. This is useful for predicting measurements `systemd-pcrfs@.service(8)` makes to PCR 15 ("system-identity") for the root and `/var/` file systems. This writes/removes the files `/var/lib/pcrlock.d/830-root-file-system.pcrlock` and `/var/lib/pcrlock.d/840-file-system-path.pcrlock`. `lock-kernel-cmdline` \[\\]; `unlock-kernel-cmdline` Generates/removes a `.pcrlock` file based on `/proc/cmdline` (or the specified file if given). This is useful for predicting measurements the Linux kernel makes to PCR 9 ("kernel-initrd"). This writes/removes the file `/var/lib/pcrlock.d/710-kernel-cmdline.pcrlock/generated.pcrlock`. `lock-kernel-initrd` \; `unlock-kernel-initrd` Generates/removes a `.pcrlock` file based on a kernel initrd cpio archive. This is useful for predicting measurements the Linux kernel makes to PCR 9 ("kernel-initrd"). Do not use for `systemd-stub(7)` UKIs, as the initrd is combined dynamically from various sources and hence does not take a single input, like this command. This writes/removes the file `/var/lib/pcrlock.d/720-kernel-initrd.pcrlock/generated.pcrlock`. `lock-raw` \[\\]; `unlock-raw` Generates/removes a `.pcrlock` file based on raw binary data. The data is either read from the specified file or from STDIN (if none is specified). This requires that `--pcrs=` is specified. The generated .pcrlock file is written to the file specified via `--pcrlock=` or to STDOUT (if none is specified). # Options The following options are understood: `--full` Show full hash value instead of abbreviating to 7 characters. `--raw-description` When displaying the TPM2 event log do not attempt to decode the records to provide a friendly event log description string. Instead, show the binary payload data in escaped form. `--pcr=` Specifies the PCR number to use. May be specified more than once to select multiple PCRs. This is used by `lock-raw` and `lock-pe` to select the PCR to lock against. If used with `predict` and `make-policy` this will override which PCRs to include in the prediction and policy. If unspecified this defaults to PCRs 0-5, 7, 11, 13-15. Note that these commands will not include any PCRs in the prediction/policy (even if specified explicitly) if there are measurements in the event log that do not match the current PCR value, or there are unrecognized measurements in the event log, or components define measurements not seen in the event log. `--nv-index=` Specifies the NV index to store the policy in. Honoured by `make-policy`. If not specified, the command will automatically pick a free NV index. `--components=` Takes a path to read `*.pcrlock` and `*.pcrlock.d/*.pcrlock` files from. May be used more than once to specify multiple such directories. If not specified, defaults to `/etc/pcrlock.d/`, `/run/pcrlock.d/`, `/var/lib/pcrlock.d/`, `/usr/local/lib/pcrlock.d/`, `/usr/lib/pcrlock.d/`. `--location=` Takes either a string or a colon-separated pair of strings. Configures up to which point in the sorted list of defined components to analyze/predict PCRs to. Typically, the `systemd-pcrlock` tool is invoked from a fully booted system after boot-up and before shutdown. This means various components that are defined for shutdown have not been measured yet, and should not be searched for. This option allows one to restrict which components are considered for analysis (taking only components before some point into account, ignoring components after them). The expected string is ordered against the filenames of the components defined. Any components with a lexicographically later name are ignored. This logic applies to the `log`, `predict`, and `make-policy` verbs. If a colon-separated pair of strings are specified then they select which phases of the boot to include in the prediction/policy. The first string defines where the first prediction shall be made, and the second string defines where the last prediction shall be made. All such predictions are then combined into one set. If used with `list-components` the selected location range will be highlighted in the component list. Defaults to `760-:940-`, which means the policies generated by default will basically cover the whole runtime of the OS userspace, from the initrd (as `760-` closely follows `750-enter-initrd.pcrlock`) until (and including) the main runtime of the system (as `940-` is closely followed by `950-shutdown.pcrlock`). See `systemd.pcrlock(5)` for a full list of well-known components, that illustrate where this range is placed by default. `--recovery-pin=` Takes one of `hide`, `show` or `query`. Defaults to `hide`. Honoured by `make-policy`. If `query`, will query the user for a PIN to unlock the TPM2 NV index with. If no policy was created before, this PIN is used to protect the newly allocated NV index. If a policy has been created before, the PIN is used to unlock write access to the NV index. If either `hide` or `show` is used, a PIN is automatically generated, and — only in case of `show` — displayed on screen. Regardless if user supplied or automatically generated, it is stored in encrypted form in the policy metadata file. The recovery PIN may be used to regain write access to an NV index in case the access policy became out of date. `--pcrlock=` Takes a file system path as argument. If specified, configures where to write the generated pcrlock data to. Honoured by the various `lock-*` commands. If not specified, a default path is generally used, as documented above. `--policy=` Takes a file system path as argument. If specified, configures where to write pcrlock policy metadata to. If not specified, defaults to `/var/lib/systemd/pcrlock.json`. `--force` If specified with `make-policy`, the predicted policy will be written to the NV index even if it is detected to be the same as the previously stored one. `--entry-token=` Sets the boot entry token to use for the file name for the pcrlock policy credential in the EFI System Partition or XBOOTLDR partition. See the `bootctl(1)` option of the same regarding expected values. This switch has an effect on the `make-policy` command only. `--quiet` If specified suppresses output when invoked for `is-supported`. `--strict=` Takes a boolean. Defaults to false. Honoured by `make-policy` and `predict`. If true all specified PCRs must be included in the policy otherwise the command returns failure. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd.pcrlock(5)`, `systemd-cryptenroll(1)`, `systemd-cryptsetup@.service(8)`, `systemd-repart(8)`, `systemd-pcrmachine.service(8)`, `systemd-creds(1)`, `systemd-stub(7)`, `bootctl(1)` # systemd-pcrphase.service systemd systemd-pcrphase.service 8 systemd-pcrphase.service systemd-pcrphase-sysinit.service systemd-pcrphase-initrd.service systemd-pcrmachine.service systemd-pcrosseparator.service systemd-pcrproduct.service systemd-pcrlogin@.service systemd-pcrfs-root.service systemd-pcrfs@.service systemd-pcrnvdone.service systemd-pcrphase-factory-reset.service systemd-pcrphase-storage-target-mode.service systemd-pcrextend Measure boot phases, machine ID, product UUID, user records and file system identity into TPM PCRs and NvPCRs `systemd-pcrphase.service` `systemd-pcrphase-sysinit.service` `systemd-pcrphase-initrd.service` `systemd-pcrmachine.service` `systemd-pcrosseparator.service` `systemd-pcrproduct.service` `systemd-pcrlogin@.service` `systemd-pcrfs-root.service` `systemd-pcrfs@.service` `systemd-pcrnvdone.service` `systemd-pcrphase-factory-reset.service` `systemd-pcrphase-storage-target-mode.service` `/usr/lib/systemd/systemd-pcrextend` \ `/usr/lib/systemd/systemd-pcrextend` `--file-system=PATH` `/usr/lib/systemd/systemd-pcrextend` `--machine-id` `/usr/lib/systemd/systemd-pcrextend` `--product-id` `/usr/lib/systemd/systemd-pcrextend` `--login=UID|USER` # Description `systemd-pcrphase.service`, `systemd-pcrphase-sysinit.service`, and `systemd-pcrphase-initrd.service` are system services that measure specific strings into TPM2 PCR 11 during boot at various milestones of the boot process. `systemd-pcrmachine.service` is a system service that measures the machine ID (see `machine-id(5)`) into PCR 15. `systemd-pcrosseparator.service` is a system service that measures the word `os-separator` into PCRs 0-7, 9, 12-14. This acts as additional separator measurement separating pre-boot (i.e. firmware + bootloader) measurements from OS measurements, and in particular "seals" off the firmware PCRs. `systemd-pcrproduct.service` is a system service that measures the firmware product UUID (as provided by one of SMBIOS, Devicetree, …) into a NvPCR named `hardware`. `systemd-pcrlogin@.service` is a template service that measures the (reduced, canonical JSON) user record of the user indicated by its instance identifier (a UID) into a NvPCR named `login`. It is started by `systemd-logind.service(8)` on the user's first login of the current boot, much like `user-runtime-dir@.service(5)`. Unlike the latter it is intentionally never stopped again: it is a `Type=oneshot` service with `RemainAfterExit=yes` in `system.slice`, so each user is measured exactly once per boot regardless of how often they log in and out (NvPCR extensions form a hash chain, so measuring the same record twice would otherwise make the NvPCR value unpredictable). The resulting `login` NvPCR (together with the `/run/log/systemd/tpm2-measure.log` event log) thus provides a TPM-backed, append-only record of which user identities were activated during the current boot. `systemd-pcrnvdone.service` is a system service that measures a separator event into PCR 9 once all NvPCRs have completed initialization. `systemd-pcrfs-root.service` and `systemd-pcrfs@.service` are services that measure file system identity information (i.e. mount point, file system type, label and UUID, partition label and UUID) into PCR 15. `systemd-pcrfs-root.service` does so for the root file system, `systemd-pcrfs@.service` is a template unit that measures the file system indicated by its instance identifier instead. These services require `systemd-stub(7)` to be used in a unified kernel image (UKI). They execute no operation when the stub has not been used to invoke the kernel. The stub will measure the invoked kernel and associated vendor resources into PCR 11 before handing control to it; once userspace is invoked these services then will extend TPM2 PCR 11 with certain literal strings indicating phases of the boot process. During a regular boot process PCR 11 is extended with the following strings: 1. `enter-initrd` — early when the initrd initializes, before activating system extension images for the initrd. It acts as a barrier between the time where the kernel initializes and where the initrd starts operating and enables system extension images, i.e. code shipped outside of the UKI. (This extension happens when the `systemd-pcrphase-initrd.service(8)` service is started.) 2. `leave-initrd` — when the initrd is about to transition into the host file system. It acts as barrier between initrd code and host OS code. (This extension happens when the `systemd-pcrphase-sysinit.service(8)` service is stopped.) 3. `sysinit` — when basic system initialization is complete (which includes local file systems having been mounted), and the system begins starting regular system services. (This extension happens when the `systemd-pcrphase-sysinit.service(8)` service is started.) 4. `ready` — during later boot-up, after remote file systems have been activated (i.e. after `remote-fs.target`), but before users are permitted to log in (i.e. before `systemd-user-sessions.service`). It acts as barrier between the time where unprivileged regular users are still prohibited to log in and where they are allowed to log in. (This extension happens when the `systemd-pcrphase-sysinit.service(8)` service is started.) 5. `shutdown` — when the system shutdown begins. It acts as barrier between the time the system is fully up and running and where it is about to shut down. (This extension happens when the `systemd-pcrphase.service` service is stopped.) 6. `final` — at the end of system shutdown. It acts as barrier between the time the service manager still runs and when it transitions into the final shutdown phase where service management is not available anymore. (This extension happens when the `systemd-pcrphase-sysinit.service(8)` service is stopped.) During a regular system lifecycle, PCR 11 is extended with the strings `enter-initrd`, `leave-initrd`, `sysinit`, `ready`, `shutdown`, and `final`. Specific phases of the boot process may be referenced via the series of strings measured, separated by colons (the "phase path"). For example, the phase path for the regular system runtime is `enter-initrd:leave-initrd:sysinit:ready`, while the one for the initrd is just `enter-initrd`. The phase path for the boot phase before the initrd is an empty string; because that's hard to pass around a single colon (`:`) may be used instead. Note that the aforementioned six strings are just the default strings and individual systems might measure other strings at other times, and thus implement different and more fine-grained boot phases to bind policy to. By binding policy of TPM2 objects to a specific phase path it is possible to restrict access to them to specific phases of the boot process, for example making it impossible to access the root file system's encryption key after the system transitioned from the initrd into the host root file system. Use `systemd-measure(1)` to pre-calculate expected PCR 11 values for specific boot phases (via the `--phase=` switch). `systemd-pcrfs-root.service` and `systemd-pcrfs@.service` are automatically pulled into the initial transaction by `systemd-gpt-auto-generator(8)` for the root and `/var/` file systems. `systemd-fstab-generator(8)` will do this for all mounts with the `x-systemd.pcrfs` mount option in `/etc/fstab`. # Options The `/usr/lib/systemd/systemd-pcrextend` executable may also be invoked from the command line, where it expects the word to extend into a PCR or NvPCR, as well as the following switches: `--bank=` Takes the PCR banks to extend the specified word into. If not specified, the tool automatically determines all enabled PCR banks and measures the word into all of them. `--pcr=` Takes the index of the PCR to extend. If `--machine-id` or `--file-system=` are specified defaults to 15, otherwise (and unless `--product-id` is specified) defaults to 11. May be specified multiple times, in order to measure to multiple PCRs at the same time. May not be combined with `--nvpcr=`. `--nvpcr=` Takes a name of an NvPCR to extend. NvPCRs are additional PCRs implemented via TPM NV indexes. The name should be a short string such as `hardware` or `disk-encryption`. If `--product-id` is specified defaults `hardware`. May not be combined with `--pcr=`. `--tpm2-device=PATH` Controls which TPM2 device to use. Expects a device node path referring to the TPM2 chip (e.g. `/dev/tpmrm0`). Alternatively the special value `auto` may be specified, in order to automatically determine the device node of a suitable TPM2 device (of which there must be exactly one). The special value `list` may be used to enumerate all suitable TPM2 devices currently discovered. `--graceful` If no TPM2 firmware, kernel subsystem, kernel driver or device support is found, exit with exit status 0 (i.e. indicate success). If this is not specified, any attempt to measure without a TPM2 device will cause the invocation to fail. `--machine-id` Instead of measuring a word specified on the command line into PCR 11, measure the host's machine ID into PCR 15. `--product-id` Instead of measuring a word specified on the command line into PCR 11, measure the firmware's product UUID into an NvPCR named `hardware`. `--login=` Instead of measuring a word specified on the command line into PCR 11, measure the user record of the specified user into an NvPCR named `login`. The parameter must be a user name or numeric UID. The record is reduced to its `regular`, `perMachine` and `binding` sections (i.e. the privileged, secret, status and signature sections are stripped, so that for example password hash changes do not perturb the NvPCR), normalized and serialized to canonical JSON before measurement. This is primarily used by `systemd-pcrlogin@.service`. `--file-system=` Instead of measuring a word specified on the command line into PCR 11, measure identity information of the specified file system into PCR 15. The parameter must be the path to the established mount point of the file system to measure. `--event-type=` Set the event log event type for this measurement. Pass `help` for a list of currently defined identifiers. Defaults to an appropriate value for `--machine-id`, `--product-id`, `--file-system=`, `--login=`, and otherwise to `phase`. # Files `/run/log/systemd/tpm2-measure.log` Measurements are logged into an event log file maintained in `/run/log/systemd/tpm2-measure.log`, which contains a [JSON-SEQ](https://www.rfc-editor.org/rfc/rfc7464.html) series of objects that follow the general structure of the [TCG Canonical Event Log Format (CEL-JSON)](https://trustedcomputinggroup.org/resource/canonical-event-log-format/) event objects (but lack the `recnum` field). A `LOCK_EX` BSD file lock (`flock(2)`) on the log file is acquired while the measurement is made and the file is updated. Thus, applications that intend to acquire a consistent quote from the TPM with the associated snapshot of the event log should acquire a `LOCK_SH` lock while doing so. `/usr/lib/nvpcr/*.nvpcr` Definition files for NvPCRs. # See Also `systemd(1)`, `systemd-stub(7)`, `systemd-measure(1)`, `systemd-gpt-auto-generator(8)`, `systemd-fstab-generator(8)`, [TPM2 PCR Measurements Made by systemd](https://systemd.io/TPM2_PCR_MEASUREMENTS) # systemd-portabled.service systemd systemd-portabled.service 8 systemd-portabled.service systemd-portabled Portable service manager `systemd-portabled.service` `/usr/lib/systemd/systemd-portabled` # Description `systemd-portabled` is a system service that may be used to attach, detach and inspect portable service images. Most of `systemd-portabled`'s functionality is accessible through the `portablectl(1)` command. See the [Portable Services](https://systemd.io/PORTABLE_SERVICES) page for details about the concepts this service implements. See `org.freedesktop.portable1(5)` and `org.freedesktop.LogControl1(5)` for a description of the D-Bus API. # See Also `systemd(1)`, `portablectl(1)`, `org.freedesktop.portable1(5)` # systemd-poweroff.service systemd systemd-poweroff.service 8 systemd-poweroff.service systemd-halt.service systemd-reboot.service systemd-kexec.service systemd-shutdown System shutdown logic `systemd-poweroff.service` `systemd-halt.service` `systemd-reboot.service` `systemd-kexec.service` `/usr/lib/systemd/systemd-shutdown` `/usr/lib/systemd/system-shutdown/` # Description `systemd-poweroff.service` is a system service that is pulled in by `poweroff.target` and is responsible for the actual system power-off operation. Similarly, `systemd-halt.service` is pulled in by `halt.target`, `systemd-reboot.service` by `reboot.target` and `systemd-kexec.service` by `kexec.target` to execute the respective actions. When these services are run, they ensure that PID 1 is replaced by the `/usr/lib/systemd/systemd-shutdown` binary which is then responsible for the actual shutdown. Before shutting down, this binary will try to unmount all remaining file systems (or at least remount them read-only), disable all remaining swap devices, detach all remaining storage devices and kill all remaining processes. It is necessary to have this code in a separate binary because otherwise rebooting after an upgrade might be broken — the running PID 1 could still depend on libraries which are not available any more, thus keeping the file system busy, which then cannot be re-mounted read-only. Shortly before executing the actual system power-off/halt/reboot/kexec, `systemd-shutdown` will run all executables in `/usr/lib/systemd/system-shutdown/`. Those executables are called with one argument: either `poweroff`, `halt`, `reboot`, or `kexec`, depending on the chosen action. All executables in this directory are executed in parallel, and execution of the action is not continued before all executables finished. (A safety timeout of 90s is applied however.) Note that these executables are run *after* all services have been shut down, and after most mounts have been unmounted (the root file system as well as `/run/` and various API file systems are still around though). This means any programs dropped into this directory must be prepared to run in such a limited execution environment and not rely on external services or hierarchies such as `/var/` to be around (or writable). Note that `systemd-poweroff.service` (and the related units) should never be executed directly. Instead, trigger system shutdown with a command such as `systemctl poweroff`. Another form of shutdown is provided by the `systemd-soft-reboot.service(8)` functionality. It reboots only the OS userspace, leaving the kernel, firmware, and hardware as it is. # See Also `systemd(1)`, `systemctl(1)`, `systemd.special(7)`, `reboot(2)`, `systemd-suspend.service(8)`, `systemd-soft-reboot.service(8)`, `bootup(7)` # systemd-pstore.service systemd systemd-pstore.service 8 systemd-pstore.service systemd-pstore A service to archive contents of pstore `/usr/lib/systemd/systemd-pstore` `systemd-pstore.service` # Description `systemd-pstore.service` is a system service that archives the contents of the Linux persistent storage filesystem, pstore, to other storage, thus preserving the existing information contained in the pstore, and clearing pstore storage for future error events. Linux provides a persistent storage file system, pstore, that can store error records when the kernel dies (or reboots or powers-off). These records in turn can be referenced to debug kernel problems (currently the kernel stores the tail of the kernel log, which also contains a stack backtrace, into pstore). The pstore file system supports a variety of backends that map onto persistent storage, such as the ACPI ERST and UEFI variables. The pstore backends typically offer a relatively small amount of persistent storage, e.g. 64KiB, which can quickly fill up and thus prevent subsequent kernel crashes from recording errors. Thus there is a need to monitor and extract the pstore contents so that future kernel problems can also record information in the pstore. The pstore service is independent of the kdump service. In cloud environments specifically, host and guest filesystems are on remote filesystems (e.g. iSCSI or NFS), thus kdump relies (implicitly and/or explicitly) upon proper operation of networking software \*and\* hardware \*and\* infrastructure. Thus it may not be possible to capture a kernel coredump to a file since writes over the network may not be possible. The pstore backend, on the other hand, is completely local and provides a path to store error records which will survive a reboot and aid in post-mortem debugging. The `systemd-pstore` executable does the actual work. Upon starting, the `pstore.conf` file is read and the `/sys/fs/pstore/` directory contents are processed according to the options. Pstore files are written to the journal, and optionally saved into `/var/lib/systemd/pstore/`. # Configuration The behavior of `systemd-pstore` is configured through the configuration file `/etc/systemd/pstore.conf` and corresponding snippets `/etc/systemd/pstore.conf.d/*.conf`, see `pstore.conf(5)`. ## Disabling pstore processing To disable pstore processing by `systemd-pstore`, set Storage=none in `pstore.conf(5)`. ## Kernel parameters The kernel has two parameters, `/sys/module/kernel/parameters/crash_kexec_post_notifiers` and `/sys/module/printk/parameters/always_kmsg_dump`, that control writes into pstore. The first enables storing of the kernel log (including stack trace) into pstore upon a panic or crash, and the second enables storing of the kernel log upon a normal shutdown (shutdown, reboot, halt). These parameters can be managed via the `tmpfiles.d(5)` mechanism, specifically the file `/usr/lib/tmpfiles/systemd-pstore.conf`. # Usage Data stored in the journal can be viewed with `journalctl(1)` as usual. # See Also `pstore.conf(5)` # systemd-pty-forward systemd systemd-pty-forward 1 systemd-pty-forward Run a command with a custom terminal background color or title systemd-pty-forward OPTIONS COMMAND # Description `systemd-pty-forward` can be used to run a command with a custom terminal background color or title. # Options The following options are understood: `--background=COLOR` Change the terminal background color to the specified ANSI color as long as the command runs. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as `40`, `41`, …, `47`, `48;2;…`, `48;5;…`. See [ANSI Escape Code (Wikipedia)](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters) for details. Example: `--background=44` for a blue background. `--title=TITLE` Change the terminal title to the specified string as long as the command runs. `--quiet`; `-q` Suppresses additional informational output while running. `--console=MODE` Selects how the terminal for the invoked command is acquired and connected. Takes one of `interactive`, `read-only`, `broker` or `broker-log`. If `interactive` (the default) a pseudo TTY is allocated locally and the calling terminal is forwarded to it interactively, i.e. both terminal output and user input are forwarded. If `read-only` this is similar, but no user input from standard input is forwarded to the command. If `broker` or `broker-log` the pseudo TTY is not allocated locally, but acquired from `systemd-ptybrokerd.service(8)`. In both cases the broker retains the frontend (i.e. the "master") side of the pseudo TTY and the command is invoked on the acquired backend (i.e. the "slave") side. With `broker` the frontend output is discarded (unless monitored), with `broker-log` it is written to the logs by `systemd-ptybrokerd.service`. The allocated pseudo TTY may subsequently be monitored, listed or hung up with `ptyctl(1)`. `--system`; `--user` When `--console=broker` or `--console=broker-log` is used, selects whether to talk to the system-wide instance or the per-user instance of `systemd-ptybrokerd.service(8)`. Defaults to `--system`. Has no effect in the other console modes. `--pty-name=NAME` When `--console=broker` or `--console=broker-log` is used, registers the newly allocated pseudo TTY under the specified name with `systemd-ptybrokerd.service(8)`; if not specified (the default) the broker picks a randomized name. Has no effect in the other console modes. # systemd-ptybrokerd.service systemd systemd-ptybrokerd.service 8 systemd-ptybrokerd.service systemd-ptybrokerd Pseudo TTY Broker `systemd-ptybrokerd.service` `systemd-ptybrokerd.socket` `/usr/lib/systemd/systemd-ptybrokerd` # Description `systemd-ptybrokerd` is a service that allocates and manages pseudo terminals (PTYs) on behalf of clients. It allocates a PTY pair on client request — or takes possession of the frontend (i.e. `master`) side of a PTY the client already allocated — and then takes care of the frontend side of the PTY: whatever is written to the PTY is either discarded or forwarded to the log, and may at any time be monitored and interactively attached to. The backend (i.e. `slave`) side of the PTY is handed back to the client, which typically invokes some payload with its standard input/output/error connected to it. At the client's request the broker may also invoke a shell on the backend side itself, as a transient service unit. When running as part of the system service manager, such shell sessions run through the `systemd-ptybroker-shell` PAM stack. This mechanism decouples the lifetime and management of a PTY from the process that requested it: the terminal of a service, container, virtual machine or shell session managed by the broker exists independently of any interactive client, may be monitored or attached to at any time (also by multiple clients simultaneously), and continues to operate — logging output, if configured — when no client is attached at all. It hence provides terminal semantics for otherwise non-interactive contexts, for example fully headless systems. The service is used by various other components: - The service manager connects the standard input/output/error of services to a broker-provided PTY if `StandardInput=broker`, `StandardOutput=broker`, `StandardError=broker` (or their `broker-log` flavours) are used, see `systemd.exec(5)`. - `systemd-pty-forward(1)` invokes arbitrary commands on a broker-provided PTY via `--console=broker`/`--console=broker-log`. - `systemd-nspawn(1)` and `systemd-vmspawn(1)` register the console of a container or virtual machine with the broker via their `--console=broker`/`--console=broker-log` switches. - `run0(1)` requests interactive privileged shell sessions from the broker. PTYs managed by the broker may be listed, monitored, interactively attached to, and hung up with the `ptyctl(1)` tool. The service is available both as a system service and as a per-user service. The system instance brokers PTYs for system services and privileged clients, the user instances do the same for the respective user's service manager and clients. Both instances are socket activated (via `systemd-ptybrokerd.socket`) and exit automatically again once they are idle, i.e. when no client is connected and no PTY is registered anymore. The service provides the `io.systemd.PTYBroker` [Varlink](https://varlink.org/) IPC interface on `/run/systemd/io.systemd.PTYBroker` (for the system instance) and `$XDG_RUNTIME_DIR/systemd/io.systemd.PTYBroker` (for the user instances). Access to the operations of the system instance is gated via [polkit](https://www.freedesktop.org/software/polkit/docs/latest/). # See Also `systemd(1)`, `ptyctl(1)`, `systemd-pty-forward(1)`, `systemd.exec(5)`, `systemd-nspawn(1)`, `systemd-vmspawn(1)`, `run0(1)` # systemd-quotacheck@.service systemd systemd-quotacheck@.service 8 systemd-quotacheck@.service systemd-quotacheck-root.service systemd-quotacheck File system quota checker logic `systemd-quotacheck@.service` `systemd-quotacheck-root.service` `/usr/lib/systemd/systemd-quotacheck` # Description `systemd-quotacheck@.service` and `systemd-quotacheck-root.service` are services responsible for file system quota checks. They run once at boot after all necessary file systems are mounted. They are pulled in only if at least one file system has quotas enabled. # Kernel Command Line `systemd-quotacheck` understands one kernel command line parameter: `quotacheck.mode=` One of `auto`, `force`, `skip`. Controls the mode of operation. The default is `auto`, and ensures that file system quota checks are done when the file system quota checker deems them necessary. `force` unconditionally results in full file system quota checks. `skip` skips any file system quota checks. # Credentials `systemd-quotacheck` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `quotacheck.mode` The contents of the credential are parsed in the same way as the kernel command line option of the same name. See above for more details. Note that by default the `systemd-quotacheck@.service` and `systemd-quotacheck-root.service` unit files are set up to inherit `quotacheck.mode` credential from the service manager. # See Also `systemd(1)`, `quotacheck(8)`, `systemd-fsck@.service(8)` # systemd-random-seed.service systemd systemd-random-seed.service 8 systemd-random-seed.service systemd-random-seed Load and save the OS system random seed at boot and shutdown `systemd-random-seed.service` `/usr/lib/systemd/systemd-random-seed` # Description `systemd-random-seed.service` is a service that loads an on-disk random seed into the kernel entropy pool during boot and saves it at shutdown. See `random(4)` for details. By default, no entropy is credited when the random seed is written into the kernel entropy pool, but this may be changed with `$SYSTEMD_RANDOM_SEED_CREDIT`, see below. On disk the random seed is stored in `/var/lib/systemd/random-seed`. Note that this service runs relatively late during the early boot phase, i.e. generally after the initrd phase has finished and the `/var/` file system has been mounted. Many system services require entropy much earlier than this — this service is hence of limited use for complex system. It is recommended to use a boot loader that can pass an initial random seed to the kernel to ensure that entropy is available from earliest boot on, for example `systemd-boot(7)`, with its `bootctl random-seed` functionality. When loading the random seed from disk, the file is immediately updated with a new seed retrieved from the kernel, in order to ensure no two boots operate with the same random seed. This new seed is retrieved synchronously from the kernel, which means the service will not complete start-up until the random pool is fully initialized. On entropy-starved systems this may take a while. This functionality is intended to be used as synchronization point for ordering services that require an initialized entropy pool to function securely (i.e. services that access `/dev/urandom` without any further precautions). Care should be taken when creating OS images that are replicated to multiple systems: if the random seed file is included unmodified each system will initialize its entropy pool with the same data, and thus — if otherwise entropy-starved — generate the same or at least guessable random seed streams. As a safety precaution crediting entropy is thus disabled by default. It is recommended to remove the random seed from OS images intended for replication on multiple systems, in which case it is safe to enable entropy crediting, see below. Also see [Safely Building Images](https://systemd.io/BUILDING_IMAGES). See [Random Seeds](https://systemd.io/RANDOM_SEEDS) for further information. # Environment `$SYSTEMD_RANDOM_SEED_CREDIT` By default, `systemd-random-seed.service` does not credit any entropy when loading the random seed. With this option this behaviour may be changed: it either takes a boolean parameter or the special string `force`. Defaults to false, in which case no entropy is credited. If true, entropy is credited if the random seed file and system state pass various superficial consistency checks. If set to `force` entropy is credited, regardless of these checks, as long as the random seed file exists. # See Also `systemd(1)`, `random(4)`, `systemd-boot(7)`, `systemd-stub(7)`, `bootctl(1)`, `systemd-boot-random-seed.service(8)` # systemd-remount-fs.service systemd systemd-remount-fs.service 8 systemd-remount-fs.service systemd-remount-fs Remount root and kernel file systems `systemd-remount-fs.service` `/usr/lib/systemd/systemd-remount-fs` # Description `systemd-remount-fs.service` is an early boot service that applies mount options listed in `fstab(5)`, or gathered from the partition table (when `systemd-gpt-auto-generator(8)` is active) to the root file system, the `/usr/` file system, and the kernel API file systems. This is required so that the mount options of these file systems — which are pre-mounted by the kernel, the initrd, container environments or system manager code — are updated to those configured in `/etc/fstab` and the other sources. This service ignores normal file systems and only changes the root file system (i.e. `/`), `/usr/`, and the virtual kernel API file systems such as `/proc/`, `/sys/` or `/dev/`. This service executes no operation if no configuration is found (`/etc/fstab` does not exist or lists no entries for the mentioned file systems, or the partition table does not contain relevant entries). For a longer discussion of kernel API file systems see [API File Systems](https://systemd.io/API_FILE_SYSTEMS). Note: `systemd-remount-fs.service` is usually pulled in by `systemd-fstab-generator(8)`, hence it is also affected by the kernel command line option `fstab=`, which may be used to disable the generator. It may also be pulled in by `systemd-gpt-auto-generator(8)`, which is affected by `systemd.gpt_auto` and other options. # See Also `systemd(1)`, `fstab(5)`, `mount(8)`, `systemd-fstab-generator(8)`, `systemd-gpt-auto-generator(8)` # systemd-repart systemd systemd-repart 8 systemd-repart systemd-repart.service Automatically grow and add partitions, and generate disk images (DDIs) systemd-repart OPTIONS BLOCKDEVICE `systemd-repart.service` # Description `systemd-repart` creates partition tables, and adds or grows partitions, based on the configuration files described in `repart.d(5)`. It operates on the block device or file image specified on the command line. `systemd-repart` is used when *building* OS images, and also when *deploying* images to automatically adjust them, during boot, to the system they are running on. This way the image can be minimal in size and may be augmented automatically at boot, taking possession of the disk space available. If invoked with no arguments, `systemd-repart` operates on the block device backing the root file system partition of the running OS, thus adding and growing partitions of the booted OS itself. When called in the initrd, it operates on the block device backing `/sysroot/` instead, i.e. on the block device the system will soon transition into. If `--image=` is used, it will operate on the specified device or image file. The `systemd-repart.service` service is generally run at boot in the initrd, in order to augment the partition table of the OS before its partitions are mounted. If the block device is specified as `-` (or as an empty string), `systemd-repart` will not operate on any block device or image file, and instead determine and output the minimum disk/image size for the specified partition configuration, taking all configured size constraints into account. `systemd-repart` operations are mostly incremental: it grows existing partitions or adds new ones, but does not shrink, delete, or move existing partitions. The service is intended to be run on every boot, but when it detects that the partition table already matches the installed `repart.d/*.conf` configuration files, it executes no operation. The following use cases are among those covered: - The root partition may be grown to cover the whole available disk space. - A `/home/`, swap, or `/srv/` partition can be added. - A second (or third, …) root partition may be added, to cover A/B style setups where a second version of the root file system is alternatingly used for implementing update schemes. The deployed image would carry only a single partition ("A") but on first boot a second partition ("B") for this purpose is automatically created. The algorithm executed by `systemd-repart` is roughly as follows: 1. The `repart.d/*.conf` configuration files are loaded and parsed, and ordered by filename (without the directory prefix). For each configuration file, drop-in files are loaded from directories with same name as the configuration file with the suffix ".d" added. 2. The partition table on the block device is loaded and parsed, if present. 3. The existing partitions in the partition table are matched with the `repart.d/*.conf` files by GPT partition type UUID. The first existing partition of a specific type is assigned the first configuration file declaring the same type. The second existing partition of a specific type is then assigned the second configuration file declaring the same type, and so on. After this iterative assigning is complete, any existing partitions that have no matching configuration file are considered "foreign" and left as they are. And any configuration files for which no partition was matched are treated as requests to create a partition. 4. Partitions that shall be created are now allocated on the disk, taking the size constraints and weights declared in the configuration files into account. Free space is used within the limits set by size and padding requests. In addition, existing partitions that should be grown are grown. When possible, newly created partitions are assigned partition table slots after existing partitions of the same type, as those are matched to configuration files in partition number order and a new partition inserted before an existing one would change that matching on the next invocation. If no such slot is available, the first unused slot is used. Partitions are never reordered and thus partition numbers remain stable. When partitions are created, they are placed in the smallest area of free space that is large enough to satisfy the size and padding limits. This means that partitions might have different order on disk than in the partition table. Note that this allocation happens in memory only, the partition table on disk is not updated yet. 5. All existing partitions for which configuration files exist and which currently have no GPT partition label set will be assigned a label, either explicitly configured in the configuration or — if that's missing — derived automatically from the partition type. The same is done for all partitions that are newly created. These assignments are done in memory only, too, the disk is not updated yet. 6. Similarly, all existing partitions for which configuration files exist and which currently have an all-zero identifying UUID will be assigned a new UUID. This UUID is cryptographically hashed from a common seed value together with the partition type UUID (and a counter in case multiple partitions of the same type are defined), see below. The same is done for all partitions that are created anew. These assignments are done in memory only, too, the disk is not updated yet. 7. Similarly, if the disk's volume UUID is all zeroes it is also initialized, also cryptographically hashed from the same common seed value. This is done in memory only too. 8. The disk space assigned to new partitions (i.e. what was previously free space) is now erased. Specifically, all file system signatures are removed, and if the device supports it, the `BLKDISCARD` I/O control command is issued to inform the hardware that the space is now empty. In addition any "padding" between partitions and at the end of the device is similarly erased. 9. The new partition table is finally written to disk. The kernel is asked to reread the partition table. As an exception to the normal incremental operation, when called in a special "factory reset" mode, `systemd-repart` may be used to erase existing partitions to reset an installation back to vendor defaults. This mode of operation is used when either the `--factory-reset=yes` switch is passed on the tool's command line, or the `systemd.factory_reset=yes` option is specified on the kernel command line, or the `FactoryResetRequest` EFI variable (vendor UUID `8cf2644b-4b0b-428f-9387-6d876050dc67`) is set to "yes". It alters the algorithm above slightly: between the 3rd and the 4th step above any partition marked explicitly via the `FactoryReset=` boolean is deleted, and the algorithm restarted, thus immediately re-creating these partitions anew empty. Note that `systemd-repart` by default only changes partition tables, it does not create or resize any file systems within these partitions, unless the `Format=` configuration option is specified. Also note that there are also separate mechanisms available for this purpose, for example `systemd-growfs(8)` and `systemd-makefs`. The UUIDs identifying the new partitions created (or assigned to existing partitions that have no UUID yet), as well as the disk as a whole are hashed cryptographically from a common seed value. This seed value is usually the `machine-id(5)` of the system, so that the machine ID reproducibly determines the UUIDs assigned to all partitions. If the machine ID cannot be read (or the user passes `--seed=random`, see below) the seed is generated randomly instead, so that the partition UUIDs are also effectively random. The seed value may also be set explicitly, formatted as UUID via the `--seed=` option. By hashing these UUIDs from a common seed images prepared with this tool become reproducible and the result of the algorithm above deterministic. The positional argument should specify the block device or a regular file to operate on. If `--empty=create` is specified, the specified path is created as regular file, which is useful for generating disk images from scratch. # Options The following options are understood: `-n`; `--dry-run=` Takes a boolean. If this switch is not specified, `--dry-run=yes` is the implied default. Controls whether `systemd-repart` executes the requested re-partition operations or whether it should only show what it would do. Unless `--dry-run=no` is specified `systemd-repart` will not actually touch the device's partition table. The short option `-n` is equivalent to `--dry-run=yes` and was added in version 262. `--empty=` Takes one of `refuse`, `allow`, `require`, `force` or `create`. Controls how to operate on block devices that are entirely empty, i.e. carry no partition table/disk label yet. If this switch is not specified, the implied default is `refuse`. If `refuse` `systemd-repart` requires that the block device it shall operate on already carries a partition table and refuses operation if none is found. If `allow` the command will extend an existing partition table or create a new one if none exists. If `require` the command will create a new partition table if none exists so far, and refuse operation if one already exists. If `force` it will create a fresh partition table unconditionally, erasing the disk fully in effect. If `force` no existing partitions will be taken into account or survive the operation. Hence: use with care, this is a great way to lose all your data. If `create` a new loopback file is create under the path passed via the device node parameter, of the size indicated with `--size=`, see below. `--discard=` Takes a boolean. If this switch is not specified ,`--discard=yes` is the implied default. Controls whether to issue the `BLKDISCARD` I/O control command on the space taken up by any added partitions or on the space in between them. Usually, it is a good idea to issue this request since it tells the underlying hardware that the covered blocks shall be considered empty, improving performance. If operating on a regular file instead of a block device node, a sparse file is generated. `--size=` Takes a size in bytes, using the usual K, M, G, T suffixes, or the special value `auto`. If used the specified device node path must refer to a regular file, which is then grown to the specified size if smaller, before any change is made to the partition table. If specified as `auto` the minimal size for the disk image is automatically determined (i.e. the minimal sizes of all partitions are summed up, taking space for additional metadata into account). This switch is not supported if the specified node is a block device. This switch has no effect if the file is already as large as the specified size or larger. The specified size is implicitly rounded up to multiples of 4096. When used with `--empty=create` this specifies the initial size of the loopback file to create. The `--size=auto` option takes the sizes of pre-existing partitions into account. However, it does not accommodate for partition tables that are not tightly packed: the configured partitions might still not fit into the backing device if empty space exists between pre-existing partitions (or before the first partition) that cannot be fully filled by partitions to grow or create. Also note that the automatic size determination does not take files or directories specified with `CopyFiles=` into account: operation might fail if the specified files or directories require more disk space then the configured per-partition minimal size limit. `--cow=BOOL` Controls copy-on-write for newly created image files on filesystems that support it. If true, copy-on-write is enabled; if false, it is disabled. If set to `auto`, the filesystem or parent directory default is left unchanged. Copy-on-write allows files to be reflinked into the image, reducing both build time and disk usage, but may result in fragmentation for images subject to frequent random writes. Defaults to `auto`. `--factory-reset=` Takes boolean. If this switch is not specified, `--factory-reset=no` is the implied default. Controls whether to operate in "factory reset" mode, see above. If set to true this will remove all existing partitions marked with `FactoryReset=` set to yes early while executing the re-partitioning algorithm. Use with care, this is a great way to lose all your data. Note that partition files need to explicitly turn `FactoryReset=` on, as the option defaults to off. If no partitions are marked for factory reset this switch has no effect. Note that there are two other methods to request factory reset operation: via the kernel command line and via an EFI variable, see above. `--can-factory-reset` If this switch is specified the disk is not re-partitioned. Instead it is determined if any existing partitions are marked with `FactoryReset=`. If there are the tool will exit with exit status zero, otherwise non-zero. This switch may be used to quickly determine whether the running system supports a factory reset mechanism built on `systemd-repart`. `--root=` Takes a path to a directory to use as root file system when searching for `repart.d/*.conf` files, for the machine ID file to use as seed and for the `CopyFiles=` and `CopyBlocks=` source files and directories. By default when invoked on the regular system this defaults to the host's root file system `/`. If invoked from the initrd this defaults to `/sysroot/`, so that the tool operates on the configuration and machine ID stored in the root file system later transitioned into itself. See `--copy-source=` for a more restricted option that only affects `CopyFiles=`. `--image=` Takes a path to a disk image file or device to mount and use in a similar fashion to `--root=`, see above. `--seed=` Takes a UUID as argument or the special value `random`. If a UUID is specified the UUIDs to assign to partitions and the partition table itself are derived via cryptographic hashing from it. If not specified, it is attempted to read the machine ID from the host (or more precisely, the root directory configured via `--root=`) and use it as seed instead, falling back to a randomized seed otherwise. Use `--seed=random` to force a randomized seed. Explicitly specifying the seed may be used to generated strictly reproducible partition tables. `--pretty=` Takes a boolean argument. If this switch is not specified, it defaults to on when called from an interactive terminal and off otherwise. Controls whether to show a user friendly table and graphic illustrating the changes applied. `--definitions=` Takes a file system path. If specified the `*.conf` files are read from the specified directory instead of searching in `/usr/lib/repart.d/*.conf`, `/etc/repart.d/*.conf`, `/run/repart.d/*.conf`. This parameter can be specified multiple times. `--key-file=` Takes a file system path. Configures the encryption key to use when setting up LUKS2 volumes configured with the `Encrypt=key-file` setting in partition files. Should refer to a regular file containing the key, or an `AF_UNIX` stream socket in the file system. In the latter case, a connection is made to it and the key read from it. If this switch is not specified, and no `KeyFile=` is specified in the partition file, the empty key (i.e. zero length key) is used. This behaviour is useful for setting up encrypted partitions during early first boot that receive their user-supplied password only in a later setup step. `--private-key=` Takes a file system path or an engine or provider specific designation. Configures the signing key to use when creating verity signature partitions with the `Verity=signature` setting in partition files. `--private-key-source=` Takes one of `file`, `engine` or `provider`. In the latter two cases, it is followed by the name of a provider or engine, separated by colon, that will be passed to OpenSSL's "engine" or "provider" logic. Configures how to load the private key to use when creating verity signature partitions with the `Verity=signature` setting in partition files. `--certificate=` Takes a file system path or a provider specific designation. Configures the PEM encoded X.509 certificate to use when creating verity signature partitions with the `Verity=signature` setting in partition files. `--certificate-source=` Takes one of `file`, or `provider`. In the latter case, it is followed by the name of a provider, separated by colon, that will be passed to OpenSSL's "provider" logic. Configures how to load the X.509 certificate to use when creating verity signature partitions with the `Verity=signature` setting in partition files. `--join-signature=` Specifies a colon-separated tuple with a hex-encoded top-level Verity hash of a `Verity=hash` partition as first element, and a PKCS7 signature of the roothash as a path to a DER-encoded signature file, or as an ASCII base64 string encoding of a DER-encoded signature prefixed by `base64:`. To be used on a pre-existing image that was created with a parameter such as `--defer-partitions=root-verity-sig`, in order to allow implementing offline signing of the verity signature partition. This is an alternative to online signing using parameters such as `--private-key=`, for build systems where the private key for production signing is not available in the same context where content is created. `--tpm2-device=`; `--tpm2-pcrs=` Configures the TPM2 device and list of PCRs to use for LUKS2 volumes configured with the `Encrypt=tpm2` option. These options take the same parameters as the identically named options to `systemd-cryptenroll(1)` and have the same effect on partitions where TPM2 enrollment is requested. `--tpm2-device-key=PATH`; `--tpm2-seal-key-handle=HANDLE` Configures a TPM2 SRK key to bind encryption to. See `systemd-cryptenroll(1)` for details on this option. `--tpm2-public-key=PATH`; `--tpm2-public-key-pcrs=PCR+PCR...` Configures a TPM2 signed PCR policy to bind encryption to. See `systemd-cryptenroll(1)` for details on these two options. `--tpm2-public-key-policyref=STRING` Configures the policy reference to use together with the signed PCR policy configured via `--tpm2-public-key=`. See `systemd-cryptenroll(1)` for details on this option. `--tpm2-pcrlock=PATH` Configures a TPM2 pcrlock policy to bind encryption to. See `systemd-cryptenroll(1)` for details on this option. `--split=BOOL` Enables generation of split artifacts from partitions configured with `SplitName=`. If enabled, for each partition with `SplitName=` set, a separate output file containing just the contents of that partition is generated. The output filename consists of the loopback filename suffixed with the name configured with `SplitName=`. If the loopback filename ends with `.raw`, the suffix is inserted before the `.raw` extension instead. Note that `--split` is independent from `--dry-run`. Even if `--dry-run` is enabled, split artifacts will still be generated from an existing image if `--split` is enabled. `--include-partitions=PARTITIONS`; `--exclude-partitions=PARTITIONS` These options specify which partition types `systemd-repart` should operate on. If `--include-partitions=` is used, all partitions that are not specified are excluded. If `--exclude-partitions=` is used, all partitions that are specified are excluded. Both options take a comma separated list of GPT partition type UUIDs or identifiers (see `Type=` in `repart.d(5)`). `--defer-partitions=PARTITIONS` This option specifies for which partition types `systemd-repart` should defer. All partitions that are deferred using this option are still taken into account when calculating the sizes and offsets of other partitions, but are not actually written to the disk image. The net effect of this option is that if you run `systemd-repart` again without this option, the missing partitions will be added as if they had not been deferred the first time `systemd-repart` was executed. `--defer-partitions-empty=yes` This is very similar to `--defer-partitions=` but automatically selects all partitions for deferral that have `Format=empty` set and do not configure a custom label, or which set `Label=_empty`. It may be used in conjunction with `--defer-partitions=` or `--defer-partitions-factory-reset=yes`, in which case all matching partitions are deferred. `--defer-partitions-factory-reset=yes` This is very similar to `--defer-partitions=` but automatically selects all partitions for deferral that have `FactoryReset=yes` set. It may be used in conjunction with `--defer-partitions=` or `--defer-partitions-empty=yes`, in which case all matching partitions are deferred. `--sector-size=BYTES` This option allows configuring the sector size of the image produced by `systemd-repart`. It takes a value that is a power of `2` between `512` and `4096`. This option is useful when building images for disks that use a different sector size as the disk on which the image is produced. `--grain-size=BYTES` This option controls the partition alignment granularity used when placing partitions. It takes a power-of-2 value that is at least the sector size. All partition start offsets will be rounded up to a multiple of this value. Defaults to `MAX(4096, sector_size)`, matching the conventional 4 KiB alignment. Setting this to `1M` ensures proper alignment for modern storage devices even after small fixed-size partitions such as a verity signature partition. `--architecture=ARCH` This option allows overriding the architecture used for architecture specific partition types. For example, if set to `arm64` a partition type of `root-x86-64` referenced in `repart.d/` drop-ins will be patched dynamically to refer to `root-arm64` instead. Takes one of `alpha`, `arc`, `arm`, `arm64`, `ia64`, `loongarch64`, `mips-le`, `mips64-le`, `parisc`, `ppc`, `ppc64`, `ppc64-le`, `riscv32`, `riscv64`, `s390`, `s390x`, `tilegx`, `x86` or `x86-64`. `--offline=BOOL` Instructs `systemd-repart` to build the image offline. Takes a boolean or `auto`. Defaults to `auto`. If enabled, the image is built without using loop devices. This is useful to build images unprivileged or when loop devices are not available. If disabled, the image is always built using loop devices. If `auto`, `systemd-repart` will build the image online if possible and fall back to building the image offline if loop devices are not available or cannot be accessed due to missing permissions. `--copy-from=PATH` Instructs `systemd-repart` to synthesize partition definitions from the partition table in the given image or device. This option can be specified multiple times to synthesize definitions from each of the given images or devices. The generated definitions will copy the partitions into the destination partition table. The copied partitions will have the same or a slightly larger size (partitions may be enlarged to align to the new grain or sector size), metadata and contents but might have a different partition number and might be located at a different offset in the destination partition table. These definitions can be combined with partition definitions read from regular partition definition files. The synthesized definitions take precedence over the definitions read from partition definition files. `--copy-source=PATH`; `-s` \ Specifies a source directory all `CopyFiles=` source paths shall be considered relative to. This is similar to `--root=`, but exclusively applies to the `CopyFiles=` setting. If `--root=` and `--copy-source=` are used in combination the former applies as usual, except for `CopyFiles=` where the latter takes precedence. `--make-ddi=TYPE` Takes one of `sysext`, `confext` or `portable`. Generates a Discoverable Disk Image (DDI) for a system extension (sysext, see `systemd-sysext(8)` for details), configuration extension (confext) or [Portable Services](https://systemd.io/PORTABLE_SERVICES). The generated image will consist of a signed Verity `erofs` file system as root partition. In this mode of operation the partition definitions in `/usr/lib/repart.d/*.conf` and related directories are not read, and `--definitions=` is not supported, as appropriate definitions for the selected DDI class will be chosen automatically. Must be used in conjunction with `--copy-source=` to specify the file hierarchy to populate the DDI with. The specified directory should contain an `etc/` subdirectory if `confext` is selected. If `sysext` is selected it should contain either a `usr/` or `opt/` directory, or both. If `portable` is used a full OS file hierarchy can be provided. This option implies `--empty=create`, `--size=auto` and `--seed=random` (the latter two can be overridden). The private key and certificate for signing the DDI must be specified via the `--private-key=` and `--certificate=` switches. `-S`; `-C`; `-P` Shortcuts for `--make-ddi=sysext`, `--make-ddi=confext`, `--make-ddi=portable`, respectively. `--append-fstab=` Takes one of `no`, `auto` or `replace`. Controls how the generated `fstab(5)` file by `--generate-fstab=` will behave in case that there is a previously existing file. If `no` `systemd-repart` will complain and abort in case that there is a file. This is the default behaviour. If `replace` the file will be silently replaced with the new generated one. If `auto` `systemd-repart` will search in the pre-existing file the section that belong to the automatically generated content and will replace it with the newer generated content, and keep the user provided section if there is one. The generated section is identified looking for the automatic content surrounded by `# Start section ↓ of automatically generated fstab by systemd-repart` and `# End section ↑ of automatically generated fstab by systemd-repart`. The content that is before and after those comments are considered user provided, and kept in the new file. `--generate-fstab=PATH` Specifies a path where to write `fstab(5)` entries for the mountpoints configured with `MountPoint=` in the root directory specified with `--copy-source=` or `--root=` or in the host's root directory if neither is specified. Disabled by default. `--generate-crypttab=PATH` Specifies a path where to write crypttab entries for the encrypted volumes configured with `EncryptedVolume=` in the root directory specified with `--copy-source=` or `--root=` or in the host's root directory if neither is specified. Disabled by default. `--list-devices` Show a list of candidate block devices this command may operate on. Specifically, this enumerates block devices currently present that support partition tables, and shows their device node paths along with any of their symlinks. `--el-torito=BOOL` Write a minimal ISO9660 header with El Torito boot catalog. That will boot the ESP on EFI firmware. The ISO9660 filesystem created by it will be empty. The initramfs is expected to create a partitionable loop device on top of the device to change the block size and enable GPT partitions. The disk requires at least one partition with `Type=esp`. The first one will be the one referenced in the boot catalog. `--el-torito-system=STRING` When creating an ISO9660 header, this value will be used as the system identifier. This is useful for the media to be matched against osinfo db. The value is limited to 32 characters. `--el-torito-volume=STRING` When creating an ISO9660 header, this value will be used as volume identifier. This is useful for the media to be matched against osinfo db. The value is limited to 32 characters. `--el-torito-publisher=STRING` When creating an ISO9660 header, this value will be used as publisher identifier. This is useful for the media to be matched against osinfo db. The value is limited to 128 characters. # Environment `$SOURCE_DATE_EPOCH` Takes a UNIX timestamp in seconds. Clamps access and modification times written into the image. See the [reproducible builds specification](https://reproducible-builds.org/specs/source-date-epoch/). Byte-for-byte reproducible images require `--offline=yes` mode. Populating a file system through the kernel writes metadata that cannot be corrected from userspace afterwards. `Format=``vfat` images have additional noise: the directory entry of the volume label is written with a wallclock timestamp by `mkfs.fat(8)` with dosfstools versions up to and including 4.2. A later release or a backport of the [upstream fix](https://github.com/dosfstools/dosfstools/commit/8da7bc93315c) sets it to `$SOURCE_DATE_EPOCH`. Offline and online mode also write `vfat` short names differently, so images built in both ways never match each other. # Exit status On success, 0 is returned, and a non-zero failure code otherwise. # Example
Generate a configuration extension image
The following creates a configuration extension DDI (confext) for an `/etc/motd` update: mkdir -p tree/etc/extension-release.d echo "Hello World" >tree/etc/motd cat >tree/etc/extension-release.d/extension-release.my-motd <
Generate a system extension image and sign it via PKCS11
The following creates a system extension DDI (sysext) for an `/usr/foo` update and signs it with a hardware token via PKCS11: mkdir -p tree/usr/lib/extension-release.d echo "Hello World" >tree/usr/foo cat >tree/usr/lib/extension-release.d/extension-release.my-foo <
Generate a dm-verity signature offline and append it to a pre-built image
The following creates an image with dm-verity metadata, signs it separately to simulate an offline signing system, and then appends the signature to the image: mkdir -p repart.d/ /tmp/tree/usr/lib/ cat >/tmp/tree/usr/lib/os-release <repart.d/10-root.conf <repart.d/11-root-verity.conf <repart.d/12-root-verity-sig.conf < /tmp/img.roothash openssl smime -sign -in /tmp/img.roothash \ -inkey verity-private-key.pem \ -signer verity-certificate.pem \ -noattr -binary -outform der \ -out /tmp/img.roothash.p7s systemd-repart --definitions repart.d \ --dry-run=no --root=/tmp/tree/ \ --join-signature="$(cat /tmp/img.roothash):/tmp/img.roothash.p7s" \ --certificate=verity-certificate.pem \ /tmp/img.raw
# See Also `systemd(1)`, `repart.d(5)`, `machine-id(5)`, `systemd-cryptenroll(1)`, `portablectl(1)`, `systemd-sysext(8)` # systemd-report-diskhealth@.service systemd systemd-report-diskhealth@.service 8 systemd-report-diskhealth@.service systemd-report-diskhealth.socket systemd-report-diskhealth Report disk identity and NVMe/ATA SMART health information as system report metrics `systemd-report-diskhealth@.service` `systemd-report-diskhealth.socket` `/usr/lib/systemd/systemd-report-diskhealth` # Description `systemd-report-diskhealth@.service` is a metrics source for `systemd-report(1)`. It reports basic identity information about the disks of the system, as well as the key health parameters of NVMe and ATA disks, by implementing the `io.systemd.Metrics` Varlink interface on a socket linked into the `/run/systemd/report/` directory. All whole-disk block devices backed by hardware are reported, i.e. partitions, loopback devices, device mapper devices and other virtual block devices, as well as drives without a medium, are skipped. Only block devices that have been fully probed by `systemd-udevd.service(8)` are considered. The metric object is the device node of the block device, for example `/dev/nvme0n1` or `/dev/sda`. No metric fields are set. The following metrics are reported for all disks. The model, vendor and serial strings are taken from the udev database, preferring information from the hardware database over the information the device reports about itself. If the block device carries no model or vendor information, the one of the PCI device of an NVMe disk or of the USB device of a USB disk is used instead. Metrics for which no information is available are omitted. `io.systemd.DiskHealth.DiskLogicalSectorSizeBytes` The logical sector size of the disk in bytes, i.e. the smallest unit the disk can be addressed in. `io.systemd.DiskHealth.DiskModel` The model name of the disk. `io.systemd.DiskHealth.DiskPhysicalSectorSizeBytes` The physical sector size of the disk in bytes, i.e. the smallest unit the disk can write without a read-modify-write cycle, as reported by the kernel. `io.systemd.DiskHealth.DiskSerial` The serial number of the disk. `io.systemd.DiskHealth.DiskSizeBytes` The size of the disk in bytes. `io.systemd.DiskHealth.DiskVendor` The vendor name of the disk. Note that ATA disks do not report a vendor, hence this metric is typically not available for them. The following metrics are reported for NVMe disks and for ATA disks. For NVMe disks they are taken from the SMART / Health Information log page, for ATA disks from the General Statistics page of the Device Statistics log. ATA disks which do not implement the Device Statistics log do not report these metrics. `io.systemd.DiskHealth.DiskPowerCycles` The number of power cycles over the lifetime of the disk. `io.systemd.DiskHealth.DiskPowerOnHours` The number of hours the disk has been powered on over its lifetime. The following metrics are reported for NVMe disks only, and are taken from the SMART / Health Information log page of the controller. If multiple namespaces are attached to the same controller, the same values are reported for all of them. `io.systemd.DiskHealth.NVMeAvailableSparePercent` The remaining spare capacity in percent. `io.systemd.DiskHealth.NVMeCriticalWarning` The critical warning bitmask. This is zero if all is well. Otherwise, bit 0 indicates that the spare capacity dropped below the threshold, bit 1 that a temperature threshold was exceeded, bit 2 that the reliability is degraded due to media errors, bit 3 that the media has been placed in read-only mode, bit 4 that a volatile memory backup device failed, and bit 5 that the persistent memory region has become read-only. `io.systemd.DiskHealth.NVMeMediaErrors` The number of unrecovered data integrity errors over the lifetime of the disk. `io.systemd.DiskHealth.NVMePercentageUsed` The vendor specific estimate of the used up life time of the disk in percent. Note that this value may exceed 100. The following metrics are reported for ATA disks with SMART enabled only. Disks attached via USB are not queried. In order not to spin up disks merely for collecting metrics, disks in standby mode are not queried either. The metrics derived from SMART attributes 5, 197 and 198 are only reported for rotating disks (as indicated by the `queue/rotational` sysfs attribute), since various SSD vendors have reused these attributes for flash specific concepts with incompatible semantics. `io.systemd.DiskHealth.ATAOfflineUncorrectable` The number of uncorrectable sectors found during offline scans (SMART attribute 198). `io.systemd.DiskHealth.ATAPendingSectors` The number of unstable sectors waiting to be remapped (SMART attribute 197). `io.systemd.DiskHealth.ATAReallocatedSectors` The number of sectors remapped to the spare area (SMART attribute 5). `io.systemd.DiskHealth.ATASmartStatusFailing` 1 if the overall SMART status of the disk reports that a threshold has been exceeded, i.e. that failure of the disk is predicted, 0 otherwise. The disk temperature is not reported by this service, see `systemd-report-hwmon@.service(8)` for that. # See Also `systemd(1)`, `systemd-report(1)`, `systemd-report-hwmon@.service(8)`, `systemd-udevd.service(8)` # systemd-report-diskspace@.service systemd systemd-report-diskspace@.service 8 systemd-report-diskspace@.service systemd-report-diskspace.socket systemd-report-diskspace Report size and free disk space of mounted file systems as system report metrics `systemd-report-diskspace@.service` `systemd-report-diskspace.socket` `/usr/lib/systemd/systemd-report-diskspace` # Description `systemd-report-diskspace@.service` is a metrics source for `systemd-report(1)`. It reports the size of the mounted file systems and how much disk space is still available on them, by implementing the `io.systemd.Metrics` Varlink interface on a socket linked into the `/run/systemd/report/` directory. All mount points of the system are enumerated. Mount points of file systems that are not backed by a block device (i.e. pseudo file systems such as `proc`, `sysfs` or `tmpfs`, network file systems, `overlay`, …) are skipped, as are read-only mount points. For each remaining mount point two gauge metrics are reported, with the mount point path as metric object: `io.systemd.DiskSpace.SizeBytes` The total size of the file system, in bytes. This matches the `1K-blocks` column of `df(1)` (scaled to bytes). `io.systemd.DiskSpace.FreeBytes` The disk space still available to unprivileged users on the file system, in bytes. This matches the `Avail` column of `df(1)`, i.e. space reserved for the superuser (as many file systems do) is not counted as free. The following metric fields are set on both metrics: `fileSystemType` The file system type, for example `ext4` or `btrfs`. Always set. `source` The mount source, typically the device node the file system is mounted from, for example `/dev/sda1`. Omitted if unknown. `originatingSource` If the block device the file system is mounted from is a stacked one (for example a LUKS or other device mapper volume), the device node of the block device it ultimately originates from, for example `/dev/sda2` for a file system mounted from `/dev/mapper/root`. Omitted if the source is not a stacked block device, or its origin cannot be determined. Note that stacked devices backed by multiple block devices (e.g. RAID) are not covered by this. A file system that is mounted multiple times (for example via bind mounts, or as multiple subvolumes of the same volume) is reported only once, under the shortest of its mount point paths (and among equally long ones, the alphabetically first). Mount points that are shadowed by another mount on top of them, or that the service cannot access, are not considered. # See Also `systemd(1)`, `systemd-report(1)`, `df(1)`, `statfs(2)` # systemd-report-files@.service systemd systemd-report-files@.service 8 systemd-report-files@.service systemd-report-files.socket systemd-report-files Report the contents of files as system report metrics `systemd-report-files@.service` `systemd-report-files.socket` `/usr/lib/systemd/systemd-report-files` # Description `systemd-report-files@.service` is a metrics source for `systemd-report(1)`. It reports the contents of a configurable set of files as metrics, by implementing the `io.systemd.Metrics` Varlink interface on a socket linked into the `/run/systemd/report/` directory. The files to report are picked up from `report.files/` subdirectories of the usual configuration directories, i.e. from `/etc/systemd/report.files/`, `/run/systemd/report.files/`, `/var/lib/systemd/report.files/`, `/usr/local/lib/systemd/report.files/` and `/usr/lib/systemd/report.files/`. Typically these directories contain symlinks pointing to the actual files in the file system whose contents shall be reported. Entries with the same name in an earlier directory override those in a later one. An entry that is a symlink to `/dev/null` masks the identically named entries in later directories, so that no metric is reported for that name. Entries that are not regular files are ignored. Each entry is reported as a metric named `io.systemd.Files.NAME`, where \ is the name of the entry (which must be a valid metric field name). The metric value is the verbatim contents of the file. Files that cannot be read (for example because a symlink is dangling) are skipped, as are files whose contents are not valid UTF-8 text. Note that access to this service is unprivileged, but it runs privileged. This means take care when symlinking files into the various `report.files/` directories: this service might provide read access even if the client does not have the required direct access rights itself. # See Also `systemd(1)`, `systemd-report(1)` # systemd-report-geoip@.service systemd systemd-report-geoip@.service 8 systemd-report-geoip@.service systemd-report-geoip.socket systemd-report-geoip Report the approximate geographic location of the system as a metric `systemd-report-geoip@.service` `systemd-report-geoip.socket` `/usr/lib/systemd/systemd-report-geoip` # Description `systemd-report-geoip@.service` is a metrics source for `systemd-report(1)`. It reports the approximate geographic location of the system, as determined by a public IP geolocation web service from the public IP address the system connects to it with. It implements the `io.systemd.Metrics` Varlink interface on a socket linked into the `/run/systemd/report/` directory. The geolocation data is acquired via HTTP from the endpoint configured in `report-geoip.conf(5)`. The acquired data is cached, and only refreshed once the cache is older than the configured `RefreshSec=` interval. If the endpoint cannot be reached, the cached data is reported even if it is older than that. If no data is available at all, no metrics are reported. # Metrics The following metrics are reported, all in the `io.systemd.GeoIP.` namespace. Fields the geolocation service does not provide are not reported. `io.systemd.GeoIP.PublicAddress` The public IP address of the system, as seen by the geolocation service. The address is validated and reported in normalized form. `io.systemd.GeoIP.ASN`; `io.systemd.GeoIP.ASName`; `io.systemd.GeoIP.ASDomain` The Autonomous System Number (e.g. `AS3320`) of the network the public IP address belongs to, and the name and domain of the organization operating it. `io.systemd.GeoIP.ContinentCode`; `io.systemd.GeoIP.ContinentName` The code (e.g. `EU`) and the name of the continent the system is located in. `io.systemd.GeoIP.CountryCode`; `io.systemd.GeoIP.CountryName` The ISO 3166-1 alpha-2 code and the name of the country the system is located in. `io.systemd.GeoIP.RegionCode`; `io.systemd.GeoIP.RegionName` The code and name of the region (state, province, …) the system is located in. `io.systemd.GeoIP.City`; `io.systemd.GeoIP.ZipCode` The city and postal code of the area the system is located in. `io.systemd.GeoIP.Timezone` The IANA time zone name of the area the system is located in. `io.systemd.GeoIP.Latitude`; `io.systemd.GeoIP.Longitude` The geographic coordinates of the system's location, in decimal degrees. `io.systemd.GeoIP.Timestamp` The time at which the reported data was acquired from the geolocation service, in microseconds since the UNIX epoch (`CLOCK_REALTIME`). When the data is served from the cache this is the time the cache was last refreshed, not the time of the report. # Privacy Note that refreshing the geolocation data means contacting a third party web service, which thereby learns the public IP address of the system. The reported metrics identify the system's public IP address and approximate location, and hence are sensitive. Only enable this service if this is acceptable for the systems the reports are collected from. # See Also `systemd(1)`, `systemd-report(1)`, `report-geoip.conf(5)` # systemd-report-hwmon@.service systemd systemd-report-hwmon@.service 8 systemd-report-hwmon@.service systemd-report-hwmon.socket systemd-report-hwmon Report hardware monitoring temperature sensor readings as system report metrics `systemd-report-hwmon@.service` `systemd-report-hwmon.socket` `/usr/lib/systemd/systemd-report-hwmon` # Description `systemd-report-hwmon@.service` is a metrics source for `systemd-report(1)`. It reports the current readings of the temperature sensors exposed by the kernel's hardware monitoring (`hwmon`) subsystem, by implementing the `io.systemd.Metrics` Varlink interface on a socket linked into the `/run/systemd/report/` directory. All devices of the `hwmon` subsystem are enumerated, and for each of their `tempN_input` attributes one `io.systemd.HWMon.TemperatureCelsius` gauge metric is reported, with the current temperature in degrees Celsius as value. The metric object is the name of the device the hwmon chip belongs to (for example `coretemp.0`, `nvme0` or `thermal_zone0`). The following metric fields are set: `chip` The name of the hwmon chip, i.e. the contents of its `name` attribute, for example `coretemp` or `nvme`. Omitted if the attribute cannot be read. `sensor` The sensor name within the chip, i.e. `tempN`. Always set. `label` The human readable sensor label, i.e. the contents of the `tempN_label` attribute, for example `Package id 0`. Omitted if the sensor carries no label. # See Also `systemd(1)`, `systemd-report(1)`, [Naming and data format standards for sysfs files](https://docs.kernel.org/hwmon/sysfs-interface.html) # systemd-report-netstat@.service systemd systemd-report-netstat@.service 8 systemd-report-netstat@.service systemd-report-netstat.socket systemd-report-netstat Report network interface statistics as system report metrics `systemd-report-netstat@.service` `systemd-report-netstat.socket` `/usr/lib/systemd/systemd-report-netstat` # Description `systemd-report-netstat@.service` is a metrics source for `systemd-report(1)`. It reports traffic counters and related properties of the network interfaces of the host, by implementing the `io.systemd.Metrics` Varlink interface on a socket linked into the `/run/systemd/report/` directory. All network interfaces of the host's network namespace are enumerated, including the loopback interface. The data is acquired from the kernel via `rtnetlink(7)`, except for the link speed, see below. Note that this service is independent of `systemd-networkd.service(8)`, and reports on all interfaces, regardless of which component manages them. For each interface the following metrics are reported, with the interface name as metric object: `io.systemd.NetworkStatistics.CarrierChanges` The number of times the carrier state of the interface changed (counter). `io.systemd.NetworkStatistics.Collisions` The number of collisions during packet transmission (counter). `io.systemd.NetworkStatistics.MTU` The maximum transmission unit of the interface, in bytes (gauge). `io.systemd.NetworkStatistics.ReceiveBytes` The number of bytes received (counter). `io.systemd.NetworkStatistics.ReceiveDropped` The number of received packets that were dropped without an error, for example due to lack of buffer space (counter). `io.systemd.NetworkStatistics.ReceiveErrors` The total number of receive errors (counter). `io.systemd.NetworkStatistics.ReceiveMulticastPackets` The number of multicast packets received (counter). `io.systemd.NetworkStatistics.ReceivePackets` The number of packets received (counter). `io.systemd.NetworkStatistics.SpeedBitsPerSecond` The link speed, in bits per second. Only reported for interfaces whose driver reports a link speed and that are up and have a known speed, which typically means wired Ethernet interfaces. The value is read from the `speed` attribute of the interface in `/sys/class/net/` (gauge). `io.systemd.NetworkStatistics.TransmitBytes` The number of bytes transmitted (counter). `io.systemd.NetworkStatistics.TransmitDropped` The number of packets dropped on transmission without an error (counter). `io.systemd.NetworkStatistics.TransmitErrors` The total number of transmit errors (counter). `io.systemd.NetworkStatistics.TransmitPackets` The number of packets transmitted (counter). `io.systemd.NetworkStatistics.TransmitQueueLength` The length of the transmit queue of the interface, in packets (gauge). Counters are maintained by the kernel per interface, and hence start from zero whenever an interface is (re-)created. The following metric fields are set on all metrics: `ifindex` The interface index, in decimal. Always set. `type` The type of the interface, as also shown in the `Type` column of `networkctl(1)`, i.e. the device type if the kernel reports one (for example `wlan` or `bridge`), and the hardware type otherwise (for example `ether` or `loopback`). Omitted if not known. `kind` The kind of the interface, for virtual interfaces, for example `veth`, `bridge` or `wireguard`. Omitted for physical interfaces. # See Also `systemd(1)`, `systemd-report(1)`, `systemd-networkd.service(8)`, `rtnetlink(7)` # systemd-report-sign-plain@.service systemd systemd-report-sign-plain@.service 8 systemd-report-sign-plain@.service systemd-report-sign-plain.socket systemd-report-sign-plain Sign system reports with a local software key `systemd-report-sign-plain@.service` `systemd-report-sign-plain.socket` `/usr/lib/systemd/systemd-report-sign-plain` # Description `systemd-report-sign-plain@.service` is a system service that signs system reports generated by `systemd-report(1)`. It is a signing backend for the `--sign=` logic of that tool: it implements the `io.systemd.Report.Signer.Sign()` Varlink method and is reached via a socket linked into the `/run/systemd/report.sign/` directory, named `plain`. The service is socket-activated (one instance per connection) via `systemd-report-sign-plain.socket`, and signs the digest passed to it with a local software key. Signatures are made with the Ed25519 (EdDSA) algorithm. On first use a key pair is generated automatically and stored below `/var/lib/systemd/report.sign.plain/`: the private key in `local.private` (PKCS#8 PEM, readable only by the root user) and the public key in `local.public` (PEM, world readable). The public key is also exported as a system report metric. # See Also `systemd(1)`, `systemd-report(1)` # systemd-report-sign-tpm2@.service systemd systemd-report-sign-tpm2@.service 8 systemd-report-sign-tpm2@.service systemd-report-sign-tpm2.socket systemd-report-sign-tpm2 Sign system reports with a set of signed TPM2 attestations `systemd-report-sign-tpm2@.service` `systemd-report-sign-tpm2.socket` `/usr/lib/systemd/systemd-report-sign-tpm2` # Description `systemd-report-sign-tpm2@.service` is a system service that signs system reports generated by `systemd-report(1)`. It is a signing backend for the `--sign=` logic of that tool: it implements the `io.systemd.Report.Signer.Sign()` Varlink method and is reached via a socket linked into the `/run/systemd/report.sign/` directory, named `tpm2`. The service is socket-activated (one instance per connection) via `systemd-report-sign-tpm2.socket`. Rather than returning a single signature, it uses a TPM2 device to generate a set of signed attestations that also bind the report digest passed to it, together providing a verifier with evidence about the state of the system that produced the report. The returned report consists of several components. Some of these carry a JSON encoded attestation structure (`TPMS_ATTEST`) and its corresponding signature. The signature is provided as a JSON encoded `TPMT_SIGNATURE` structure and in PEM encoded form. The components are: - A PCR quote, generated with `TPM2_Quote`. This contains the JSON encoded attestation and the corresponding signature. - One attestation per NvPCR, generated with `TPM2_NV_Certify`. Each of these contain the JSON encoded attestation structure and its signature. In addition to this, each one also includes the readable name of the NvPCR, the NV index public area (as a JSON encoded `TPMS_NV_PUBLIC` structure), and a JSON blob of authenticated data (the NvPCR name and priority) that is digested and supplied as the qualifying data to the certify command. - A certification of the TPM's storage root key (SRK), generated with `TPM2_Certify`. This contains the JSON encoded attestation and the corresponding signature. The component also includes the public area of the SRK, as a JSON encoded `TPMT_PUBLIC` structure. Marshalled into a `TPM2B_PUBLIC` structure, this is the format accepted by the `--tpm2-device-key=` switch of `systemd-cryptenroll(1)` and `systemd-repart(8)`. The certification proves to a verifier that the SRK resides in the same TPM as the attestation key, so that secrets sealed to it, sealing to which requires no access to the TPM, can only be unsealed by the reporting system. As `TPM2_Clear` replaces the SRK, a certification of the same SRK in a later report is also evidence that the TPM has not been cleared in between. If no SRK exists yet, one is created and persisted at the usual handle, which requires the authorization value of the TPM's owner hierarchy to be empty. If the SRK cannot be acquired, or the object at its handle cannot be authorized with an empty password, the report is generated without this component. The same applies if the object lacks the `noDA` attribute, as a failed authorization attempt would then count towards the TPM's dictionary attack protection. Checking that the attributes of the certified key are those of a storage key that cannot leave the TPM is up to the verifier. - One component per reported TPM property, generated with `TPM2_GetCapability`. Each of these contain the property and its value as a JSON encoded `TPMS_TAGGED_PROPERTY` structure, as well as a boolean indicating the value of the `moreData` parameter returned from the TPM. These components contain no signature of their own, but the response is included in the audit session digest. - One component per reported TPM permanent handle authorization policy, generated with `TPM2_GetCapability`. Each of these contain the handle, the policy digest algorithm, and the policy digest (if the algorithm is not NULL) as a JSON encoded `TPMS_TAGGED_POLICY` structure, as well as a boolean indicating the value of the `moreData` parameter returned from the TPM. These components contain no signature of their own, but the response is included in the audit session digest. Note that these components are omitted on TPMs that don't support `TPM_CAP_AUTH_POLICIES`. - An audit session attestation, generated with `TPM2_GetSessionAuditDigest`. This is always the last component. The report digest passed in via Varlink is supplied as its qualifying data. All other components are generated using this audit session. The report additionally includes the measurement event log, and the public area of the signing key. The public area is provided as a JSON encoded `TPMT_PUBLIC` structure, and in PEM encoded form. The preceding components are all executed under the audit session, and the report is only generated if that session remains exclusive throughout. Because the audit session attestation records whether the session was still exclusive when it was signed, this provides evidence to a verifier that the report is a single, consistent snapshot of the system, with no other TPM commands interleaved while it was generated. The set of attested PCRs, NvPCRs, TPM properties and permanent handle authorization policies is currently fixed. It covers all firmware PCRs except PCR 6, all other S-RTM PCRs except the IMA PCR (which is not useful without the IMA log), all defined NvPCRs, the TPM_PT_PERMANENT, TPM_PT_MAX_AUTH_FAIL, TPM_PT_LOCKOUT_INTERVAL and TPM_PT_LOCKOUT_RECOVERY TPM properties, and the authorization policies for the storage, endorsement and lockout hierarchies. Note that authorization policies are omitted on TPMs that don't support `TPM_CAP_AUTH_POLICIES` # Signing key The attestation signing key is stored as a JSON file named `default.key` in `/var/lib/systemd/report.sign.tpm2/`. Three kinds of key are supported: an ordinary object protected by an existing persistent object such as the SRK or EK, a persistent object, and a primary object that is recreated from a template on each use. In all cases the key must be a restricted signing key. If no key exists, an ordinary key is generated automatically on first use. For ordinary and primary keys, the loaded object context is cached in the service's runtime directory as `/run/systemd/report.sign.tpm2/default.context` and reused on subsequent invocations, avoiding a repeated `TPM2_Load` (which requires authorization with the parent key) or primary key recreation. The key may optionally have an associated *voucher*, stored alongside it as `default.voucher`. This is an opaque credential — for example one issued by a CA during onboarding — that is attached to the signed report and presented to a verifier as proof that the attestation key is authentic. It is deliberately not required to be any particular format (such as an X.509 certificate). # See Also `systemd(1)`, `systemd-report(1)` # systemd-report-sign-tsm@.service systemd systemd-report-sign-tsm@.service 8 systemd-report-sign-tsm@.service systemd-report-sign-tsm.socket systemd-report-sign-tsm Sign system reports with a confidential-computing attestation report `systemd-report-sign-tsm@.service` `systemd-report-sign-tsm.socket` `/usr/lib/systemd/systemd-report-sign-tsm` # Description `systemd-report-sign-tsm@.service` is a system service that signs system reports generated by `systemd-report(1)`. It is a signing backend for the `--sign=` logic of that tool: it implements the `io.systemd.Report.Signer.Sign()` Varlink method and is reached via a socket linked into the `/run/systemd/report.sign/` directory, named `tsm`. The service is socket-activated (one instance per connection) via `systemd-report-sign-tsm.socket`. Rather than signing with a local key, it obtains a hardware-backed attestation report from the platform's Trusted Security Module (TSM) through the kernel's configfs-TSM interface at `/sys/kernel/config/tsm/report/`. The digest passed to it is embedded into the report as its run-time provided data (`inblob`), cryptographically binding the attestation report to the system report being signed. The returned signature carries the binary attestation report (the `outblob`), the name of the TSM provider that generated it (for example `sev_guest` for AMD SEV-SNP or `tdx_guest` for Intel TDX), and, where the provider supplies them, supplemental certificate (`auxblob`) and manifest (`manifestblob`) data. A verifier selects the appropriate validation logic based on the provider field. This backend is only functional inside a confidential virtual machine whose kernel exposes the configfs-TSM interface (such as AMD SEV-SNP or Intel TDX guests). On systems where the interface is unavailable the signing operation is reported as unsupported and the mechanism is skipped. The service keeps no persistent state. # See Also `systemd(1)`, `systemd-report(1)` # systemd-resolved.service systemd systemd-resolved.service 8 systemd-resolved.service systemd-resolved Network Name Resolution manager `systemd-resolved.service` `/usr/lib/systemd/systemd-resolved` # Description `systemd-resolved` is a system service that provides network name resolution to local applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR and MulticastDNS resolver and responder. Local applications may submit network name resolution requests via three interfaces: - The native, fully-featured API `systemd-resolved` exposes via D-Bus, see `org.freedesktop.resolve1(5)` and `org.freedesktop.LogControl1(5)` for details. Usage of this API is generally recommended to clients as it is asynchronous and fully featured (for example, properly returns DNSSEC validation status and interface scope for addresses as necessary for supporting link-local networking). - The native API `systemd-resolved` exposes via Varlink on the `/run/systemd/resolve/io.systemd.Resolve` AF_UNIX socket. This provides similar functionality as the D-Bus interface, but is available during the entire runtime, without requiring a running D-Bus system bus broker service. - The glibc `getaddrinfo(3)` API as defined by [RFC3493](https://tools.ietf.org/html/rfc3493) and its related resolver functions, including `gethostbyname(3)`. This API is widely supported, including beyond the Linux platform. In its current form it does not expose DNSSEC validation status information however, and is synchronous only. This API is backed by the glibc Name Service Switch (`nss(5)`). Usage of the glibc NSS module `nss-resolve(8)` is required in order to allow glibc's NSS resolver functions to resolve hostnames via `systemd-resolved`. - Additionally, `systemd-resolved` provides a local DNS stub listener on the IP addresses 127.0.0.53 and 127.0.0.54 on the local loopback interface. Programs issuing DNS requests directly, bypassing any local API may be directed to this stub, in order to connect them to `systemd-resolved`. Note however that it is strongly recommended that local programs use the glibc NSS or bus APIs instead (as described above), as various network resolution concepts (such as link-local addressing, or LLMNR Unicode domains) cannot be mapped to the unicast DNS protocol. The DNS stub resolver on 127.0.0.53 provides the full feature set of the local resolver, which includes offering LLMNR/MulticastDNS resolution. The DNS stub resolver on 127.0.0.54 provides a more limited resolver, that operates in "proxy" mode only, i.e. it will pass most DNS messages relatively unmodified to the current upstream DNS servers and back, but not try to process the messages locally, and hence does not validate DNSSEC, or offer up LLMNR/MulticastDNS. (It will translate to DNS-over-TLS communication if needed however.) The DNS servers contacted are determined from the global settings in `/etc/systemd/resolved.conf`, the per-link static settings in `/etc/systemd/network/*.network` files (in case `systemd-networkd.service(8)` is used), the per-link dynamic settings received over DHCP, information provided via `resolvectl(1)`, and any DNS server information made available by other system services. See `resolved.conf(5)` and `systemd.network(5)` for details about systemd's own configuration files for DNS servers. To improve compatibility, `/etc/resolv.conf` is read in order to discover configured system DNS servers, but only if it is not a symlink to `/run/systemd/resolve/stub-resolv.conf`, `/usr/lib/systemd/resolv.conf` or `/run/systemd/resolve/resolv.conf` (see below). # Synthetic Records `systemd-resolved` synthesizes DNS resource records (RRs) for the following cases: - The local, configured hostname is resolved to all locally configured IP addresses ordered by their scope, or — if none are configured — the IPv4 address 127.0.0.2 (which is on the local loopback interface) and the IPv6 address ::1 (which is the local host). - The hostnames `localhost` and `localhost.localdomain` as well as any hostname ending in `.localhost` or `.localhost.localdomain` are resolved to the IP addresses 127.0.0.1 and ::1. - The hostname `_gateway` is resolved to all current default routing gateway addresses, ordered by their metric. This assigns a stable hostname to the current gateway, useful for referencing it independently of the current network configuration state. - The hostname `_outbound` is resolved to the local IPv4 and IPv6 addresses that are most likely used for communication with other hosts. This is the preferred source addresses of default gateways if specified, or determined by requesting a routing decision to the configured default gateways from the kernel and then using the local IP addresses selected by this decision. This hostname is only available if there is at least one local default gateway configured. This assigns a stable hostname to the local outbound IP addresses, useful for referencing them independently of the current network configuration state. - The hostname `_localdnsstub` is resolved to the IP address 127.0.0.53, i.e. the address the local DNS stub (see above) is listening on. - The hostname `_localdnsproxy` is resolved to the IP address 127.0.0.54, i.e. the address the local DNS proxy (see above) is listening on. - The files matching `/etc/systemd/resolve/static.d/*.rr`, `/run/systemd/resolve/static.d/*.rr`, `/usr/local/lib/systemd/resolve/static.d/*.rr`, `/usr/lib/systemd/resolve/static.d/*.rr` may be used to define arbitrary records. See `systemd.rr(5)` for details. Support for this may be disabled with `ReadStaticRecords=no`, see `resolved.conf(5)`. - The mappings defined in `/etc/hosts` are resolved to their configured addresses and back, but they will not affect lookups for non-address types (like MX). Support for `/etc/hosts` may be disabled with `ReadEtcHosts=no`, see `resolved.conf(5)`. # Protocols and Routing The lookup requests that `systemd-resolved.service` receives are routed to the available DNS servers, LLMNR, and MulticastDNS interfaces according to the following rules: - Names for which synthetic records are generated (the local hostname, `localhost` and `localdomain`, local gateway, as listed in the previous section) and addresses configured in `/etc/hosts` are never routed to the network and a reply is sent immediately. - Single-label names are resolved using LLMNR on all local interfaces where LLMNR is enabled. Lookups for IPv4 addresses are only sent via LLMNR on IPv4, and lookups for IPv6 addresses are only sent via LLMNR on IPv6. Note that lookups for single-label synthesized names are not routed to LLMNR, MulticastDNS or unicast DNS. - Queries for the address records (A and AAAA) of single-label non-synthesized names are resolved via unicast DNS using search domains. For any interface which defines search domains, such look-ups are routed to the servers defined for that interface, suffixed with each of those search domains. When global search domains are defined, such look-ups are routed to the global servers. For each search domain, queries are performed by suffixing the name with each of the search domains in turn. Additionally, lookup of single-label names via unicast DNS may be enabled with the `ResolveUnicastSingleLabel=yes` setting. The details of which servers are queried and how the final reply is chosen are described below. Note that this means that address queries for single-label names are never sent out to remote DNS servers by default, and resolution is only possible if search domains are defined. - Multi-label names with the domain suffix `.local` are resolved using MulticastDNS on all local interfaces where MulticastDNS is enabled. As with LLMNR, IPv4 address lookups are sent via IPv4 and IPv6 address lookups are sent via IPv6. - Queries for multi-label names are routed via unicast DNS on local interfaces that have a DNS server configured, plus the globally configured DNS servers if there are any. Which interfaces are used is determined by the routing logic based on search and route-only domains, described below. Note that by default, lookups for domains with the `.local` suffix are not routed to DNS servers, unless the domain is specified explicitly as routing or search domain for the DNS server and interface. This means that on networks where the `.local` domain is defined in a site-specific DNS server, explicit search or routing domains need to be configured to make lookups work within this DNS domain. Note that these days, it is generally recommended to avoid defining `.local` in a DNS server, as [RFC6762](https://tools.ietf.org/html/rfc6762) reserves this domain for exclusive MulticastDNS use. - Address lookups (reverse lookups) are routed similarly to multi-label names, with the exception that addresses from the link-local address range are never routed to unicast DNS and are only resolved using LLMNR and MulticastDNS (when enabled). If lookups are routed to multiple interfaces, the first successful response is returned (thus effectively merging the lookup zones on all matching interfaces). If the lookup failed on all interfaces, the last failing response is returned. Routing of lookups is determined by the per-interface routing domains (search and route-only) and global search domains. See `systemd.network(5)` and `resolvectl(1)` for a description how those settings are set dynamically and the discussion of `Domains=` in `resolved.conf(5)` for a description of globally configured DNS settings. The following query routing logic applies for unicast DNS lookups initiated by `systemd-resolved.service`: - If a name to look up matches (that is: is equal to or has as suffix) any of the configured routing domains (search or route-only) of any link, or the globally configured DNS settings, "best matching" routing domain is determined: the matching one with the most labels. The query is then sent to all DNS servers of any links or the globally configured DNS servers associated with this "best matching" routing domain. (Note that more than one link might have this same "best matching" routing domain configured, in which case the query is sent to all of them in parallel). In case of single-label names, when search domains are defined, the same logic applies, except that the name is first suffixed by each of the search domains in turn. Note that this search logic does not apply to any names with at least one dot. Also see the discussion about compatibility with the traditional glibc resolver below. - If a query does not match any configured routing domain (either per-link or global), it is sent to all DNS servers that are configured on links configured as the default route, as well as the globally configured DNS server. - If there are no DNS servers configured on any link also configured as the default route and no global DNS server configured, one of the compiled-in fallback DNS servers is used. - Otherwise, the unicast DNS query fails, as no suitable DNS servers can be determined. Whether a link is the default route or not can be configured with `resolvectl default-route` command or `DNSDefaultRoute=` setting in `.network` files. If not configured explicitly, it is implicitly determined based on the configured DNS domains for a link: if there's a route-only domain other than `~.`, it defaults to false, otherwise to true. Effectively this means: in order to support single-label non-synthesized names, define appropriate search domains. In order to preferably route all DNS queries not explicitly matched by routing domain configuration to a specific link, configure a `~.` route-only domain on it. This will ensure that other links will not be considered for these queries (unless they too carry such a routing domain). In order to route all such DNS queries to a specific link only if no other link is preferred, configure the link as the default route and do not configure a `~.` route-only domain on it. Finally, in order to avoid a specific link receiving any DNS traffic not matching any of its configured routing domains, do not make it a default route. See `org.freedesktop.resolve1(5)` for information about the D-Bus APIs `systemd-resolved` provides. # Compatibility with the traditional glibc stub resolver This section provides a short summary of differences in the resolver implemented by `nss-resolve(8)` together with `systemd-resolved` and the traditional stub resolver implemented in `nss-dns`. - Some names are always resolved internally (see Synthetic Records above). Traditionally they would be resolved by `nss-files` if provided in `/etc/hosts`. But note that the details of how a query is constructed are under the control of the client library. `nss-dns` will first try to resolve names using search domains and even if those queries are routed to `systemd-resolved`, it will send them out over the network using the usual rules for multi-label name routing [^1]. - Single-label names are not resolved for A and AAAA records using unicast DNS (unless overridden with `ResolveUnicastSingleLabel=`, see `resolved.conf(5)`). This is similar to the `no-tld-query` option being set in `resolv.conf(5)`. - Search domains are not used for *suffixing* of multi-label names. (Search domains are nevertheless used for lookup *routing*, for names that were originally specified as single-label or multi-label.) Any name with at least one dot is always interpreted as a FQDN. `nss-dns` would resolve names both as relative (using search domains) and absolute FQDN names. Some names would be resolved as relative first, and after that query has failed, as absolute, while other names would be resolved in opposite order. The `ndots` option in `/etc/resolv.conf` was used to control how many dots the name needs to have to be resolved as relative first. This stub resolver does not implement this at all: multi-label names are only resolved as FQDNs.[^2] - This resolver has a notion of the special `.local` domain used for MulticastDNS, and will not route queries with that suffix to unicast DNS servers unless explicitly configured, see above. Also, reverse lookups for link-local addresses are not sent to unicast DNS servers. - This resolver reads and caches `/etc/hosts` internally. (In other words, `nss-resolve` replaces `nss-files` in addition to `nss-dns`). Entries in `/etc/hosts` have highest priority. - This resolver also implements LLMNR and MulticastDNS in addition to the classic unicast DNS protocol, and will resolve single-label names using LLMNR (when enabled) and names ending in `.local` using MulticastDNS (when enabled). - Environment variables `$LOCALDOMAIN` and `$RES_OPTIONS` described in `resolv.conf(5)` are not supported currently. - The `nss-dns` resolver maintains little state between subsequent DNS queries, and for each query always talks to the first listed DNS server from `/etc/resolv.conf` first, and on failure continues with the next until reaching the end of the list which is when the query fails. The resolver in `systemd-resolved` however maintains state, and will continuously talk to the same server for all queries in a particular lookup scope until some form of error is seen at which point it will switch to the next server, and then stay with it for all queries on the scope until the next failure, and so on, eventually returning to the first configured server. This is done to optimize lookup times, in particular given that the resolver typically must first probe server feature sets when talking to a server, which takes time. This different behaviour implies that listed DNS servers per lookup scope must be equivalent in the zones they serve, so that sending a query to one of them will yield the same results as sending it to another configured DNS server. # `/etc/resolv.conf` Four modes of handling `/etc/resolv.conf` (see `resolv.conf(5)`) are supported: - `systemd-resolved` maintains the `/run/systemd/resolve/stub-resolv.conf` file for compatibility with traditional Linux programs. This file lists the 127.0.0.53 DNS stub (see above) as the only DNS server. It also contains a list of search domains that are in use by `systemd-resolved`. The list of search domains is always kept up-to-date. Note that `/run/systemd/resolve/stub-resolv.conf` should not be used directly by applications, but only through a symlink from `/etc/resolv.conf`. This file may be symlinked from `/etc/resolv.conf` in order to connect all local clients that bypass local DNS APIs to `systemd-resolved` with correct search domains settings. This mode of operation is recommended. - A static file `/usr/lib/systemd/resolv.conf` is provided that lists the 127.0.0.53 DNS stub (see above) as only DNS server. This file may be symlinked from `/etc/resolv.conf` in order to connect all local clients that bypass local DNS APIs to `systemd-resolved`. This file does not contain any search domains. - `systemd-resolved` maintains the `/run/systemd/resolve/resolv.conf` file for compatibility with traditional Linux programs. This file may be symlinked from `/etc/resolv.conf` and is always kept up-to-date, containing information about all known DNS servers. Note the file format's limitations: it does not know a concept of per-interface DNS servers and hence only contains system-wide DNS server definitions. Note that `/run/systemd/resolve/resolv.conf` should not be used directly by applications, but only through a symlink from `/etc/resolv.conf`. If this mode of operation is used local clients that bypass any local DNS API will also bypass `systemd-resolved` and will talk directly to the known DNS servers. - Alternatively, `/etc/resolv.conf` may be managed by other packages, in which case `systemd-resolved` will read it for DNS configuration data. In this mode of operation `systemd-resolved` is consumer rather than provider of this configuration file. Note that the selected mode of operation for this file is detected fully automatically, depending on whether `/etc/resolv.conf` is a symlink to `/run/systemd/resolve/resolv.conf` or lists 127.0.0.53 as DNS server. # Signals `SIGUSR1` Upon reception of the `SIGUSR1` process signal `systemd-resolved` will dump the contents of all DNS resource record caches it maintains, as well as all feature level information it learnt about configured DNS servers into the system logs. `SIGUSR2` Upon reception of the `SIGUSR2` process signal `systemd-resolved` will flush all caches it maintains. Note that it should normally not be necessary to request this explicitly – except for debugging purposes – as `systemd-resolved` flushes the caches automatically anyway any time the host's network configuration changes. Sending this signal to `systemd-resolved` is equivalent to the `resolvectl flush-caches` command, however the latter is recommended since it operates in a synchronous way. `SIGRTMIN+1` Upon reception of the `SIGRTMIN+1` process signal `systemd-resolved` will forget everything it learnt about the configured DNS servers. Specifically any information about server feature support is flushed out, and the server feature probing logic is restarted on the next request, starting with the most fully featured level. Note that it should normally not be necessary to request this explicitly – except for debugging purposes – as `systemd-resolved` automatically forgets learnt information any time the DNS server configuration changes. Sending this signal to `systemd-resolved` is equivalent to the `resolvectl reset-server-features` command, however the latter is recommended since it operates in a synchronous way. `SIGHUP` Upon reception of the `SIGHUP` process signal `systemd-resolved` will flush all caches it maintains, drop all open TCP connections (if any), and reload its configuration files. # Credentials `systemd-resolved` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `network.dns`; `network.search_domains` May contain a space separated list of DNS server IP addresses and DNS search domains. This information is only used when no explicit configuration via `/etc/systemd/resolved.conf`, `/etc/resolv.conf` or the kernel command line has been provided. # Kernel Command Line `systemd-resolved` also honours two kernel command line options: `nameserver=`; `domain=` Takes the IP address of a DNS server (in case of `nameserver=`), and a DNS search domain (in case of `domain=`). May be used multiple times, to define multiple DNS servers/search domains. If either of these options are specified `/etc/resolv.conf` will not be read and the `DNS=` and `Domains=` settings of `resolved.conf(5)` will be ignored. These two kernel command line options hence override system configuration. # IP Ports The `systemd-resolved` service listens on the following IP ports: - Port 53 on IPv4 addresses 127.0.0.53 and 127.0.0.54 (both are on the local loopback interface `lo`). This is the local DNS stub, as discussed above. Both UDP and TCP are covered. - Port 5353 on all local addresses, both IPv4 and IPv6 (0.0.0.0 and ::0), for MulticastDNS on UDP. Note that even though the socket is bound to all local interfaces via the selected "wildcard" IP addresses, the incoming datagrams are filtered by the network interface they are coming in on, and separate MulticastDNS link-local scopes are maintained for each, taking into consideration whether MulticastDNS is enabled for the interface or not. - Port 5355 on all local addresses, both IPv4 and IP6 (0.0.0.0 and ::0), for LLMNR, on both TCP and UDP. As with MulticastDNS filtering by incoming network interface is applied. # See Also `systemd(1)`, `resolved.conf(5)`, `systemd.dns-delegate(5)`, `systemd.rr(5)`, `systemd.dnssd(5)`, `dnssec-trust-anchors.d(5)`, `nss-resolve(8)`, `resolvectl(1)`, `resolv.conf(5)`, `hosts(5)`, `systemd.network(5)`, `systemd-networkd.service(8)`, `org.freedesktop.resolve1(5)` [^1]: For example, if `/etc/resolv.conf` has nameserver 127.0.0.53 search foobar.com barbar.com and we look up `localhost`, `nss-dns` will send the following queries to `systemd-resolved` listening on 127.0.0.53:53: first `localhost.foobar.com`, then `localhost.barbar.com`, and finally `localhost`. If (hopefully) the first two queries fail, `systemd-resolved` will synthesize an answer for the third query. When using `nss-dns` with any search domains, it is thus crucial to always configure `nss-files` with higher priority and provide mappings for names that should not be resolved using search domains. [^2]: There are currently more than 1500 top-level domain names defined, and new ones are added regularly, often using "attractive" names that are also likely to be used locally. Not looking up multi-label names in this fashion avoids fragility in both directions: a valid global name could be obscured by a local name, and resolution of a relative local name could suddenly break when a new top-level domain is created, or when a new subdomain of a top-level domain in registered. Resolving any given name as either relative or absolute avoids this ambiguity. # systemd-rfkill.service systemd systemd-rfkill.service 8 systemd-rfkill.service systemd-rfkill.socket systemd-rfkill Load and save the RF kill switch state at boot and change `systemd-rfkill.service` `systemd-rfkill.socket` `/usr/lib/systemd/systemd-rfkill` # Description `systemd-rfkill.service` is a service that restores the RF kill switch state at early boot and saves it on each change. On disk, the RF kill switch state is stored in `/var/lib/systemd/rfkill/`. # Kernel Command Line `systemd-rfkill` understands the following kernel command line parameter. See also `kernel-command-line(7)`. `systemd.restore_state=` Takes a boolean argument. Defaults to `1`. If `0`, does not restore the rfkill settings on boot. However, settings will still be stored on shutdown. # See Also `systemd(1)` # systemd-run-generator systemd systemd-run-generator 8 systemd-run-generator Generator for invoking commands specified on the kernel command line as system service `/usr/lib/systemd/system-generators/systemd-run-generator` # Description `systemd-run-generator` is a generator that reads the kernel command line and understands three options: If the `systemd.run=` option is specified and followed by a command line, a unit named `kernel-command-line.service` is generated for it and booted into. The service has `Type=oneshot` set, and has `SuccessAction=exit` and `FailureAction=exit` configured by default, thus ensuring that the system is shut down as soon as the command completes. The exit status of the command line is propagated to the invoking container manager, if this applies (which might propagate this further, to the calling shell — e.g. `systemd-nspawn(1)` does this). If this option is used multiple times the unit file will contain multiple `ExecStart=` lines, to execute all commands in order. The command is started as regular service, i.e. with `DefaultDependencies=` on. Use `systemd.run_success_action=` and `systemd.run_failure_action=` to tweak how to react to the process completing. In particular assigning `none` will leave the system running after the command completes. For further details on supported arguments, see `systemd.unit(5)`. `systemd-run-generator` implements `systemd.generator(7)`. # Example Use a command like the following to add a user to the user database inside a container run with `systemd-nspawn(1)`: # systemd-nspawn -D mycontainer -b systemd.run='"adduser test"' (Note the requirement for double quoting in the command line above. The first level of quoting ('') is processed and removed by the command shell used to invoke `systemd-nspawn`. The second level of quoting ("") is propagated to the kernel command line of the container and processed and removed by `systemd-run-generator`. Both together make sure both words of the specified command line `adduser test` end up in the generated unit file together and are neither split apart by the command shell nor by the generator.) # See Also `systemd(1)`, `systemctl(1)`, `kernel-command-line(7)`, `systemd-nspawn(1)`, `systemd.unit(5)`, `systemd.service(5)` # systemd-sbsign systemd systemd-sbsign 1 systemd-sbsign Sign PE binaries for EFI Secure Boot systemd-sbsign OPTIONS COMMAND # Description `systemd-sbsign` can be used to sign PE binaries for EFI Secure Boot. # Commands `sign` Signs the given PE binary for EFI Secure Boot. Takes a path to a PE binary as its argument. If the PE binary already has a certificate table, the new signature will be added to it. Otherwise, a new certificate table will be created. The signed PE binary will be written to the path specified with `--output=`. # Options The following options are understood: `--output=PATH` Specifies the path where to write the signed PE binary or the data to be signed offline when using the `--prepare-offline-signing` option. `--private-key=PATH/URI`; `--private-key-source=TYPE[:NAME]`; `--certificate=PATH`; `--certificate-source=TYPE[:NAME]` Set the Secure Boot private key and certificate for use with the `sign` verb. The `--certificate=` option takes a path to a PEM-encoded X.509 certificate or a URI that's passed to the OpenSSL provider configured with `--certificate-source=`. The `--certificate-source=` option takes one of `file` or `provider`, with the latter being followed by a specific provider identifier, separated with a colon, e.g. `provider:pkcs11`. The `--private-key=` option takes a path or a URI that will be passed to the OpenSSL engine or provider, as specified by `--private-key-source=` as a `type:name` tuple, such as `engine:pkcs11`. The specified OpenSSL signing engine or provider will be used to sign the PE binary. `--prepare-offline-signing` When this option is specified, the `sign` command writes the data that should be signed to the path specified with `--output=` instead of writing the signed PE binary. This data can then be signed out of band after which the signature can be attached to the PE binary using the `--signed-data=` and `--signed-data-signature=` options. `--signed-data=PATH`; `--signed-data-signature=PATH` Configure the signed data (as written to the path specified with `--output=` when using the `--prepare-offline-signing` option) and corresponding signature for the `sign` command. # Examples
Offline EFI secure boot signing of a PE binary
The following does offline secure boot signing of systemd-boot: SD_BOOT="$(find /usr/lib/systemd/boot/efi/ -name "systemd-boot*.efi" | head -n1)" # Extract the data that should be signed offline. /usr/lib/systemd/systemd-sbsign \ sign \ --certificate=secure-boot-certificate.pem \ --output=signed-data.bin \ --prepare-offline-signing \ "$SD_BOOT" # Sign the data out-of-band. This step usually happens out-of-band on a separate system. openssl dgst -sha256 -sign secure-boot-private-key.pem -out signed-data.sig signed-data.bin # Attach the signed data and its signature to the systemd-boot PE binary. /usr/lib/systemd/systemd-sbsign \ sign \ --certificate=secure-boot-certificate.pem \ --output="$SD_BOOT.signed" \ --signed-data=signed-data.bin \ --signed-data-signature=signed-data.sig \ "$SD_BOOT"
# See Also `bootctl(1)` # systemd-sleep.conf systemd systemd-sleep.conf 5 systemd-sleep.conf sleep.conf.d Suspend and hibernation configuration file `/etc/systemd/sleep.conf`, `/run/systemd/sleep.conf`, `/usr/lib/systemd/sleep.conf`, `/etc/systemd/sleep.conf.d/*.conf`, `/run/systemd/sleep.conf.d/*.conf`, `/usr/lib/systemd/sleep.conf.d/*.conf` # Description `systemd` supports four general power-saving modes: suspend a low-power state where execution of the OS is paused, and complete power loss might result in lost data, and which is fast to enter and exit. This corresponds to suspend, standby, or freeze states as understood by the kernel. hibernate a low-power state where execution of the OS is paused, and complete power loss does not result in lost data, and which might be slow to enter and exit. This corresponds to the hibernation as understood by the kernel. hybrid-sleep a low-power state where execution of the OS is paused, which might be slow to enter, and on complete power loss does not result in lost data but might be slower to exit in that case. This mode is called suspend-to-both by the kernel. suspend-then-hibernate A low power state where the system is initially suspended (the state is stored in RAM). When the battery level is too low (less than 5%) or a certain timespan has passed, whichever happens first, the system is automatically woken up and then hibernated. This establishes a balance between speed and safety. If the system has no battery, it would be hibernated after `HibernateDelaySec=` has passed. If not set, then defaults to `2h`. If the system has battery, low-battery alarms (ACPI \_BTP) are tried first for detecting battery percentage and wake up the system for hibernation. If `HibernateDelaySec=` is also set, an additional timer is configured so that the system hibernates on whichever comes first: low battery or the configured delay. If ACPI \_BTP is not available, the system would regularly wake up to check the time and detect the battery percentage/discharging rate. The rate is used to schedule the next detection. If that is also not available, `SuspendEstimationSec=` is used as last resort. Settings in these files determine what strings will be written to `/sys/power/disk` and `/sys/power/state` by `systemd-sleep(8)` when `systemd(1)` attempts to suspend or hibernate the machine. See `systemd.syntax(7)` for a general description of the syntax. # Options The following options can be configured in the \[Sleep\] section of `/etc/systemd/sleep.conf` or a `sleep.conf.d` file: `AllowSuspend=`; `AllowHibernation=`; `AllowHybridSleep=`; `AllowSuspendThenHibernate=` By default, any power-saving mode is advertised if possible (i.e. the kernel supports that mode, the necessary resources are available). Those switches can be used to disable specific modes. If `AllowHibernation=no` or `AllowSuspend=no` is used, this implies `AllowSuspendThenHibernate=no` and `AllowHybridSleep=no`, since those methods use both suspend and hibernation internally. `AllowSuspendThenHibernate=yes` and `AllowHybridSleep=yes` can be used to override and enable those specific modes. `SuspendState=` The string to be written to `/sys/power/state` by `systemd-suspend.service(8)`. More than one value can be specified by separating multiple values with whitespace. They will be tried in turn, until one is written without error. If none of the writes succeed, the operation will be aborted. The allowed set of values is determined by the kernel and is shown in the file itself (use `cat /sys/power/state` to display). See [ Basic sysfs Interfaces for System Suspend and Hibernation](https://docs.kernel.org/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation) for more details. `systemd-suspend-then-hibernate.service(8)` uses this value when suspending. `HibernateMode=` The string to be written to `/sys/power/disk` by `systemd-hibernate.service(8)`. More than one value can be specified by separating multiple values with whitespace. They will be tried in turn, until one is written without error. If none of the writes succeed, the operation will be aborted. The allowed set of values is determined by the kernel and is shown in the file itself (use `cat /sys/power/disk` to display). See the kernel documentation page [ Basic sysfs Interfaces for System Suspend and Hibernation](https://docs.kernel.org/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation) for more details. `systemd-suspend-then-hibernate.service(8)` uses the value of `HibernateMode=` when hibernating. `MemorySleepMode=` The string to be written to `/sys/power/mem_sleep` when `SuspendState=mem` or `hybrid-sleep` is used. More than one value can be specified by separating multiple values with whitespace. They will be tried in turn, until one is written without error. If none of the writes succeed, the operation will be aborted. Defaults to empty, i.e. the kernel default or kernel command line option `mem_sleep_default=` is respected. The allowed set of values is determined by the kernel and is shown in the file itself (use `cat /sys/power/mem_sleep` to display). See the kernel documentation page [ Basic sysfs Interfaces for System Suspend and Hibernation](https://docs.kernel.org/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation) for more details. `HibernateDelaySec=` The amount of time the system spends in suspend mode before the system is automatically put into hibernate mode. Only used by `systemd-suspend-then-hibernate.service(8)`. Refer to `suspend-then-hibernate` for details on how this option interacts with other options/system battery state. `HibernateOnACPower=` Whether to allow hibernation when the system has AC power. Only used by `systemd-suspend-then-hibernate.service(8)` when `HibernateDelaySec=` is set. If this option is disabled, the countdown of `HibernateDelaySec=` starts only after AC power is disconnected, keeping the system in the suspend state otherwise. This option is only effective on systems with a battery. `SuspendEstimationSec=` The RTC alarm will wake the system after the specified timespan to measure the system battery capacity level and estimate battery discharging rate. Only used by `systemd-suspend-then-hibernate.service(8)`. Refer to `suspend-then-hibernate` for details on how this option interacts with other options/system battery state. # Example: freeze Example: to exploit the “freeze” mode added in Linux 3.9, one can use `systemctl suspend` with [Sleep] SuspendState=freeze # See Also `systemd-sleep(8)`, `systemd-suspend.service(8)`, `systemd-hibernate.service(8)`, `systemd-hybrid-sleep.service(8)`, `systemd-suspend-then-hibernate.service(8)`, `systemd(1)`, `systemd.directives(7)` # systemd-socket-activate systemd systemd-socket-activate 1 systemd-socket-activate Test socket activation of daemons systemd-socket-activate OPTIONS COMMAND ARGS # Description `systemd-socket-activate` may be used to launch a socket-activated service program from the command line for testing purposes. It may also be used to launch individual instances of the service program per connection. The daemon to launch and its options should be specified after options intended for `systemd-socket-activate`. If the `--inetd` option is given, the socket file descriptor will be used as the standard input and output of the launched process. Otherwise, standard input and output will be inherited, and sockets will be passed through file descriptors 3 and higher. Sockets passed through `$LISTEN_FDS` to `systemd-socket-activate` will be passed through to the daemon, in the original positions. Other sockets specified with `--listen=` will use consecutive descriptors. By default, `systemd-socket-activate` listens on a stream socket, use `--datagram` and `--seqpacket` to listen on datagram or sequential packet sockets instead (see below). # Options `-l address`; `--listen=address` Listen on this \. Takes a string like `2000` or `127.0.0.1:2001`. `-a`; `--accept` Launch an instance of the service program for each connection and pass the connection socket. May not be combined with `--now`. `-d`; `--datagram` Listen on a datagram socket (`SOCK_DGRAM`), instead of a stream socket (`SOCK_STREAM`). May not be combined with `--seqpacket`. `--seqpacket` Listen on a sequential packet socket (`SOCK_SEQPACKET`), instead of a stream socket (`SOCK_STREAM`). May not be combined with `--datagram`. `--inetd` Use the inetd protocol for passing file descriptors, i.e. as standard input and standard output, instead of the new-style protocol for passing file descriptors using `$LISTEN_FDS` (see above). `-E VAR=VALUE`; `--setenv=VAR=VALUE` Add this variable to the environment of the launched process. If \ is followed by `=`, assume that it is a variable–value pair. Otherwise, obtain the value from the environment of `systemd-socket-activate` itself. `--fdname=NAME:NAME…` Specify names for the file descriptors passed. This is equivalent to setting `FileDescriptorName=` in socket unit files, and enables use of `sd_listen_fds_with_names(3)`. Multiple entries may be specifies using separate options or by separating names with colons (`:`) in one option. In case more names are given than descriptors, superfluous ones will be ignored. In case less names are given than descriptors, the remaining file descriptors will be unnamed. `--now` Start the service program instantly, instead of waiting for a connection on the socket(s). May not be combined with `--accept`. # Environment variables `$LISTEN_FDS`; `$LISTEN_PID`; `$LISTEN_PIDFDID`; `$LISTEN_FDNAMES` See `sd_listen_fds(3)`. `$SYSTEMD_LOG_TARGET`; `$SYSTEMD_LOG_LEVEL`; `$SYSTEMD_LOG_TIME`; `$SYSTEMD_LOG_COLOR`; `$SYSTEMD_LOG_LOCATION`; `$SYSTEMD_LOG_EXECUTABLE` Same as in `systemd(1)`. # Examples
Run an echo server on port 2000
$ systemd-socket-activate -l 2000 --inetd -a cat
Run a socket-activated instance of `systemd-journal-gatewayd(8)`
$ systemd-socket-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd
# See Also `systemd(1)`, `systemd.socket(5)`, `systemd.service(5)`, `systemd-run(1)`, `sd_listen_fds(3)`, `sd_listen_fds_with_names(3)`, `cat(1)` # systemd-socket-proxyd systemd systemd-socket-proxyd 8 systemd-socket-proxyd Bidirectionally proxy local sockets to another (possibly remote) socket systemd-socket-proxyd OPTIONS HOST : PORT systemd-socket-proxyd OPTIONS UNIX-DOMAIN-SOCKET-PATH # Description `systemd-socket-proxyd` is a generic socket-activated network socket forwarder proxy daemon for IPv4, IPv6 and UNIX stream sockets. It may be used to bi-directionally forward traffic from a local listening socket to a local or remote destination socket. One use of this tool is to provide socket activation support for services that do not natively support socket activation. On behalf of the service to activate, the proxy inherits the socket from systemd, accepts each client connection, opens a connection to a configured server for each client, and then bidirectionally forwards data between the two. This utility's behavior is similar to `socat(1)`. The main differences for `systemd-socket-proxyd` are support for socket activation with `Accept=no` and an event-driven design that scales better with the number of connections. Note that `systemd-socket-proxyd` will not forward socket side channel information, i.e. will not forward `SCM_RIGHTS`, `SCM_CREDENTIALS`, `SCM_SECURITY`, `SO_PEERCRED`, `SO_PEERPIDFD`, `SO_PEERSEC`, `SO_PEERGROUPS` and similar. # Options The following options are understood: `--connections-max=`; `-c` Sets the maximum number of simultaneous connections, defaults to 256. If the limit of concurrent connections is reached further connections will be refused. `--exit-idle-time=` Sets the time before exiting when there are no connections, defaults to `infinity`. Takes a unit-less value in seconds, or a time span value such as `5min 20s`. `--proxy-protocol=` Uses the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to communicate with the server. This allows an appropriately configured server to know the real client IP address. Takes the version of the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) used, and only supports `v1` for now. Default is not to use a PROXY protocol. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Examples ## Simple Example Use two services with a dependency and no namespace isolation.
proxy-to-nginx.socket
[Socket] ListenStream=80 [Install] WantedBy=sockets.target
proxy-to-nginx.service
[Unit] Requires=nginx.service After=nginx.service Requires=proxy-to-nginx.socket After=proxy-to-nginx.socket [Service] Type=notify ExecStart=/usr/lib/systemd/systemd-socket-proxyd /run/nginx/socket PrivateTmp=yes PrivateNetwork=yes
nginx.conf
[…] server { listen unix:/run/nginx/socket; […]
Enabling the proxy
# systemctl enable --now proxy-to-nginx.socket $ curl http://localhost:80/
If `nginx.service` has `StopWhenUnneeded=` set, then passing `--exit-idle-time=` to `systemd-socket-proxyd` allows both services to stop during idle periods. ## Namespace Example Similar as above, but runs the socket proxy and the main service in the same private namespace, assuming that `nginx.service` has `PrivateTmp=` and `PrivateNetwork=` set, too.
proxy-to-nginx.socket
[Socket] ListenStream=80 [Install] WantedBy=sockets.target
proxy-to-nginx.service
[Unit] Requires=nginx.service After=nginx.service Requires=proxy-to-nginx.socket After=proxy-to-nginx.socket JoinsNamespaceOf=nginx.service [Service] Type=notify ExecStart=/usr/lib/systemd/systemd-socket-proxyd 127.0.0.1:8080 PrivateTmp=yes PrivateNetwork=yes
nginx.conf
[…] server { listen 8080; […]
Enabling the proxy
# systemctl enable --now proxy-to-nginx.socket $ curl http://localhost:80/
## PROXY protocol example with nginx systemd-socket-proxyd and nginx using the PROXY protocol
proxy-to-nginx.socket
[Socket] ListenStream=80 [Install] WantedBy=sockets.target
proxy-to-nginx.service
[Unit] Requires=nginx.service After=nginx.service Requires=proxy-to-nginx.socket After=proxy-to-nginx.socket [Service] Type=notify ExecStart=/usr/lib/systemd/systemd-socket-proxyd --proxy-protocol=v1 /run/nginx/socket PrivateTmp=yes PrivateNetwork=yes
nginx.conf
[…] server { listen unix:/run/nginx/socket proxy_protocol; real_ip_header proxy_protocol; […]
Enabling the proxy
# systemctl enable --now proxy-to-nginx.socket $ curl http://localhost:80/
# See Also `systemd(1)`, `systemd.socket(5)`, `systemd.service(5)`, `systemctl(1)`, `socat(1)`, `nginx(1)`, `curl(1)`, [PROXY protocol specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt), [nginx: Accepting the PROXY Protocol](https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol/) # systemd-soft-reboot.service systemd systemd-soft-reboot.service 8 systemd-soft-reboot.service Userspace reboot operation `systemd-soft-reboot.service` # Description `systemd-soft-reboot.service` is a system service that is pulled in by `soft-reboot.target` and is responsible for performing a userspace-only reboot operation. When invoked, it will send the `SIGTERM` signal to any processes left running (but does not wait for the processes to exit), and follow up with `SIGKILL`. If the `/run/nextroot/` directory exists (which may be a regular directory, a directory mount point or a symlink to either) then it will switch the file system root to it. It then reexecutes the service manager off the (possibly now new) root file system, which will enqueue a new boot transaction as in a normal reboot. Such a userspace-only reboot operation permits updating or resetting the entirety of userspace with minimal downtime, as the reboot operation does *not* transition through: - The second phase of regular shutdown, as implemented by `systemd-shutdown(8)`. - The third phase of regular shutdown, i.e. the return to the initrd context. - The hardware reboot operation. - The firmware initialization. - The boot loader initialization. - The kernel initialization. - The initrd initialization. However, this form of reboot comes with drawbacks as well: - The OS update remains incomplete, as the kernel is not reset and continues running. - Kernel settings (such as `/proc/sys/` settings, a.k.a. "sysctl", or `/sys/` settings) are not reset. These limitations may be addressed by various means, which are outside of the scope of this documentation, such as kernel live-patching and sufficiently comprehensive `/etc/sysctl.d/` files. # Resource Pass-Through Various runtime OS resources can passed from a system runtime to the next, through the userspace reboot operation. Specifically: - File descriptors placed in the file descriptor store of services that remain active until the very end are passed to the next boot, where they are placed in the file descriptor store of the same unit. For this to work, units must declare `DefaultDependencies=no` (and avoid a manual `Conflicts=shutdown.target` or similar) to ensure they are not terminated as usual during the system shutdown operation. Alternatively, use `FileDescriptorStorePreserve=` to allow the file descriptor store to remain pinned even when the unit is down. See `systemd.service(5)` for details about the file descriptor store. - Similar to this, file descriptors associated with `.socket` units remain open (and connectible) if the units are not stopped during the transition. (Achieved by `DefaultDependencies=no`.) - The `/run/` file system remains mounted and populated and may be used to pass state information between such userspace reboot cycles. - Service processes may continue to run over the transition, past soft-reboot and into the next session, if they are placed in services that remain active until the very end of shutdown (which again is achieved via `DefaultDependencies=no`). They must also be set up to avoid being killed by the aforementioned `SIGTERM` and `SIGKILL` via `SurviveFinalKillSignal=yes`, and also be configured to avoid being stopped on isolate via `IgnoreOnIsolate=yes`. They also have to be configured to be stopped on normal shutdown, reboot and maintenance mode. Finally, they have to be ordered after `basic.target` to ensure correct ordering on boot. Note that in case any new or custom units are used to isolate to, or that implement an equivalent shutdown functionality, they will also have to be configured manually for correct ordering and conflicting. For example: [Unit] Description=My Surviving Service SurviveFinalKillSignal=yes IgnoreOnIsolate=yes DefaultDependencies=no After=basic.target Conflicts=reboot.target kexec.target poweroff.target halt.target rescue.target emergency.target Before=shutdown.target rescue.target emergency.target [Service] Type=oneshot ExecStart=sleep infinity - On top of the above, templated units also need a configuration file for their slice, as they by default use a slice named after the non-templated part of the unit. For example, for a `foo@test.service` instance, a `system-foo.slice` unit may be added with the following content: [Unit] SurviveFinalKillSignal=yes IgnoreOnIsolate=yes DefaultDependencies=no - File system mounts may remain mounted during the transition, and complex storage attached, if configured to remain until the very end of the shutdown process. (Also achieved via `DefaultDependencies=no`, and by avoiding `Conflicts=umount.target`) - If the unit publishes a service over D-Bus, the connection needs to be re-established after soft-reboot as the D-Bus broker will be stopped and then started again. When using the `sd-bus(3)` library this can be achieved by adapting the following example. Even though passing resources from one soft reboot cycle to the next is possible this way, we strongly suggest to use this functionality sparingly only, as it creates a more fragile system as resources from different versions of the OS and applications might be mixed with unforeseen consequences. In particular it is recommended to *avoid* allowing processes to survive the soft reboot operation, as this means code updates will necessarily be incomplete, and processes typically pin various other resources (such as the file system they are backed by), thus increasing memory usage (as two versions of the OS/application/file system might be kept in memory). Leaving processes running during a soft-reboot operation requires disconnecting the service comprehensively from the rest of the OS, i.e. minimizing IPC and reducing sharing of resources with the rest of the OS. A possible mechanism to achieve this is the concept of [Portable Services](https://systemd.io/PORTABLE_SERVICES), but make sure no resource from the host's OS filesystems is pinned via `BindPaths=` or similar unit settings, otherwise the old, originating filesystem will remain mounted as long as the unit is running. # Notes Note that because `systemd-shutdown(8)` is not executed, the executables in `/usr/lib/systemd/system-shutdown/` are not executed either. Note that `systemd-soft-reboot.service` (and related units) should never be executed directly. Instead, trigger system shutdown with a command such as `systemctl soft-reboot`. Note that if a new root file system has been set up on `/run/nextroot/`, a `soft-reboot` will be performed when the `reboot` command is invoked. # See Also `systemd(1)`, `systemctl(1)`, `systemd.special(7)`, `systemd-poweroff.service(8)`, `systemd-suspend.service(8)`, `bootup(7)` # systemd-ssh-generator systemd systemd-ssh-generator 8 systemd-ssh-generator Generator for binding a socket-activated SSH server to local AF_VSOCK and AF_UNIX sockets `/usr/lib/systemd/system-generators/systemd-ssh-generator` # Description `systemd-ssh-generator` binds a socket-activated SSH server to local `AF_VSOCK` and `AF_UNIX` sockets under certain conditions. It only has an effect if the `sshd(8)` binary is installed. Specifically, it does the following: - If invoked in a VM with `AF_VSOCK` support, a socket-activated SSH per-connection service is bound to `AF_VSOCK` port 22. - If invoked in a container environment with a writable directory `/run/host/unix-export/` pre-mounted it binds SSH to an `AF_UNIX` socket `/run/host/unix-export/ssh`. The assumption is that this directory is bind mounted to the host side as well, and can be used to connect to the container from there. See [Container Interface](https://systemd.io/CONTAINER_INTERFACE) for more information about this interface. - A local `AF_UNIX` socket `/run/ssh-unix-local/socket` is also bound, unconditionally. This may be used for SSH communication from the host to itself, without involving networking, for example to traverse security boundaries safely and with secure authentication. - Additional `AF_UNIX` and `AF_VSOCK` sockets are optionally bound, based on the `systemd.ssh_listen=` kernel command line option or the `ssh.listen` system credential (see below). See `systemd-ssh-proxy(1)` for details on how to connect to these sockets via the `ssh` client. The `ssh.authorized_keys.root` credential can be used to allow specific public keys to log in over SSH. See `systemd.system-credentials(7)` for more information. The generator will use a packaged `sshd@.service` service template file if one exists, and otherwise generate a suitable service template file. `systemd-ssh-generator` implements `systemd.generator(7)`. # Kernel Command Line `systemd-ssh-generator` understands the following `kernel-command-line(7)` parameters: `systemd.ssh_auto=` This option takes an optional boolean argument, and defaults to yes. If enabled, the automatic binding to the `AF_VSOCK` and `AF_UNIX` sockets listed above is done. If disable, this is not done, except for those explicitly requested via `systemd.ssh_listen=` on the kernel command line or via the `ssh.listen` system credential. `systemd.ssh_listen=` This option configures an additional socket to bind SSH to. It may be used multiple times to bind multiple sockets. The syntax should follow the one of `ListenStream=`, see `systemd.socket(5)` for details. This functionality supports all socket families `systemd(1)` supports, including `AF_INET` and `AF_INET6`. # Credentials `systemd-ssh-generator` supports the system credentials logic. The following credentials are used when passed in: `ssh.listen` This credential should be a text file, with each line referencing one additional socket to bind SSH to. The syntax should follow the one of `ListenStream=`, see `systemd.socket(5)` for details. This functionality supports all socket families systemd supports, including `AF_INET` and `AF_INET6`. `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. # See Also `systemd(1)`, `kernel-command-line(7)`, `systemd.system-credentials(7)`, `vsock(7)`, `unix(7)`, `ssh(1)`, `sshd(8)` # systemd-ssh-issue systemd systemd-ssh-issue 1 systemd-ssh-issue Generator for SSH login prompt drop-ins /usr/lib/systemd/systemd-ssh-issue OPTIONS make-vsock /usr/lib/systemd/systemd-ssh-issue OPTIONS rm-vsock # Description `systemd-ssh-issue` is a small tool that generates (when called with `make-vsock`) and removes (when called with `rm-vsock`) a `/run/issue.d/50-ssh-vsock.issue` drop-in file in case `AF_VSOCK` support is available in the kernel and the VM environment. The file contains brief information about how to contact the local system via SSH-over-`AF_VSOCK`, in particular it reports the system's `AF_VSOCK` CID. The file is typically read and displayed by `agetty(8)` on console or serial login prompts. This tool is automatically used by `systemd-ssh-generator(8)` in the `AF_VSOCK` socket units it generates. # Options The following options are understood: `--issue-path=` Changes the path to the issue file to write to/remove. If not specified, defaults to `/run/issue.d/50-ssh-vsock.issue`. If specified as empty string or `-` writes the issue file contents to standard output. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-ssh-generator(8)`, `vsock(7)`, `ssh(1)`, `sshd(8)`, `agetty(8)` # systemd-ssh-proxy systemd systemd-ssh-proxy 1 systemd-ssh-proxy SSH client plugin for connecting to AF_VSOCK and AF_UNIX sockets Host unix/* unix%* vsock/* vsock%* vsock-mux/* vsock-mux%* ProxyCommand /usr/lib/systemd/systemd-ssh-proxy %h %p ProxyUseFdpass yes /usr/lib/systemd/systemd-ssh-proxy ADDRESS PORT # Description `systemd-ssh-proxy` is a small "proxy" plugin for the `ssh(1)` tool that allows connecting to `AF_UNIX` and `AF_VSOCK` sockets. It implements the interface defined by `ssh`'s `ProxyCommand` configuration option. It's supposed to be used with an `ssh_config(5)` configuration fragment like the following: Host unix/* unix%* vsock/* vsock%* vsock-mux/* vsock-mux%* ProxyCommand /usr/lib/systemd/systemd-ssh-proxy %h %p ProxyUseFdpass yes CheckHostIP no Host .host ProxyCommand /usr/lib/systemd/systemd-ssh-proxy unix/run/ssh-unix-local/socket %p ProxyUseFdpass yes CheckHostIP no A configuration fragment along these lines is by default installed into `/etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf`. With this in place, SSH connections to host string `unix/` followed by an absolute `AF_UNIX` file system path to a socket will be directed to the specified socket, which must be of type `SOCK_STREAM`. Similar, SSH connections to `vsock/` followed by an `AF_VSOCK` CID will result in an SSH connection made to that CID. `vsock-mux/` followed by an absolute `AF_UNIX` file system path to a socket is similar but for cloud-hypervisor/firecracker which do not allow direct `AF_VSOCK` communication between the host and guests, and provide their own multiplexer over `AF_UNIX` sockets. See [cloud-hypervisor VSOCK support](https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/vsock.md) and [Using the Firecracker Virtio-vsock Device](https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md). Note that `%` can be used as a separator instead of `/` to be compatible with tools like `scp` and `rsync`. Moreover, connecting to `.host` will connect to the local host via SSH, without involving networking. This tool is supposed to be used together with `systemd-ssh-generator(8)` which when run inside a VM or container will bind SSH to suitable addresses. `systemd-ssh-generator` is supposed to run in the container or VM guest, and `systemd-ssh-proxy` is run on the host, in order to connect to the container or VM guest. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Examples
Talk to a local VM with CID 4711
ssh vsock/4711
Talk to a VM guest hosted with cloud-hypervisor/firecracker
ssh vsock-mux/run/vm-1234.sock
Talk to the local host via ssh
ssh .host or equivalent: ssh unix/run/ssh-unix-local/socket
Copy local 'foo' file to a local VM with CID 1348
scp foo vsock%1348:
# See Also `systemd(1)`, `systemd-ssh-generator(8)`, `vsock(7)`, `unix(7)`, `ssh(1)`, `sshd(8)` # systemd-stdio-bridge systemd systemd-stdio-bridge 1 systemd-stdio-bridge D-Bus proxy systemd-stdio-bridge OPTIONS # Description `systemd-stdio-bridge` implements a proxy between STDIN/STDOUT and a D-Bus bus. It expects to receive an open connection via STDIN/STDOUT when started, and will create a new connection to the specified bus. It will then forward messages between the two connections. This program is suitable for socket activation: the first connection may be a pipe or a socket and must be passed as either standard input, or as an open file descriptor according to the protocol described in `sd_listen_fds(3)`. The second connection will be made by default to the local system bus, but this can be influenced by the `--user`, `--system`, `--machine=`, and `--bus-path=` options described below. `sd-bus(3)` uses `systemd-stdio-bridge` to forward D-Bus connections over `ssh(1)`, or to connect to the bus of a different user, see `sd_bus_set_address(3)`. # Options The following options are understood: `-p PATH`; `--bus-path=PATH` Path to the bus address. Default: `unix:path=/run/dbus/system_bus_socket` `-q`; `--quiet` Suppresses error logging on failure. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `dbus-daemon(1)`, `dbus-broker(1)`, [D-Bus](https://www.freedesktop.org/wiki/Software/dbus), `systemd(1)` # systemd-storage-block@.service systemd systemd-storage-block@.service 8 systemd-storage-block@.service systemd-storage-block.socket systemd-storage-block Storage provider exposing local block devices as storage volumes `systemd-storage-block@.service` `systemd-storage-block.socket` # Description `systemd-storage-block@.service` is a system service that implements the `io.systemd.StorageProvider` [Varlink](https://varlink.org/) interface, exposing the system's block devices (such as disks, partitions, and device-mapper nodes) as storage volumes that may be acquired by other programs as file descriptors. The service is socket-activated via `systemd-storage-block.socket`, which listens on the AF_UNIX socket `/run/systemd/io.systemd.StorageProvider/block`. The socket directory `/run/systemd/io.systemd.StorageProvider/` is the well-known location where storage providers register, see `storagectl(1)` for an enumeration tool. See also `systemd-storage-fs@.service(8)` for a complementary implementation that exposes regular files and directories from a backing file system. # Volumes The volumes exposed via the provider are identified by an absolute path (which must begin with `/dev/`), i.e. as a kernel block device node such as `/dev/sda` or `/dev/disk/by-id/…`. Volume names that are not normalized or that do not begin with `/dev/` are not accepted. # Options The following options are understood: # Files `/run/systemd/io.systemd.StorageProvider/block` AF_UNIX socket the service listens on. This is the canonical location for the `block` storage provider, and is enumerated by `storagectl providers`. # See Also `systemd(1)`, `storagectl(1)`, `systemd-storage-fs@.service(8)` # systemd-storage-fs@.service systemd systemd-storage-fs@.service 8 systemd-storage-fs@.service systemd-storage-fs.socket systemd-storage-fs Storage provider exposing regular files and directories as storage volumes `systemd-storage-fs@.service` `systemd-storage-fs.socket` # Description `systemd-storage-fs@.service` is a service that implements the `io.systemd.StorageProvider` [Varlink](https://varlink.org/) interface, exposing regular files and directories in `/var/lib/storage/*.volume` (if used in system mode) or `$XDG_STATE_HOME/storage` (when used in user mode) as storage volumes. Acquired volumes are returned to the caller as file descriptors. Unlike `systemd-storage-block@.service(8)`, this implementation also supports creating new volumes on demand from a small set of built-in templates. The service is socket-activated via `systemd-storage-fs.socket`. In system mode it listens on the AF_UNIX socket `/run/systemd/io.systemd.StorageProvider/fs`, in user mode on `$XDG_RUNTIME_DIR/systemd/io.systemd.StorageProvider/fs`. See `storagectl(1)` for an enumeration tool. See also `systemd-storage-block@.service(8)` for a complementary implementation that exposes local block devices as storage volumes. # Volumes Volumes are stored below the storage directory: - `/var/lib/storage/` when run in system mode. - `$XDG_STATE_HOME/storage/` (typically `~/.local/state/storage/`) when run in user mode. Each volume on disk is stored as a directory entry with a `.volume` suffix in the storage directory. Entries which are regular files are exposed as volumes of type `reg`; entries which are directories are exposed as volumes of type `dir`. Moreover, block device nodes may be symlinked (or bind mounted) into the directory, which are then exposed as volumes of type `blk`. For directory volumes, the root of the file system passed to clients is placed in a subdirectory `root/` of the `NAME.volume` directory. The former (and all inodes below it) must be owned by the foreign UID range, the latter by the host's root (or the user in user mode). When acquiring a volume, symlinks are followed. An administrator is permitted to freely manipulate the volume hierarchy directly as long as the rules described above are followed. In particular, it's permitted to copy, mount or symlink arbitrary external resources (regardless if directory, regular file or block) into the volume directory, so that they are exposed as additional volumes. # Templates The provider supports creating new volumes automatically when they are acquired. The caller may select a *template* that determines configuration details of the volume to create. The following built-in templates are available: `sparse-file` Creates a volume backed by a sparsely populated regular file. This is the default template when creating a regular file volume. (Volume type is `reg`.) `allocated-file` Creates a volume backed by a fully allocated regular file. (Volume type is `reg`.) `directory` Creates a volume backed by a regular directory. (Volume type is `dir`.) `subvolume` Creates a btrfs subvolume as backing inode (falling back to a regular directory if the storage directory is not on btrfs). This is the default template when creating a directory volume. (Volume type is `dir`.) # Options The following command-line options are understood: `--system` Operate in system mode. Volumes are stored below `/var/lib/storage/`. This is the default when invoked from `systemd-storage-fs@.service` in the system manager. `--user` Operate in user mode. Volumes are stored below `$XDG_STATE_HOME/storage/`. This is the default when invoked from `systemd-storage-fs@.service` in the user manager. # Files `/var/lib/storage/`; `$XDG_STATE_HOME/storage/` The storage directory used to back the system mode and user mode service instances respectively. Each volume is stored as an entry with a `.volume` suffix below this directory. `/run/systemd/io.systemd.StorageProvider/fs`; `$XDG_RUNTIME_DIR/systemd/io.systemd.StorageProvider/fs` AF_UNIX sockets the service listens on, in system and user mode respectively. These are the canonical locations for the `fs` storage provider, and are enumerated by `storagectl providers`. # See Also `systemd(1)`, `storagectl(1)`, `systemd-storage-block@.service(8)` # systemd-storagetm.service systemd systemd-storagetm.service 8 systemd-storagetm.service systemd-storagetm Exposes all local block devices as NVMe-TCP mass storage devices `systemd-storagetm.service` /usr/lib/systemd/systemd-storagetm OPTIONS DEVICE /usr/lib/systemd/systemd-storagetm OPTIONS --all /usr/lib/systemd/systemd-storagetm OPTIONS --list-devices # Description `systemd-storagetm.service` is a service that exposes all local block devices as NVMe-TCP mass storage devices. Its primary use-case is to be invoked by the `storage-target-mode.target` unit that can be booted into. > [!WARNING] > The NVMe disks are currently exposed without authentication or encryption, in read/write mode. This means network peers may read from and write to the device without any restrictions. This functionality should hence only be used in a local setup. Note that to function properly networking must be configured too. The recommended mechanism to boot into a storage target mode is by adding `rd.systemd.unit=storage-target-mode.target ip=link-local` on the kernel command line. Note that `ip=link-local` only configures link-local IP, i.e. IPv4LL and IPv6LL, which means non-routable addresses. This is done for security reasons, so that only systems on the local link can access the devices. Use `ip=dhcp` to assign routable addresses too. For further details see `systemd-network-generator.service(8)`. Unless the `--list-devices` or `--all` switches are used, one or more block devices or regular files to expose via NVMe-TCP must be specified as arguments. # Options The following options are understood: `--nqn=` Takes a string. If specified configures the NVMe Qualified Name to use for the exposed NVMe-TCP mass storage devices. The NQN should follow the syntax described in [NVM Express Base Specification 2.0c](https://nvmexpress.org/wp-content/uploads/NVM-Express-Base-Specification-2.0c-2022.10.04-Ratified.pdf), section 4.5 "NVMe Qualified Names". Note that the NQN specified here will be suffixed with a dot and the block device name before it is exposed on the NVMe target. If not specified, defaults to `nqn.2023-10.io.systemd:storagetm.ID`, where ID is replaced by a 128bit ID derived from `machine-id(5)`. `--all`; `-a` If specified exposes all local block devices via NVMe-TCP, current and future (i.e. it watches block devices come and go and updates the NVMe-TCP list as needed). Note that by default any block devices that originate on the same block device as the block device backing the current root file system are excluded. If the switch is specified twice this safety mechanism is disabled. `--list-devices` Show a list of candidate block devices this command may operate on. Specifically, this enumerates block devices currently present, and shows their device node paths along with any of their symlinks. # See Also `systemd(1)`, `systemd.special(7)` # systemd-stub systemd systemd-stub 7 systemd-stub sd-stub linuxx64.efi.stub linuxia32.efi.stub linuxaa64.efi.stub A simple UEFI kernel boot stub `/usr/lib/systemd/boot/efi/linuxx64.efi.stub`, `/usr/lib/systemd/boot/efi/linuxia32.efi.stub`, `/usr/lib/systemd/boot/efi/linuxaa64.efi.stub`, `ESP/.../foo.efi.extra.d/*.addon.efi`, `ESP/.../foo.efi.extra.d/*.cred`, `ESP/.../foo.efi.extra.d/*.raw`, `ESP/.../foo.efi.extra.d/*.sysext.raw`, `ESP/.../foo.efi.extra.d/*.confext.raw`, `ESP/loader/addons/*.addon.efi`, `ESP/loader/credentials/*.cred`, `ESP/loader/extensions/*.raw`, `ESP/loader/extensions/*.sysext.raw`, `ESP/loader/extensions/*.confext.raw` # Description `systemd-stub` (stored in per-architecture files `linuxx64.efi.stub`, `linuxia32.efi.stub`, `linuxaa64.efi.stub` on disk) is a simple UEFI boot stub. An UEFI boot stub is attached to a Linux kernel binary image, and is a piece of code that runs in the UEFI firmware environment before transitioning into the Linux kernel environment. The UEFI boot stub ensures a Linux kernel is executable as regular UEFI binary, and is able to do various preparations before switching the system into the Linux world. The UEFI boot stub looks for various resources for the kernel invocation inside the UEFI PE binary itself. This allows combining various resources inside a single PE binary image (a "Unified Kernel Image" or "UKI" for short), which may then be signed via UEFI SecureBoot as a whole, covering all individual resources at once. Specifically it may include the following PE sections: - A `.linux` section with the ELF Linux kernel image. This section is required. - An optional `.osrel` section with OS release information, i.e. the contents of the `os-release(5)` file of the OS the kernel belongs to. - An optional `.cmdline` section with the kernel command line to pass to the invoked kernel. - An optional `.initrd` section with the initrd. - An optional `.ucode` section with an initrd containing microcode, to be handed to the kernel before any other initrd. This initrd must not be compressed. - An optional `.splash` section with an image (in the Windows `.BMP` format) to show on screen before invoking the kernel. - An optional `.dtb` section with a compiled binary DeviceTree. - Zero or more `.dtbauto` sections. `systemd-stub` will always use the first matching one. The match is performed by taking the first DeviceTree's `compatible` string supplied by the firmware in configuration tables and comparing it with the first `compatible` string from each of the `.dtbauto` sections. If the firmware does not provide a DeviceTree, the match is done using the `.hwids` section instead. After selecting the matching entry in the `.hwids` section (see the description below), the `compatible` string from that entry will be used to perform the same matching procedure. If a match is found, that `.dtbauto` section will be loaded and will override `.dtb` if present. - Zero or more `.efifw` sections for the firmware image. It works in many ways similar to `.dtbauto` sections. `systemd-stub` will always use the first matching one. The match is performed by first selecting the most appropriate entry in the `.hwids` section based on the hardware IDs supplied by SMBIOS (see below). If a suitable entry is found, the `fwid` string from that entry will be used to perform the matching procedure for firmware blobs in `.efifw` section. The first matching firmware will be loaded. - An optional `.hwids` section with hardware IDs of the machines to match DeviceTrees. `systemd-stub` will use the SMBIOS data to calculate hardware IDs of the machine (as per [specification](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/specifying-hardware-ids-for-a-computer)), and then it will try to find any of them in the `.hwids` section. The first matching entry will be used. - An optional `.uname` section with the kernel version information, i.e. the output of `uname -r` for the kernel included in the `.linux` section. - An optional `.sbat` section with [SBAT](https://github.com/rhboot/shim/blob/main/SBAT.md) revocation metadata. - An optional `.pcrsig` section with a set of cryptographic signatures for the expected TPM2 PCR values after the kernel has been booted, in JSON format. This is useful for implementing TPM2 policies that bind disk encryption and similar to kernels that are signed by a specific key. - An optional `.pcrpkey` section with a public key in the PEM format matching the signature data in the `.pcrsig` section. In a basic UKI, the sections listed above appear at most once, with the exception of `.dtbauto` and `.efifw` sections. In a multi-profile UKI, multiple sets of these sections are present in a single file and form "profiles", one of which can be selected at boot. For this, the PE section `.profile` is defined to be used as the separator between sets of sections. The `.profile` section itself may contain meta-information about the section, and follows a similar structure as the contents of the `.osrel` section. For further details about multi-profile UKIs, see below. If UEFI SecureBoot is enabled and the `.cmdline` section is present in the executed image, any attempts to override the kernel command line by passing one as invocation parameters to the EFI binary are ignored. Thus, in order to allow overriding the kernel command line, either disable UEFI SecureBoot, or do not include a kernel command line PE section in the kernel image file. If a command line is accepted via EFI invocation parameters to the EFI binary it is measured into TPM PCR 12 (if a TPM is present). If a DeviceTree is embedded in the `.dtb` section, it replaces an existing DeviceTree in the corresponding EFI configuration table. `systemd-stub` will ask the firmware via the `EFI_DT_FIXUP_PROTOCOL` for hardware specific fixups to the DeviceTree. The contents of 11 of these 12 sections are measured into TPM PCR 11. It is otherwise not used and thus the result can be pre-calculated without too much effort. The `.pcrsig` section is not included in this PCR measurement, since it is supposed to contain signatures for the output of the measurement operation, and thus cannot also be input to it. If an UKI contains multiple profiles, only the PE sections of the selected profile (and those of the base profile, except if overridden) are measured. If non-zero, the selected numeric profile is measured into PCR 12. When `.pcrsig` and/or `.pcrpkey` sections are present in a unified kernel image their contents are passed to the booted kernel in an synthetic initrd cpio archive that places them in the `/.extra/tpm2-pcr-signature.json` and `/.extra/tpm2-pcr-public-key.pem` files. Typically, a `tmpfiles.d(5)` line then ensures they are copied into `/run/systemd/tpm2-pcr-signature.json` and `/run/systemd/tpm2-pcr-public-key.pem` where they remain accessible even after the system transitions out of the initrd environment into the host file system. Tools such `systemd-cryptsetup@.service(8)`, `systemd-cryptenroll(1)` and `systemd-creds(1)` will automatically use files present under these paths to unlock protected resources (encrypted storage or credentials) or bind encryption to booted kernels. For further details about the UKI concept, see the [UAPI.5 UKI specification](https://uapi-group.org/specifications/specs/unified_kernel_image/). # Companion Files The `systemd-stub` UEFI boot stub automatically collects three types of auxiliary companion files optionally placed in drop-in directories on the same partition as the EFI binary, dynamically generates `cpio` initrd archives from them, and passes them to the kernel. Specifically: - For a kernel binary called `foo.efi`, it will look for files with the `.cred` suffix in a directory named `foo.efi.extra.d/` next to it. If the kernel binary uses a counter for the purpose of [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT), this counter will be ignored. For example, `foo+3-0.efi` will look in directory `foo.efi.extra.d/`. A `cpio` archive is generated from all files found that way, placing them in the `/.extra/credentials/` directory of the initrd file hierarchy. The main initrd may then access them in this directory. This is supposed to be used to store auxiliary, encrypted, authenticated credentials for use with `LoadCredentialEncrypted` in the UEFI System Partition. See `systemd.exec(5)` and `systemd-creds(1)` for details on encrypted credentials. The generated `cpio` archive is measured into TPM PCR 12 (if a TPM is present). - Similarly, files `foo.efi.extra.d/*.sysext.raw` are packed up in a `cpio` archive and placed in the `/.extra/sysext/` directory in the initrd file hierarchy. This is supposed to be used to pass additional UKI-specific system extension images to the initrd. See `systemd-sysext(8)` for details on system extension images. The generated `cpio` archive containing these system extension images is measured into TPM PCR 13 (if a TPM is present). - Similarly, files `/loader/extensions/*.sysext.raw` are packed up in a `cpio` archive and placed in the `/.extra/global_sysext/` directory in the initrd file hierarchy. This is supposed to be used to pass additional global system extension images to the initrd. See `systemd-sysext(8)` for details on system extension images. The generated `cpio` archive containing these system extension images is measured into TPM PCR 13 (if a TPM is present). - Similarly, files `foo.efi.extra.d/*.confext.raw` are packed up in a `cpio` archive and placed in the `/.extra/confext/` directory in the initrd file hierarchy. This is supposed to be used to pass additional UKI-specific configuration extension images to the initrd. See `systemd-confext(8)` for details on configuration extension images. The generated `cpio` archive containing these configuration extension images is measured into TPM PCR 12 (if a TPM is present). - Similarly, files `/loader/extensions/*.confext.raw` are packed up in a `cpio` archive and placed in the `/.extra/global_confext/` directory in the initrd file hierarchy. This is supposed to be used to pass additional global configuration extension images to the initrd. See `systemd-confext(8)` for details on configuration extension images. The generated `cpio` archive containing these configuration extension images is measured into TPM PCR 12 (if a TPM is present). - Similarly, files `foo.efi.extra.d/*.addon.efi` are loaded and verified as PE binaries and specific sections are loaded from them. Addons are used to pass additional kernel command line parameters (`.cmdline` section), or DeviceTree blobs (`.dtb` section), additional initrds (`.initrd` section), and microcode updates (`.ucode` section). Addons allow those resources to be passed regardless of the kernel version being booted, for example allowing platform vendors to ship platform-specific configuration. In case Secure Boot is enabled, these files will be validated using keys in UEFI DB, Shim's DB or Shim's MOK, and only loaded if the check passes. Additionally, if both the addon and the UKI contain a `.uname` section, the addon will be rejected if they do not match exactly. It is recommended to always add a `.sbat` section to all signed addons, so that they may be revoked with a SBAT policy update, without requiring blocklisting via DBX/MOKX. The `ukify(1)` tool will add a SBAT policy by default if none is passed when building addons. For more information on SBAT see [Shim documentation](https://github.com/rhboot/shim/blob/main/SBAT.md). Addon files are sorted, loaded, and measured into TPM PCR 12 (if a TPM is present) and appended to the kernel command line. UKI command line options are listed first, then options from addons in `/loader/addons/*.addon.efi`, and finally UKI-specific addons. Device tree blobs are loaded and measured following the same algorithm. Microcode addons are passed to the kernel in inverse order (UKI specific addons, global addons, UKI embedded section). This is because the microcode update driver stops on the first matching filename. Addons are always loaded in the same order based on the filename, so that, given the same set of addons, the same set of measurements can be expected in PCR12. However, note that the filename is not protected by the PE signature, and as such an attacker with write access to the ESP could potentially rename these files to change the order in which they are loaded, in a way that could alter the functionality of the kernel, as some options might be order-dependent. If you sign such addons, you should pay attention to the PCR12 values and make use of an attestation service so that improper use of your signed addons can be detected and dealt with using one of the aforementioned revocation mechanisms. - Files `/loader/credentials/*.cred` are packed up in a `cpio` archive and placed in the `/.extra/global_credentials/` directory of the initrd file hierarchy. This is supposed to be used to pass additional credentials to the initrd, regardless of the kernel version being booted. The generated `cpio` archive is measured into TPM PCR 12 (if a TPM is present). - Additionally, files `/loader/addons/*.addon.efi` are loaded and verified as PE binaries, and `.cmdline`, `.dtb`, `.initrd`, and `.ucode` sections are parsed from them. This is supposed to be used to pass additional command line parameters, DeviceTree blobs, initrds, and microcode updates to the kernel, regardless of the kernel version being booted. These mechanisms may be used to parameterize and extend trusted (i.e. signed), immutable initrd images in a reasonably safe way: all data they contain is measured into TPM PCRs. On access they should be further validated: in case of the credentials case by encrypting/authenticating them via TPM, as exposed by `systemd-creds encrypt -T` (see `systemd-creds(1)` for details); in case of the system extension images by using signed Verity images. Note that earlier components of the boot process might register additional initrds, and thus additional "companion" resources such as system extensions, configuration extensions and credentials for consumption by the kernel and OS eventually booted. For example, `systemd-boot(7)` does this for resources configured in UAPI.1 Type \#1 `extra` lines. `systemd-stub` will combine any resources provided that way with the companion file resources it acquires itself. # Multi-Profile UKIs In many contexts it is useful to allow invocation of a single UKI in multiple different modes (or "profiles") without compromising the cryptographic integrity, measurements and so on of the boot process. For example, a single UKI might provide three distinct profiles: a regular boot one, one that invokes a "factory reset" operation, and one that boots into a storage target mode (as in `systemd-storagetm.service(8)`). Each profile would then use the same `.linux` and `.initrd` sections, but would have a separate `.cmdline` section. For example the latter two profiles would extend the regular kernel command line with `systemd.unit=factory-reset.target` or `rd.systemd.unit=storagetm.target`. A single UKI may support multiple profiles by means of the special `.profile` PE section. This section acts as separator between the PE sections of the individual profiles. `.profile` PE sections hence may appear multiple times in a single UKI, and the other PE sections listed above may appear multiple times too, if `.profile` are used, but only once before the first `.profile` section, once between each subsequent pair, and once after the last appearance of `.profile`. The sections listed before the first `.profile` are considered the "base" profile of the UKI. Each `.profile` section then introduces a new profile, which are numbered starting from zero. The PE sections following each `.profile` are specific to that profile. When booting into a specific profile, the base section's profiles are used in combination with the specific profile's sections: if the same section is defined in both, the per-profile section overrides the base profile's version, otherwise the base profile sections are used. A UKI that contains no `.profile` is consider equivalent to one that just contains a single `.profile`, as having only a single profile `@0`. Here's a simple example for a multi-profile UKI's sections, inspired by the setup suggested above:
Multi-Profile UKI Example
Section Profile
.linux Base profile
.osrel
.cmdline
.initrd
.profile Profile @0
.profile Profile @1
.cmdline
.profile Profile @2
.cmdline
The section list above would define three profiles. The first four sections make up the base profile. A `.profile` section then introduces profile @0. It does not override any sections (or add any) from the base section, hence it is immediately followed by another `.profile` section that then introduces section @1. This profile overrides the kernel command line. Finally, the last two sections define section @2, again overriding the command line. (Note that in this example the first `.cmdline` could also moved behind the first `.profile` with equivalent effect. To keep things nicely extensible, it is probably a good idea to keep the generic command line in the base section instead of profile 0, in case later added profiles might want to reuse it.) The profile to boot may be controlled via the UKI's own command line: if the first argument starts with `@`, followed by a positive integer number in decimal, it selects the profile to boot into. If the first argument is not specified like that, the UKI will automatically boot into profile 0. A `.profile` section may contain meta-information about the profile. It follows a similar format as `.osrel` (i.e. an environment-variable-assignment-block-like list of newline separated strings). Currently two fields are defined: `ID=` is supposed to carry a short identifying string that identifies the profile (e.g. `ID=factory-reset`). `TITLE=` should contain a human-readable string that may appear in the boot menu entry for this profile (e.g. `TITLE='Factory Reset this Device'`). # TPM PCR Notes Note that when a unified kernel using `systemd-stub` is invoked the firmware will measure it as a whole to TPM PCR 4, covering all embedded resources, such as the stub code itself, the core kernel, the embedded initrd and kernel command line (see above for a full list), including all UKI profiles. Also note that when `systemd-stub` measures a PE section, it will measure the amount of bytes that the section takes up in memory (`VirtualSize`) and not the amount of bytes that the section takes up on disk (`SizeOfRawData`). This means that if the size in memory is larger than the size on disk, `systemd-stub` will end up measuring extra zeroes. To avoid this from happening, it is recommended to make sure that the size in memory of each section that is measured by `systemd-stub` is always smaller than or equal to the size on disk. `ukify` automatically makes sure this is the case when building UKIs or addons. Also note that the Linux kernel will measure all initrds it receives into TPM PCR 9. This means every type of initrd (of the selected UKI profile) will possibly be measured two or three times: the initrds embedded in the kernel image will be measured to PCR 4, PCR 9 and PCR 11; the initrd synthesized from credentials (and the one synthesized from configuration extensions) will be measured to both PCR 9 and PCR 12; the initrd synthesized from system extensions will be measured to both PCR 4 and PCR 9. Let's summarize the OS resources and the PCRs they are measured to: | OS Resource | Measurement PCR | |----|----| | `systemd-stub` code (the entry point of the unified PE binary) | 4 | | Core kernel code (embedded in unified PE binary) | 4 + 11 | | OS release information (embedded in the unified PE binary) | 4 + 11 | | Main initrd (embedded in unified PE binary) | 4 + 9 + 11 | | Microcode initrd (embedded in unified PE binary) | 4 + 9 + 11 | | Default kernel command line (embedded in unified PE binary) | 4 + 11 | | Overridden kernel command line | 12 | | Boot splash (embedded in the unified PE binary) | 4 + 11 | | TPM2 PCR signature JSON (embedded in unified PE binary, synthesized into initrd) | 4 + 9 | | TPM2 PCR PEM public key (embedded in unified PE binary, synthesized into initrd) | 4 + 9 + 11 | | Credentials (synthesized initrd from companion files) | 9 + 12 | | System Extensions (synthesized initrd from companion files) | 9 + 13 | | Configuration Extensions (synthesized initrd from companion files) | 9 + 12 | | Selected profile unless zero | 12 | OS Resource PCR Summary # EFI Variables The following EFI variables are defined, set and read by `systemd-stub`, under the vendor UUID `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`, for communication between the boot stub and the OS: `LoaderDevicePartUUID` Contains the partition UUID of the partition the boot loader has been started from on the current boot (usually a EFI System Partition). If already set by the boot loader, this will remain untouched by `systemd-stub`. If not set yet, this will be set to the partition UUID of the partition the unified kernel is started from, in order to support systems that directly boot into a unified kernel image, bypassing any boot loader. `systemd-gpt-auto-generator(8)` uses this information to automatically find the disk booted from, in order to discover various other partitions on the same disk automatically. `LoaderFirmwareInfo`; `LoaderFirmwareType` Brief firmware information. Use `bootctl(1)` to view this data. `LoaderTpm2ActivePcrBanks` Hexadecimal string representation of a bitmask with values defined by the TCG EFI Protocol Specification for TPM 2.0 as EFI_TCG2_BOOT_HASH_ALG\_\*. If no TPM2 support or no active banks were detected, will be set to `0`. Set by the boot loader. Use `systemd-analyze(1)` to view this data. `LoaderImageIdentifier` The file system path to the EFI executable of the boot loader for the current boot, relative to the partition's root directory (i.e. relative to the partition indicated by `LoaderDevicePartUUID`, see above). If not set yet, this will be set to the file system path of the EFI executable of the booted unified kernel, in order to support systems that directly boot into a unified kernel image, bypassing any boot loader. Use `bootctl(1)` to view this data. `StubDevicePartUUID`; `StubImageIdentifier` Similar to `LoaderDevicePartUUID` and `LoaderImageIdentifier`, but indicates the location of the unified kernel image EFI binary rather than the location of the boot loader binary, regardless of whether booted via a boot loader or not. `StubDeviceURL` If the kernel image has been invoked via network booting this variable contains the originating URL. This may be used to automatically acquire additional resources from the same source. `StubInfo` Brief stub information. Use `bootctl(1)` to view this data. `StubPcrKernelImage` The PCR register index the kernel image, initrd image, boot splash, devicetree database, and the embedded command line are measured into, formatted as decimal ASCII string (e.g. `11`). This variable is set if a measurement was successfully completed, and remains unset otherwise. `StubPcrKernelParameters` The PCR register index the kernel command line and credentials are measured into, formatted as decimal ASCII string (e.g. `12`). This variable is set if a measurement was successfully completed, and remains unset otherwise. `StubPcrInitRDSysExts` The PCR register index the system extensions for the initrd, which are picked up from the file system the kernel image is located on. Formatted as decimal ASCII string (e.g. `13`). This variable is set if a measurement was successfully completed, and remains unset otherwise. `StubPcrInitRDConfExts` The PCR register index the configuration extensions for the initrd, which are picked up from the file system the kernel image is located on. Formatted as decimal ASCII string (e.g. `12`). This variable is set if a measurement was successfully completed, and remains unset otherwise. `StubProfile` The numeric index of the selected profile, without the `@`, formatted as decimal string. Set both on single-profile and multi-profile UKIs. (In the former case this variable will be set to `0` unconditionally.) `LoaderPcrSMBIOS` The PCR register index select SMBIOS structures are measured into — type 1 (system information, with the volatile "Wake-up Type" field zeroed out), type 2 (baseboard information) and type 11 (OEM strings). Formatted as decimal ASCII string (e.g. `1`). This variable is set only if all of these structures were measured successfully, and remains unset otherwise. `systemd-stub` performs this measurement only if it has not already been done in the same boot (e.g. by the boot loader), as indicated by this variable being set already. `LoaderBootSecret` A non-volatile EFI variable only accessible from the pre-boot environment (i.e. access from the OS is not permitted) that contains a per-system secret. It is set automatically by `systemd-stub` if not present already. A secret derived from the value of this EFI variable is passed to the OS in `/.extra/boot-secret`, see below. Note that some of the variables above may also be set by the boot loader. The stub will only set them if they are not set already. Some of these variables are defined by the [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE). # initrd Resources The following resources are passed as initrd cpio archives to the booted kernel, and thus make up the initial file system hierarchy in the initrd execution environment: `/` The main initrd from the `.initrd` PE section of the unified kernel image. `/.extra/credentials/*.cred` Credential files (suffix `.cred`) that are placed next to the unified kernel image (as described above) are copied into the `/.extra/credentials/` directory in the initrd execution environment. `/.extra/global_credentials/*.cred` Similarly, credential files in the `/loader/credentials/` directory in the file system the unified kernel image is placed in are copied into the `/.extra/global_credentials/` directory in the initrd execution environment. `/.extra/sysext/*.sysext.raw` System extension image files (suffix `.sysext.raw`) that are placed next to the unified kernel image (as described above) are copied into the `/.extra/sysext/` directory in the initrd execution environment. `/.extra/global_sysext/*.sysext.raw` Similarly, system extension image files (suffix `.sysext.raw`) that are placed in the `/loader/extensions/` directory in the file system the unified kernel image is placed in are copied into the `/.extra/global_sysext/` directory in the initrd execution environment. `/.extra/confext/*.confext.raw` Configuration extension image files (suffix `.confext.raw`) that are placed next to the unified kernel image (as described above) are copied into the `/.extra/confext/` directory in the initrd execution environment. `/.extra/global_confext/*.confext.raw` Similarly, configuration extension image files (suffix `.confext.raw`) that are placed in the `/loader/extensions/` directory in the file system the unified kernel image is placed in are copied into the `/.extra/global_confext/` directory in the initrd execution environment. `/.extra/tpm2-pcr-signature.json` The TPM2 PCR signature JSON object included in the `.pcrsig` PE section of the unified kernel image is copied into the `/.extra/tpm2-pcr-signature.json` file in the initrd execution environment. `/.extra/tpm2-pcr-public-key.pem` The PEM public key included in the `.pcrpkey` PE section of the unified kernel image is copied into the `/.extra/tpm2-pcr-public-key.pem` file in the initrd execution environment. `/.extra/profile`; `/.extra/os-release` The contents of the `.profile` and `.osrel` sections of the selected profile, if any. `/.extra/boot-secret` A 32 byte per-system secret which is derived from a 32 byte secret stored in an EFI variable (`LoaderBootSecret`, see above), which itself is only accessible to the pre-boot environment. This may be used for various early-boot cryptographic purposes, and OS file system access to it is restricted to root. The `IMAGE_ID=`/`ID=` data from the `.osrel` is hashed into the secret, to ensure that different images get a distinct secret passed. Moreover, a randomized 32 byte value stored in the ESP in the `/loader/boot-secret-mixin` file is hashed in as well, ensuring that distinct disks will result in different boot secrets. Note: this boot secret is ultimately protected only by firmware-enforced access controls on the EFI variable. This is generally a much weaker protection than TPM-based approaches have, and it is hence strongly recommended to use the TPM on systems that possess one. The boot secret is primarily intended to be a lower-security fallback for cases where a TPM is not available. Applications should never protect resources directly with this secret, but derive their own secret from it (by hashing it together with some application ID, in HMAC mode for example), in order not to accidentally leak the primary boot secret. Note that the boot secret is only available if the pre-boot environment had a suitable RNG source at the current boot or an earlier one. This source can be an initialized on-disk random seed or the EFI RNG support, or both. Note that all these files are located in the `tmpfs` file system the kernel sets up for the initrd file hierarchy and are thus lost when the system transitions from the initrd execution environment into the host file system. If these resources shall be kept around over this transition they need to be copied to a place that survives the transition first, for example via a suitable `tmpfiles.d(5)` line. By default, this is done for the TPM2 PCR signature and public key files. # SMBIOS Type 11 Strings `systemd-stub` can be configured using SMBIOS Type 11 strings. Applicable strings consist of a name, followed by `=`, followed by the value. Unless `systemd-stub` detects it is running inside a confidential computing environment, `systemd-stub` will search the table for a string with a specific name, and if found, use its value. The following strings are read: `io.systemd.stub.kernel-cmdline-extra` If set, the value of this string is added to the list of kernel command line arguments that are measured in PCR12 and passed to the kernel. `io.systemd.boot.loglevel` If set, the value of this string is used as log level. Valid values (from most to least critical) are `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, and `debug`. # Assembling Kernel Images In order to assemble a bootable Unified Kernel Image from various components as described above, use `ukify(1)`. # See Also `systemd-boot(7)`, `systemd.exec(5)`, `systemd-creds(1)`, `systemd-sysext(8)`, [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification), [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE), `ukify(1)`, `systemd-measure(1)`, [TPM2 PCR Measurements Made by systemd](https://systemd.io/TPM2_PCR_MEASUREMENTS) # systemd-suspend.service systemd systemd-suspend.service 8 systemd-suspend.service systemd-hibernate.service systemd-hybrid-sleep.service systemd-suspend-then-hibernate.service systemd-sleep System sleep state logic `systemd-suspend.service`, `systemd-hibernate.service`, `systemd-hybrid-sleep.service`, `systemd-suspend-then-hibernate.service`, `/usr/lib/systemd/system-sleep` # Description `systemd-suspend.service` is a system service that is pulled in by `suspend.target` and is responsible for the actual system suspend. Similarly, `systemd-hibernate.service` is pulled in by `hibernate.target` to execute the actual hibernation. Finally, `systemd-hybrid-sleep.service` is pulled in by `hybrid-sleep.target` to execute hybrid hibernation with system suspend and pulled in by `suspend-then-hibernate.target` to execute system suspend with a timeout that will activate hibernate later. Immediately before entering system suspend and/or hibernation `systemd-suspend.service` (and the other mentioned units, respectively) will run all executables in `/usr/lib/systemd/system-sleep/` and pass two arguments to them. The first argument will be `pre`, the second either `suspend`, `hibernate`, `hybrid-sleep`, or `suspend-then-hibernate` depending on the chosen action. An environment variable called `SYSTEMD_SLEEP_ACTION` will be set and contain the sleep action that is processing. This is primarily helpful for `suspend-then-hibernate` where the value of the variable will be `suspend`, `hibernate`, or `suspend-after-failed-hibernate` in cases where hibernation has failed. Immediately after leaving system suspend and/or hibernation the same executables are run, but the first argument is now `post`. All executables in this directory are executed in parallel, and execution of the action is not continued until all executables have finished. Note that `user.slice` will be frozen while the executables are running, so they should not attempt to communicate with any user services expecting a reply. Note that scripts or binaries dropped in `/usr/lib/systemd/system-sleep/` are intended for local use only and should be considered hacks. If applications want to react to system suspend/hibernation and resume, they should rather use the [Inhibitor Locks](https://systemd.io/INHIBITOR_LOCKS). Note that `systemd-suspend.service`, `systemd-hibernate.service`, `systemd-hybrid-sleep.service`, and `systemd-suspend-then-hibernate.service` should never be executed directly. Instead, trigger system sleep with a command such as `systemctl suspend` or `systemctl hibernate`. Internally, this service will echo a string like `mem` into `/sys/power/state`, to trigger the actual system suspend. What exactly is written where can be configured in the \[Sleep\] section of `/etc/systemd/sleep.conf` or a `sleep.conf.d` file. See `systemd-sleep.conf(5)`. Note that by default these services freeze `user.slice` while they run. This prevents the execution of any process in any of the user sessions while the system is entering into and resuming from sleep. Thus, this prevents the hooks in `/usr/lib/systemd/system-sleep/`, or any other process for that matter, from communicating with any user session process during sleep. # Options `systemd-sleep` understands the following commands: `suspend`; `hibernate`; `suspend-then-hibernate`; `hybrid-sleep` Suspend, hibernate, suspend then hibernate, or put the system to hybrid sleep. # See Also `systemd-sleep.conf(5)`, `systemd(1)`, `systemctl(1)`, `systemd.special(7)`, `systemd-halt.service(8)` # systemd-sysctl.service systemd systemd-sysctl.service 8 systemd-sysctl.service systemd-sysctl Configure kernel parameters at boot /usr/lib/systemd/systemd-sysctl OPTIONS CONFIGFILE `systemd-sysctl.service` # Description `systemd-sysctl.service` is an early boot service that configures `sysctl(8)` kernel parameters by invoking `/usr/lib/systemd/systemd-sysctl`. When invoked with no arguments, `/usr/lib/systemd/systemd-sysctl` applies all directives from configuration files listed in `sysctl.d(5)`. When invoked with positional arguments, the configuration specified by the command line arguments is executed. If the string `-` is specified instead of a filename, the configuration is read from standard input. If the argument is a file name (without any slashes), all configuration directories are searched for a matching file and the file found that has the highest priority is executed. If the argument is a path, that file is used directly without searching the configuration directories for any other matching file. In addition, `--prefix=` option may be used to limit which sysctl settings are applied. See `sysctl.d(5)` for information about the configuration of sysctl settings. After sysctl configuration is changed on disk, it must be written to the files in `/proc/sys/` before it takes effect. It is possible to update specific settings, or simply to reload all configuration, see Examples below. # Options `--prefix=` Only apply rules with the specified prefix. `--strict` Always return non-zero exit code on failure (including invalid sysctl variable name and insufficient permissions), unless the sysctl variable name is prefixed with a "-" character. `--verify` After `systemd-sysctl` successfully writes a value to a sysctl variable, the variable is read back and verified to match the value that was written. If the variable cannot be read back, or if the returned value differs from the written value, the write operation is considered to have failed. To detect such failures reliably, it is recommended to also specify `--strict`, and to ensure that the settings being applied are not prefixed with `-` (see `sysctl.d(5)` for details). This mode is disabled by default, since the format accepted by the kernel may differ from the format returned when the variable is read back, or the kernel may normalize the input. As a result, verification may not work reliably in all cases. Therefore, this option is best used together with explicitly specified configuration files or settings provided through `--inline`, or with `--prefix=` to restrict the set of sysctl variables being written. `--inline` Treat each positional argument as a separate configuration line instead of a file name. When specified, at least one positional argument must be specified. `--save=FILENAME` Before applying the loaded sysctl settings, write them to `/run/sysctl.d/` using the specified filename. If the filename does not end with `.conf`, the suffix is appended. This option requires one or more positional arguments. May be combined with `--inline`. This may be useful for creating runtime sysctl configuration files or overriding existing sysctl configuration files. `--revert=FILENAME` Before loading and applying the sysctl settings, removes the specified sysctl configuration file under `/run/sysctl.d/`. If the filename does not end with `.conf`, the suffix is appended. This may be useful for removing configuration files created by `--save=`. # Credentials `systemd-sysctl` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `sysctl.extra` The contents of this credential may contain additional lines to operate on. The credential contents should follow the same format as any other `sysctl.d/` drop-in configuration file. If this credential is passed it is processed after all of the drop-in files read from the file system. The settings configured in the credential hence take precedence over those in the file system. Note that by default the `systemd-sysctl.service` unit file is set up to inherit the `sysctl.extra` credential from the service manager. # Examples
Reset all sysctl settings
systemctl restart systemd-sysctl
View coredump handler configuration
# sysctl kernel.core_pattern kernel.core_pattern = |/usr/libexec/abrt-hook-ccpp %s %c %p %u %g %t %P %I
Update and verify coredump handler configuration
# /usr/lib/systemd/systemd-sysctl --prefix kernel.core_pattern --strict --verify This searches all the directories listed in `sysctl.d(5)` for configuration files and writes `/proc/sys/kernel/core_pattern`. The sysctl variable is read back and verified. If writing or verification fails, the command exits with a non-zero status, unless the corresponding setting is prefixed with `-`.
Update coredump handler configuration according to a specific file
# /usr/lib/systemd/systemd-sysctl 50-coredump.conf This applies all the settings found in `50-coredump.conf`. Either `/etc/sysctl.d/50-coredump.conf`, or `/run/sysctl.d/50-coredump.conf`, or `/usr/lib/sysctl.d/50-coredump.conf` will be used, in the order of preference.
Disable IPv6 on an interface and save the specified setting
# /usr/lib/systemd/systemd-sysctl --save=99-disable-ipv6-foo - <
Remove a runtime sysctl configuration file
# /usr/lib/systemd/systemd-sysctl --revert=99-disable-ipv6-foo --prefix=/net/ipv6/conf/foo This removes `/run/sysctl.d/99-disable-ipv6-foo.conf`, and applies the remaining sysctl settings for the network interface `foo`.
See `sysctl(8)` for various ways to directly apply sysctl settings. # See Also `systemd(1)`, `sysctl.d(5)`, `sysctl(8)` # systemd-sysext systemd systemd-sysext 8 systemd-sysext systemd-sysext.service systemd-sysext-initrd.service systemd-sysext-sysroot.service systemd-confext systemd-confext.service systemd-confext-initrd.service systemd-confext-sysroot.service Activates System Extension Images systemd-sysext OPTIONS COMMAND `systemd-sysext.service` systemd-confext OPTIONS COMMAND `systemd-confext.service` # Description `systemd-sysext` activates/deactivates system extension images. System extension images may – dynamically at runtime — extend the `/usr/` and `/opt/` directory hierarchies with additional files. This is particularly useful on immutable system images where a `/usr/` and/or `/opt/` hierarchy residing on a read-only file system shall be extended temporarily at runtime without making any persistent modifications. System extension images should contain files and directories similar in fashion to regular operating system tree. When one or more system extension images are activated, their `/usr/` and `/opt/` hierarchies are combined via `overlayfs` with the same hierarchies of the host OS, and the host `/usr/` and `/opt/` overmounted with it ("merging"). When they are deactivated, the mount point is disassembled — again revealing the unmodified original host version of the hierarchy ("unmerging"). Merging thus makes the extension's resources suddenly appear below the `/usr/` and `/opt/` hierarchies as if they were included in the base OS image itself. Unmerging makes them disappear again, leaving in place only the files that were shipped with the base OS image itself. Files and directories contained in the extension images outside of the `/usr/` and `/opt/` hierarchies are *not* merged, and hence have no effect when included in a system extension image. In particular, files in the `/etc/` and `/var/` included in a system extension image will *not* appear in the respective hierarchies after activation. System extension images are strictly read-only by default. On mutable host file systems, `/usr/` and `/opt/` hierarchies become read-only while extensions are merged, unless mutability is enabled. Mutability may be enabled via the `--mutable=` option and the `Mutable=` option in the configuration file; see "Mutability" below for more information. Various command options can be configured globally via configuration files. See `sysext.conf(5)` for details. System extensions are supposed to be purely additive, i.e. they are supposed to include only files that do not exist in the underlying basic OS image. However, the underlying mechanism (overlayfs) also allows overlaying or removing files, but it is recommended not to make use of this. System extension images may be provided in the following formats: 1. Plain directories or btrfs subvolumes containing the OS tree 2. Disk images with a GPT disk label, following the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification) 3. Disk images lacking a partition table, with a naked Linux file system (e.g. erofs, squashfs or ext4) These image formats are the same ones that `systemd-nspawn(1)` supports via its `--directory=`/`--image=` switches and those that the service manager supports via `RootDirectory=`/`RootImage=`. Similar to them they may optionally carry Verity authentication information. LUKS encrypted extension images carrying a TPM2 token (as enrolled via the `--tpm2-device=` option of `systemd-cryptenroll(1)`) are unlocked via the local TPM2 automatically, without any passphrase. This may be turned off via the `$SYSTEMD_DISSECT_TPM2_UNLOCK` environment variable. System extensions are searched for in the directories `/etc/extensions/`, `/run/extensions/` and `/var/lib/extensions/`. The first two listed directories are not suitable for carrying large binary images, however are still useful for carrying symlinks to them. The primary place for installing system extensions is `/var/lib/extensions/`. Any directories found in these search directories are considered directory based extension images; any files with the `.raw` suffix are considered disk image based extension images. When invoked in the initrd, the additional directory `/.extra/sysext/` is included in the directories that are searched for extension images. Note however, that by default a tighter image policy applies to images found there, though, see below. This directory is populated by `systemd-stub(7)` with extension images found in the system's EFI System Partition. During boot, system and configuration extension images are activated automatically if the `systemd-sysext.service` and `systemd-confext.service` services are enabled. Note that these services run only after the underlying file systems where system and configuration extensions may be located have been mounted. To make it possible to ship resources that are processed by subsystems running in the earliest boot stages (for example, system services or `systemd-sysusers(8)` definitions), the `systemd-sysext-sysroot.service` and `systemd-confext-sysroot.service` initrd services are provided. Currently, these services cannot be used to merge system extensions from `/sysroot/var/lib/extensions/` and configuration extensions from `/sysroot/var/lib/confexts/` when the `/var/` partition is split off. These extensions are later merged by the `systemd-sysext.service` and `systemd-confext.service` services during the main OS boot process. Also, see the [Portable Services](https://systemd.io/PORTABLE_SERVICES) page for a simple mechanism for shipping system services in disk images, in a similar fashion to OS extensions. Note the differences in isolation between these two mechanisms: while system extensions directly extend the underlying OS image with additional files that appear as if they were shipped in the OS image itself and thus imply no security isolation, portable services imply service-level sandboxing in one way or another. Binaries shipped in system extensions can only link against libraries from the host if the extension is bound to the version of the host OS (see further below) or otherwise have to use static linking. Portable services, however, are fully decoupled from the host as they ship their own library dependencies. The `systemd-sysext.service` and `systemd-confext.service` services are guaranteed to finish start-up before `basic.target` is reached; i.e., by the time regular services initialize (those which do not use `DefaultDependencies=no`), the files and directories provided by system and configuration extensions are available in `/usr/`, `/opt/`, and `/etc/` and may be accessed. System and configuration extensions can also be used to extend the initrd, and the `systemd-sysext-initrd.service` and `systemd-confext-initrd.service` initrd services are provided. Note that some limitations apply: resources that are used in the earliest boot stages of the initrd (e.g. system services) cannot be updated. Note that there is no concept of enabling/disabling installed system extension images: all installed extension images are automatically activated at boot. However, you can place an empty directory named like the extension (no `.raw`) in `/etc/extensions/` to "mask" an extension with the same name in a system folder with lower precedence. It is also possible to disable automatic merging altogether using the `rd.systemd.sysext=`, `rd.systemd.confext=`, `systemd.sysext=`, and `systemd.confext=` kernel command line options. Note that `systemd-sysext-sysroot.service` and `systemd-confext-sysroot.service` are controlled by the `systemd.sysext=` and `systemd.confext=` options, as these services merge system and configuration extensions for the main system, not for the initrd. A simple mechanism for version compatibility is enforced: a system extension image must carry a `/usr/lib/extension-release.d/extension-release.NAME` file, which must match its image name, that is compared with the host `os-release` file: the contained `ID=` fields have to match unless `_any` is set for the extension. If the extension `ID=` is not `_any`, the `SYSEXT_LEVEL=` field (if defined) has to match. If the latter is not defined, the `VERSION_ID=` field has to match instead. If the extension defines the `ARCHITECTURE=` field and the value is not `_any` it has to match the kernel's architecture reported by `uname(2)` but the used architecture identifiers are the same as for `ConditionArchitecture=` described in `systemd.unit(5)`. `EXTENSION_RELOAD_MANAGER=` can be set to 1 if the extension requires a service manager reload after application of the extension. `EXTENSION_RESTART_UNITS=` and `EXTENSION_RELOAD_OR_RESTART_UNITS=` can be set to a whitespace-separated list of unit names (e.g. `EXTENSION_RESTART_UNITS="my.service other.service"`) that `systemd-sysext`/`systemd-confext` should restart resp. reload (or restart, if the unit does not support reloading) after merging or refreshing the extension, and after unmerging it. Use `EXTENSION_RESTART_UNITS=` for units whose binary the extension replaces (a reload would not pick up the new binary), and `EXTENSION_RELOAD_OR_RESTART_UNITS=` for units the extension extends with configuration drop-ins only (so reload-capable services are not needlessly interrupted). If a unit has disappeared, e.g., on unmerge because it was part of the extension, it is stopped instead. If the same unit is listed in both fields, `EXTENSION_RESTART_UNITS=` takes precedence. Listing any unit in either field implies `EXTENSION_RELOAD_MANAGER=1`, as the service manager would otherwise not yet (or no longer) see the unit files shipped by the extension. Note that these settings do not take effect when the extension is merged for the system already from the initrd and extensions should still ship a `.wants/` or `.upholds/` symlink from the unit's install target to ensure the unit starts at boot. System extensions should not ship a `/usr/lib/os-release` file (as that would be merged into the host `/usr/` tree, overriding the host OS version data, which is not desirable). The `extension-release` file follows the same format and semantics, and carries the same content, as the `os-release` file of the OS, but it describes the resources carried in the extension image. The `systemd-confext` concept follows the same principle as the `systemd-sysext(8)` functionality but instead of working on `/usr` and `/opt`, `confext` will extend only `/etc`. Files and directories contained in the confext images outside of the `/etc/` hierarchy are *not* merged, and hence have no effect when included in the image. Formats for these images are of the same as sysext images. The merged hierarchy will be mounted with `nosuid` and (if not disabled via `--noexec=false`) `noexec`. Just like sysexts, confexts are strictly read-only by default. Merging confexts on mutable host file systems will result in `/etc/` becoming read-only. As with sysexts, mutability can be enabled via the `--mutable=` option. Refer to "Mutability" below for more information. Confexts are looked for in the directories `/run/confexts/`, `/var/lib/confexts/`, `/usr/lib/confexts/` and `/usr/local/lib/confexts/`. The first listed directory is not suitable for carrying large binary images, however is still useful for carrying symlinks to them. The primary place for installing configuration extensions is `/var/lib/confexts/`. Any directories found in these search directories are considered directory based confext images; any files with the `.raw` suffix are considered disk image based confext images. Again, just like sysext images, the confext images will contain a `/etc/extension-release.d/extension-release.NAME` file, which must match the image name (with the usual escape hatch of the `user.extension-release.strict` `xattr(7)`), and again with content being one or more of `ID=`, `VERSION_ID=`, and `CONFEXT_LEVEL`. Confext images will then be checked and matched against the base OS layer. # Uses The primary use case for system images are immutable environments where debugging and development tools shall optionally be made available, but not included in the immutable base OS image itself (e.g. `strace(1)` and `gdb(1)` shall be an optionally installable addition in order to make debugging/development easier). System extension images should not be misunderstood as a generic software packaging framework, as no dependency scheme is available: system extensions should carry all files they need themselves, except for those already shipped in the underlying host system image. Typically, system extension images are built at the same time as the base OS image — within the same build system. Another use case for the system extension concept is temporarily overriding OS supplied resources with newer ones, for example to install a locally compiled development version of some low-level component over the immutable OS image without doing a full OS rebuild or modifying the nominally immutable image. (e.g. "install" a locally built package with `DESTDIR=/var/lib/extensions/mytest make install && systemd-sysext refresh`, making it available in `/usr/` as if it was installed in the OS image itself.) This case works regardless of whether the underlying host `/usr/` is managed as immutable disk image or is a traditional package manager controlled (i.e. writable) tree. With `systemd-confext` one can perform runtime reconfiguration of OS services. Sometimes, there is a need to swap certain configuration parameter values or restart only a specific service without deployment of new code or a complete OS deployment. In other words, we want to be able to tie the most frequently configured options to runtime updateable flags that can be changed without a system reboot. This will help reduce servicing times when there is a need for changing the OS configuration. It also provides a reliable tool for managing configuration because all old configuration files disappear when the `systemd-confext` image is removed. # Mutability By default, merging system extensions on mutable host file systems will render `/usr/` and `/opt/` hierarchies read-only. Merging configuration extensions will have the same effect on `/etc/`. Mutable mode allows writes to these locations when extensions are merged. The following modes are supported: 1. `disabled`: Force immutable mode even if write routing directories exist below `/var/lib/extensions.mutable/`. This is the default. 2. `auto`: Automatic mode. Mutability is disabled by default and only enabled if a corresponding write routing directory exists below `/var/lib/extensions.mutable/`. 3. `enabled`: Force mutable mode and automatically create write routing directories below `/var/lib/extensions.mutable/` when required. 4. `import`: Force immutable mode like `disabled` above, but merge the contents of directories below `/var/lib/extensions.mutable/` into the host file system. 5. `ephemeral`: Force mutable mode like `enabled` above, but instead of using write routing directory below `/var/lib/extensions.mutable/`, `systemd-sysext` will use empty ephemeral directories. This means that the modifications made in the merged hierarchies will be gone when the hierarchies are unmerged. 6. `ephemeral-import`: Force mutable mode like `ephemeral` above, but instead of ignoring the contents of write routing directories under `/var/lib/extensions.mutable/`, merge them into the host file system, like `import` does. See "Options" below on specifying modes using the `--mutable=` command line option. With exception of the ephemeral mode, the mutable mode routes writes to subdirectories in `/var/lib/extensions.mutable/`. Writes to `/usr/` are directed to `/var/lib/extensions.mutable/usr/`, writes to `/opt/` are directed to `/var/lib/extensions.mutable/opt/`, and, writes to `/etc/` land in `/var/lib/extensions.mutable/etc/`. If `usr/`, `opt/`, or `etc/` in `/var/lib/extensions.mutable/` are symlinks, then writes are directed to the symlinks' targets. Consequently, to retain mutability of a host file system, create symlinks `/var/lib/extensions.mutable/etc/` → `/etc/`, `/var/lib/extensions.mutable/usr/` → `/usr/`, `/var/lib/extensions.mutable/opt/` → `/opt/` to route writes back to the original base directory hierarchy. Alternatively, a temporary file system may be mounted to `/var/lib/extensions.mutable/`, or symlinks in `/var/lib/extensions.mutable/` may point to sub-directories on a temporary file system (e.g. below `/tmp/`) to only allow ephemeral changes. Note that this is not the same as ephemeral mode, because the temporary file system will still exist after unmerging. # Commands The following commands are understood by both the sysext and confext concepts: `status` When invoked without any command verb, or when `status` is specified the current merge status is shown, separately (for both `/usr/` and `/opt/` of sysext and for `/etc/` of confext). `merge` Merges all currently installed system extension images into `/usr/` and `/opt/`, by overmounting these hierarchies with an `overlayfs` file system combining the underlying hierarchies with those included in the extension images. This command will fail if the hierarchies are already merged. For confext, the merge happens into the `/etc/` directory instead. `unmerge` Unmerges all currently installed system extension images from `/usr/` and `/opt/` for sysext and `/etc/`, for confext, by unmounting the `overlayfs` file systems created by `merge` prior. `refresh` A combination of `unmerge` and `merge`: if already mounted the existing `overlayfs` instance is unmounted temporarily, and then replaced by a new version. This command is useful after installing/removing system extension images, in order to update the `overlayfs` file system accordingly. If no system extensions are installed when this command is executed, the equivalent of `unmerge` is executed, without establishing any new `overlayfs` instance. Note that currently there's a brief moment where neither the old nor the new `overlayfs` file system is mounted. This implies that all resources supplied by a system extension will briefly disappear — even if it exists continuously during the refresh operation. `list` A brief list of installed extension images is shown. # Options `--root=` Operate relative to the specified root directory, i.e. establish the `overlayfs` mount not on the top-level host `/usr/` and `/opt/` hierarchies for sysext or `/etc/` for confext, but below some specified root directory. `--force` When merging system extensions into `/usr/` and `/opt/` for sysext and `/etc/` for confext, ignore version incompatibilities, i.e. force merging regardless of whether the version information included in the images matches the host or not. `--always-refresh=yes|no` When refreshing system extensions on `/usr/` and `/opt/` for sysext and `/etc/` for confext, ignore when the existing merged extensions already match what would be merged. By default the refresh is skipped when no changes are found. Note that changes done to an extension directory while it's merged are ignored without this flag (unless another extension got changed). Note that changing the contents while merged is also undefined behavior in overlayfs. `--image-policy=policy` Takes an image policy string as argument, as per `systemd.image-policy(7)`. The policy is enforced when operating on system extension disk images. If not specified, defaults to `root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent` for system extensions, i.e. only the root and `/usr/` file systems in the image are used. For configuration extensions defaults to `root=verity+signed+encrypted+unprotected+absent`. When run in the initrd and operating on a system extension image stored in the `/.extra/sysext/` directory a slightly stricter policy is used by default: `root=signed+absent:usr=signed+absent`, see above for details. `--mutable=BOOL|auto|import|ephemeral|ephemeral-import|help` Set mutable mode. The special value `help` will list the known values. `no` force immutable mode even with write routing directories present. This is the default. `auto` enable mutable mode individually for `/usr/`, `/opt/`, and `/etc/` if write routing sub-directories or symlinks are present in `/var/lib/extensions.mutable/`; disable otherwise. See "Mutability" above for more information on write routing. `yes` force mutable mode. Write routing directories will be created in `/var/lib/extensions.mutable/` if not present. `import` immutable mode, but with contents of write routing directories in `/var/lib/extensions.mutable/` also merged into the host file system. `ephemeral` force mutable mode, but with contents of write routing directories in `/var/lib/extensions.mutable/` being ignored, and modifications of the host file system being discarded after unmerge. `ephemeral-import` force mutable mode, with contents of write routing directories in `/var/lib/extensions.mutable/` being merged into the host file system, but with the modifications made to the host file system being discarded after unmerge. `help` list known values and exit immediately. `--noexec=BOOL` When merging configuration extensions into `/etc/` the `MS_NOEXEC` mount flag is used by default. This option can be used to disable it. `--no-reload` When used with `merge`, `unmerge` or `refresh`, do not reload daemon after executing the changes even if an extension that is applied requires a reload via the `EXTENSION_RELOAD_MANAGER=` set to 1. This also skips processing any units listed via `EXTENSION_RESTART_UNITS=` or `EXTENSION_RELOAD_OR_RESTART_UNITS=`. # Exit status On success, 0 is returned. # See Also `systemd(1)`, `sysext.conf(5)`, `systemd-nspawn(1)`, `systemd-stub(7)`, `importctl(1)` # systemd-sysinstall systemd systemd-sysinstall 8 systemd-sysinstall systemd-sysinstall.service Simple OS installer systemd-sysinstall OPTIONS BLOCKDEVICE `systemd-sysinstall.service` # Description `systemd-sysinstall` is a simple terminal and command line based operating system installer tool. Its primary use-case is to act as an automatically started interactive interface when booting from an installer medium (e.g. a USB stick), in order to install an OS onto a target disk. However, it may also be invoked directly from a shell. It executes the following steps: 1. It prompts the user for the target disk to install the OS on. (Unless the block device is already specified on the command line, or is picked automatically via `--device-auto`.) 2. It validates whether the disk is suitable (i.e. large enough, and with enough free/unpartitioned space) for an OS installation. If it is generally suitable the user is prompted if they want to erase the disk before installation, or if the OS shall be added to the existing partitions on the disk (the latter only if enough free/unpartitioned disk space is available). 3. It prompts the user whether to register the newly installed OS with the firmware boot option menu. 4. It requests confirmation from the user, after showing a summary of the planned OS installation. 5. It invokes `systemd-creds(1)`'s `encrypt` command in order to generate encrypted (TPM locked, if available) system credential files for a few, very basic system settings of the currently booted system (locale, keymap, timezone), which it will install on the target disk, parameterizing the invoked kernel. (Or in other words, it prepares that some settings already in effect on the installer system are propagated securely onto the new installation.) 6. It invokes `systemd-repart(8)` with a definitions directory of `/usr/lib/repart.sysinstall.d/` (only if populated – if not will use the default of `/usr/lib/repart.d/`). This is supposed to set up the basic OS partition structure on the target disk and copies in basic OS partitions (most importantly the `/usr/` hierarchy). 7. It invokes `bootctl(1)`'s `link` command to install an OS kernel image onto the target disk's ESP/XBOOTLDR, together with the credential files prepared earlier. 8. It invokes `bootctl(1)`'s `install` command to install the `systemd-boot(7)` boot loader onto the target disk's ESP. 9. After confirmation, it reboots the system. Note that the prompts/confirmation may be disabled via the command line, enabling fully automatic, non-interactive installation. See below. Note this tool does not interactively query the user for a user to create or a root password to be set on the target system, under the assumption these questions are better prompted from within the newly installed system's first boot process, for example via the `systemd-firstboot(1)` or `systemd-homed-firstboot.service` components. Note that if required such settings may be propagated explicitly via the `--load-credential=` switch below. # Options The following options are understood: `--definitions=` Overrides the directory where `systemd-repart` shall read its partition definitions from, in place of the default of `/usr/lib/repart.sysinstall.d/`. `--device-auto` Automatically pick the target disk instead of prompting for it or taking it from the command line. The tool watches the block devices of the system (via udev) and waits for the list of candidate disks to settle: the timeout configured with `--device-auto-timeout=` starts at invocation and is restarted whenever a block device appears, disappears or changes. Once it expires without further changes, the single candidate disk present at that moment is selected as installation target. If no candidate disk is present when the timeout expires, or if at any time more than one candidate disk is present, the installation fails. Candidate disks are those `systemd-repart(8)` would offer in the interactive prompt (i.e. that support partition scanning, are writable, not the disk the running system is booted from, and contain a medium). If the disk the running system is booted from cannot be determined – and hence cannot reliably be excluded from the candidate set – the automatic selection is refused. Cannot be combined with an explicitly specified block device. This is primarily useful together with `--confirm=no`, `--erase=` and `--variables=`, for fully unattended installations. `--device-auto-timeout=` Configures the settle timeout for `--device-auto`, i.e. for how long the list of candidate disks must remain unchanged before a disk is selected. Takes a time span, see `systemd.time(7)`. Defaults to 30s. `--welcome=` Takes a boolean argument. Controls whether to show the brief welcome text normally displayed at the beginning of the installation. Defaults to true. `--chrome=` Takes a boolean argument. Controls whether to show the colored bars at the top and bottom of the terminal interface. Defaults to true. `--erase=` Takes a boolean argument. Controls whether to erase the current contents of the target disk. If this switch is not used the user is prompted. `--confirm=` Takes a boolean argument. Controls whether to interactively query the user for confirmation before initiating the OS installation. Defaults to true. `--reboot=` Takes a boolean argument. Controls whether to reboot the system after completing the installation. Defaults to false. `--variables=` Takes a boolean argument. Controls whether to register the installed boot loader in the firmware's boot options database. If not specified the user will be prompted. `--summary=` Takes a boolean argument. Controls whether to show a summary of the choices made before asking for confirmation to proceed with the OS installation. Defaults to true. `--kernel=` Takes a path to a unified kernel image (UKI). Explicitly selects the kernel image to install on the target disk. If unspecified the currently booted kernel image is installed on the target disk. `--set-credential=id:value` Accepts an additional system credential to encrypt (with a key generated on the local TPM, if available, and the null key otherwise) and place next to the installed kernel image in the ESP. This may be used to parameterize the installed kernel with arbitrary system credentials. Do not use this switch for sensitive data (such as passwords), use `--load-credential=` instead, see below. May be used multiple times to configure multiple credentials. Note that three system credentials are propagated in similar fashion to the target system: the locale, keymap and timezone. This may be controlled by the relevant `--copy-locale=`, `--copy-keymap=` and `--copy-timezone=` options below. See `systemd.system-credentials(7)` for a list of well-known system credentials that may be propagated this way. (Note that you may pass arbitrary additional credentials this way, that can be consumed by any service of your choice, via the usual system credentials logic.) `--load-credential=id:path` Similar to `--set-credential=` but reads the credential value from a file on disk or an `AF_UNIX` socket in the file system. This is generally preferable for sensitive data, such as passwords. `--copy-locale=`; `--copy-keymap=`; `--copy-timezone=` These options take boolean parameters. They control whether the indicated system settings shall be propagated from the currently running system into the new target OS installation. These options default to true. Typically, these three settings are the minimal settings that need to be configured during early boot of an installer medium in order to make the installer tool accessible to the user. The `systemd-firstboot(1)` tool may be used to query the user interactively when the OS install medium is booted for these properties. By propagating these settings to the target installation via system credentials they do not need to be queried again on first boot of the new installation. `--mute-console=` Takes a boolean argument. Controls whether to disable kernel and service manager log output to the console the installer is invoked on temporarily while running, in order to avoid interleaved output. Defaults to false. # Exit status On success, 0 is returned, and a non-zero failure code otherwise. # Example
Invoke the tool for a fully automatic non-interactive OS installation
systemd-sysinstall \ /dev/disk/by-id/nvme-Micron_MTFDKBA1T0TFH_214532D0CDA5 \ --erase=yes \ --confirm=no \ --variables=yes \ --load-credential=ssh.authorized_keys.root:my-ssh-key This installs the OS on the selected disk, erasing any previous contents, without confirmation, registers it in the firmware, and drops in the SSH key for the root user, read from the `my-ssh-key` file in the current directory.
# See Also `systemd(1)`, `systemd-creds(1)`, `systemd-repart(8)`, `bootctl(1)`, `systemd-firstboot(1)`, `systemd-boot(7)`, `systemd.system-credentials(7)` # systemd-system-update-generator systemd systemd-system-update-generator 8 systemd-system-update-generator Generator for redirecting boot to offline update mode `/usr/lib/systemd/system-generators/systemd-system-update-generator` # Description `systemd-system-update-generator` is a generator that automatically redirects the boot process to `system-update.target`, if `/system-update` or `/etc/system-update` exists. This is required to implement the logic explained in the `systemd.offline-updates(7)`. `systemd-system-update-generator` implements `systemd.generator(7)`. # See Also `systemd(1)`, `systemd.special(7)` # systemd-sysupdate systemd systemd-sysupdate 8 systemd-sysupdate systemd-sysupdate-update.service systemd-sysupdate-update.timer systemd-sysupdate-reboot.service systemd-sysupdate-reboot.timer systemd-sysupdate-auto-enable.service systemd-sysupdate.service systemd-sysupdate.timer Automatically Update OS or Other Resources systemd-sysupdate OPTIONS `systemd-sysupdate-update.service` # Description `systemd-sysupdate` atomically updates the host OS, container images, portable service images or other sources, based on the transfer configuration files described in `sysupdate.d(5)`. This tool implements file, directory, or partition based update schemes, supporting multiple parallel installed versions of specific resources in an A/B (or even: A/B/C, A/B/C/D/, …) style. A/B updating means that when one version of a resource is currently being used, the next version can be downloaded, unpacked, and prepared in an entirely separate location, independently of the first, and — once complete — be activated, swapping the roles so that it becomes the used one and the previously used one becomes the one that is replaced by the next update, and so on. The resources to update are defined in transfer files, one for each resource to be updated. For example, resources that may be updated with this tool could be: a root file system partition, a matching Verity partition plus one kernel image. The combination of the three would be considered a complete OS update. The tool updates partitions, files or directory trees always in whole, and operates with at least two versions of each of these resources: the *current* version, plus the *next* version: the one that is being updated to, and which is initially incomplete as the downloaded data is written to it; plus optionally more versions. Once the download of a newer version is complete it becomes the current version, releasing the version previously considered current for deletion/replacement/updating. When installing new versions the tool will directly download, decompress, unpack and write the new version into the destination. This is done in a robust fashion so that an incomplete download can be recognized on next invocation, and flushed out before a new attempt is initiated. Note that when writing updates to a partition, the partition has to exist already, as `systemd-sysupdate` will not automatically create new partitions. Use a tool such as `systemd-repart(8)` to automatically create additional partitions to be used with `systemd-sysupdate` on boot. The tool can both be used on the running OS, to update the OS in "online" state from within itself, and on "offline" disk images, to update them from the outside based on transfer files embedded in the disk images. For the latter, see `--image=` below. The latter is particularly interesting to update container images or portable service images. The `systemd-sysupdate-update.service` system service will automatically update the host OS based on the installed transfer files. It is triggered in regular intervals via `systemd-sysupdate-update.timer`. The `systemd-sysupdate-reboot.service` will automatically reboot the system after a new version is installed. It is triggered via `systemd-sysupdate-reboot.timer`. The two services are separate from each other as it is typically advisable to download updates regularly while the system is up, but delay reboots until the appropriate time (i.e. typically at night). The two sets of service/timer units may be enabled separately. The `systemd-sysupdate-auto-enable.service` system service automatically enables all suggested components and all suggested features of all components before each update. It is ordered before and pulled in by `systemd-sysupdate-update.service`, and is not enabled by default. Enable it if newly suggested components and features shall be picked up automatically as they become available, rather than requiring manual `enable-component`/`enable-feature` invocations. For details about transfer files and examples see `sysupdate.d(5)`. # Command The following commands are understood: `list` \[\\] If invoked without an argument, enumerates downloadable and installed versions, and shows a summarizing table with the discovered versions and their properties, including whether there's a newer candidate version to update to. If a version argument is specified, shows details about the specific version, including the individual files that need to be transferred to acquire the version. If no command is explicitly specified this command is implied. `features` \[\\] If invoked without an argument, enumerates optional features and shows a summarizing table, including which features are enabled or disabled. If a feature argument is specified, shows details about the specific feature, including the transfers that are controlled by the feature. `enable-feature` \…; `disable-feature` \… Enables or disables the specified optional features. This writes an `Enabled=` setting into a drop-in next to the feature definition, see `sysupdate.features(5)` for details. The features may be specified either as arguments or selected via the `--feature-all` or `--feature-suggested` switches. Note that this only changes the configuration: to actually download the newly enabled transfers, or remove the disabled ones, invoke `update` or `vacuum` afterwards. `check-new` Checks if there's a new version available. This internally enumerates downloadable and installed versions and returns exit status 0 if there's a new version to update to, non-zero otherwise. If there is a new version to update to, its version identifier is written to standard output. `update` \[--offline\] \[\\] Installs (updates to) the specified version, or if none is specified to the newest version available. If the version is already installed or no newer version available, no operation is executed. If `--offline` is specified, the update must already have been acquired using `acquire` and, if so, this pre-acquired version is the one which will be updated to. `acquire` \[\\] Acquires (downloads) the specified version, ready to install it. If no version is specified, the newest version available is acquired. If the version is already installed or no newer version is available, no operation is executed. If a new version to install/update to is found, old installed versions are deleted until at least one new version can be installed, as configured via `InstanceMax=` in `sysupdate.d(5)`, or via the available partition slots of the right type. This implicit operation can also be invoked explicitly via the `vacuum` command described below. `vacuum` Deletes old installed versions until the limits configured via `InstanceMax=` in `sysupdate.d(5)` are met again. Normally, it should not be necessary to invoke this command explicitly, since it is implicitly invoked whenever a new update is initiated. `pending` Checks whether a newer version of the OS is installed than the one currently running. Returns zero if so, non-zero otherwise. This compares the newest installed version's identifier with the OS image version as reported by the `IMAGE_VERSION=` field in `/etc/os-release`. If the former is newer than the latter, an update was apparently completed but not activated (i.e. rebooted into) yet. `reboot` Similar to the `pending` command but immediately reboots in case a newer version of the OS has been installed than the one currently running. This operation can be done implicitly together with the `update` command, after a completed update via the `--reboot` switch, see below. This command will execute no operation (and return success) if no update has been installed, and thus the system was not rebooted. `components` Lists components that can be updated. This enumerates the `/etc/sysupdate.*.d/`, `/run/sysupdate.*.d/` and `/usr/lib/sysupdate.*.d/` directories that contain transfer files, as well as the components offered by component providers (see `sysupdate.components(5)`). This command is useful to list possible parameters for `--component=` (see below). `enable-component` \…; `disable-component` \… Enables or disables the specified components. This writes an `Enabled=` setting into a drop-in next to the component definition. The components may be specified either as arguments or selected via the `--component=`, `--component-all` or `--component-suggested` switches. `cleanup` Removes orphaned files that were previously installed by a transfer, but are no longer owned by any currently defined transfer file. Whenever a resource is installed into the file system, `systemd-sysupdate` records the target directory and the matching pattern in an installation database below `/var/lib/systemd/sysupdate/`. This command iterates through these records, determines which files they match, and deletes those that are no longer covered by any of the patterns of the transfer files currently in place. This is useful to garbage-collect files that used to be owned by a transfer file that has since been modified, disabled or removed altogether (for example because a component is no longer being updated). By default only the selected component is processed (i.e. the one selected via `--component=`, or the default one if none were selected). Use `--component-all` to process all components known to the installation database in a single invocation. This operation only removes files that were installed into the file system (i.e. resources of type `regular-file`, `directory` and `subvolume`, see `sysupdate.d(5)`); it does not touch partition-based resources. # Options The following options are understood: `--component=`; `-C` Selects the component to update. Takes a component name as argument. This has the effect of slightly altering the search logic for transfer files. If this switch is not used, the transfer files are loaded from `/etc/sysupdate.d/*.conf`, `/run/sysupdate.d/*.conf` and `/usr/lib/sysupdate.d/*.conf`. If this switch is used, the specified component name is used to alter the directories to look in to be `/etc/sysupdate.component.d/*.conf`, `/run/sysupdate.component.d/*.conf` and `/usr/lib/sysupdate.component.d/*.conf`, each time with the `component` string replaced with the specified component name. If none of these directories exist, the definition of the component is acquired from the component providers, see `sysupdate.components(5)`. Use the `components` command to list available components to update. This enumerates the directories matching this naming rule. Components may be used to define a separate set of transfer files for different components of the OS that shall be updated separately. Do not use this concept for resources that shall always be updated together in a synchronous fashion. Simply define multiple transfer files within the same `sysupdate.d/` directory for these cases. This option may not be combined with `--definitions=`, nor with the `pending` and `reboot` commands or the `--reboot` switch, which only apply to the booted OS version. `--component-all`; `-A` Instead of operating on a single component, operate on all known components (as well as the default, component-less installation). This is supported for the `update`, `acquire`, `cleanup`, `enable-feature`, `disable-feature`, `enable-component` and `disable-component` commands; all other commands will fail if this switch is used. This option may not be combined with `--component=`. `--component-suggested`; `-S` Similar to `--component-all`, but operates only on the components that are currently *suggested* for this system, as determined by the `Suggest=` and `SuggestOn…=` settings in the component definition files. This is supported for the `enable-component` and `disable-component` commands. Both commands operate on the same set of components, thus `disable-component` undoes what `enable-component` did. This option may not be combined with `--component=`. In order to reconcile the system according to suggestions, i.e., to also turn off the components that are not (or no longer) suggested, first disable all components with `--component-all`, then enable the suggested ones with this switch. Note that this has wider consequences than the equivalent reconciliation of optional features because components are enabled by default, and a component counts as not suggested unless `Suggest=` or one of the `SuggestOn…=` settings says otherwise. Reconciling hence explicitly disables every component that is not suggested, including components that ship no `*.component` file at all. The default component is not affected. `--feature-all`; `-a` Instead of operating on features specified on the command line, operate on all optional features known to the selected component(s). This is supported for the `enable-feature` and `disable-feature` commands. `--feature-suggested`; `-s` Similar to `--feature-all`, but operates only on the optional features that are currently *suggested* for this system, as determined by the `Suggest=` and `SuggestOn…=` settings in the feature definition files. This is supported for the `enable-feature` and `disable-feature` commands. Both commands operate on the same set of features, thus `disable-feature` undoes what `enable-feature` did. In order to reconcile the system according to suggestions, i.e., to also turn off the features that are not (or no longer) suggested, first disable all features with `--feature-all`, then enable the suggested ones with this switch. `--definitions=` A path to a directory. If specified, the transfer `*.conf` files are read from this directory instead of `/usr/lib/sysupdate.d/*.conf`, `/etc/sysupdate.d/*.conf`, and `/run/sysupdate.d/*.conf`. This option may not be combined with `--component=`. `--root=` Takes a path to a directory to use as root file system when searching for `sysupdate.d/*.conf` files. `--image=` Takes a path to a disk image file or device to mount and use in a similar fashion to `--root=`, see above. If this is used and partition resources are updated this is done inside the specified disk image. `--instances-max=`; `-m` Takes a decimal integer greater than or equal to 2 while updating or 1 while vacuuming. Controls how many versions to keep at any time. This option may also be configured inside the transfer files, via the `InstancesMax=` setting, see `sysupdate.d(5)` for details. `--sync=` Takes a boolean argument, defaults to yes. This may be used to specify whether the newly updated resource versions shall be synchronized to disk when appropriate (i.e. after the download is complete, before it is finalized, and again after finalization). This should not be turned off, except to improve runtime performance in testing environments. `--verify=` Takes a boolean argument, defaults to yes. Controls whether to cryptographically verify downloads. Do not turn this off, except in testing environments. `--reboot` When used in combination with the `update` commands and a new version is installed, automatically reboots the system immediately afterwards. This switch may not be combined with `--component=`, as it only applies to the booted OS version. `--cleanup=` Takes a boolean argument. When used in combination with the `update` command, automatically performs the equivalent of the `cleanup` command afterwards, removing any orphaned files that are no longer covered by the patterns of the currently defined transfer files. This is useful to garbage-collect files that used to be owned by a transfer file that has since been modified, disabled or removed. Defaults to off. `--loop=` Takes a positive integer. When used in combination with the `update` command, the update logic is run repeatedly, until either an iteration installs nothing, or the specified number of iterations has been reached. Each iteration re-reads all definition files (and re-enumerates components, if `--component-all` is used). This is useful if installing an update can make further updates available, for example because the update ships new or changed transfer files or components, or because a system extension it installs contains such files. Reaching the iteration limit while updates are still being installed is not considered a failure. If not specified, defaults to 1, i.e. a single iteration is run. If combined with `--reboot`, the reboot is requested only once, after the last iteration. May not be used with `acquire`. `systemd-sysupdate-update.service` runs with `--loop=16`. `--offline` Prevents fetching metadata from the network (i.e. `SHA256SUMS`). This is most useful when used in combination with the `list` command, to query locally installed versions. If used in combination with the `update` command, it allows updates to be downloaded in advance (using `acquire`) and installed later. `--transfer-source=` Takes a path as its argument. When specified, all transfer sources configured with `PathRelativeTo=explicit` will be interpreted relative to the specified path. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `sysupdate.d(5)`, `sysupdate.features(5)`, `sysupdate.components(5)`, `systemd-sysupdated.service(8)`, `systemd-repart(8)` # systemd-sysupdated.service systemd systemd-sysupdated.service 8 systemd-sysupdated.service systemd-sysupdated System Update Service `systemd-sysupdated.service` `/usr/lib/systemd/systemd-sysupdated` # Description `systemd-sysupdated` is a system service that allows unprivileged clients to update the system. It works by scanning the system for updateable "targets" (i.e. portable services, sysexts, sysupdate components, etc.) and exposing them on the bus. Each target then has methods that translate directly into invocations of `systemd-sysupdate(8)`. See `org.freedesktop.sysupdate1(5)` and `org.freedesktop.LogControl1(5)` for a description of the D-Bus API. # See Also `systemd(1)`, `systemd-sysupdate(8)`, `updatectl(1)`, `org.freedesktop.sysupdate1(5)` # systemd-sysusers systemd systemd-sysusers 8 systemd-sysusers systemd-sysusers.service Allocate system users and groups systemd-sysusers OPTIONS CONFIGFILE `systemd-sysusers.service` # Description `systemd-sysusers` creates system users and groups, based on files in the format described in `sysusers.d(5)`. If invoked with no arguments, directives from the configuration files found in the directories specified by `sysusers.d(5)` are executed. When invoked with positional arguments, if option `--replace=PATH` is specified, arguments specified on the command line are used instead of the configuration file \. Otherwise, just the configuration specified by the command line arguments is executed. If the string `-` is specified instead of a filename, the configuration is read from standard input. If the argument is a file name (without any slashes), all configuration directories are searched for a matching file and the file found that has the highest priority is executed. If the argument is a path, that file is used directly without searching the configuration directories for any other matching file. # Options The following options are understood: `--root=root` Takes a directory path as an argument. All paths will be prefixed with the given alternate \ path, including config search paths. Note that this is not a sandboxing or security feature. `sysusers.d(5)` definitions are potentially not processed in a hermetic fashion to the specified root. `--image=image` Takes a path to a disk image file or block device node. If specified all operations are applied to file system in the indicated disk image. This is similar to `--root=` but operates on file systems stored in disk images or block devices. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). For further information on supported disk images, see `systemd-nspawn(1)`'s switch of the same name. `--replace=PATH` When this option is given, one or more positional arguments must be specified. All configuration files found in the directories listed in `sysusers.d(5)` will be read, and the configuration given on the command line will be handled instead of and with the same priority as the configuration file \. This option is intended to be used when package installation scripts are running and files belonging to that package are not yet available on disk, so their contents must be given on the command line, but the admin configuration might already exist and should be given higher priority.
RPM installation script for radvd
echo 'u radvd - "radvd daemon"' | \ systemd-sysusers --replace=/usr/lib/sysusers.d/radvd.conf - This will create the radvd user as if `/usr/lib/sysusers.d/radvd.conf` was already on disk. An admin might override the configuration specified on the command line by placing `/etc/sysusers.d/radvd.conf` or even `/etc/sysusers.d/00-overrides.conf`. Note that this is the expanded form, and when used in a package, this would be written using a macro with "radvd" and a file containing the configuration line as arguments.
`-n`; `--dry-run` Process the configuration and figure out what entries would be created, but do not actually write anything. The short option `-n` was added in version 262. `--inline` Treat each positional argument as a separate configuration line instead of a file name. # Credentials `systemd-sysusers` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `passwd.hashed-password.user` A UNIX hashed password string to use for the specified user, when creating an entry for it. This is particularly useful for the `root` user as it allows provisioning the default root password to use via a unit file drop-in or from a container manager passing in this credential. Note that setting this credential has no effect if the specified user account already exists. This credential is hence primarily useful in first boot scenarios or systems that are fully stateless and come up with an empty `/etc/` on every boot. `passwd.plaintext-password.user` Similar to `passwd.hashed-password.user` but expect a literal, plaintext password, which is then automatically hashed before used for the user account. If both the hashed and the plaintext credential are specified for the same user the former takes precedence. It's generally recommended to specify the hashed version; however in test environments with weaker requirements on security it might be easier to pass passwords in plaintext instead. `passwd.shell.user` Specifies the shell binary to use for the specified account when creating it. `sysusers.extra` The contents of this credential may contain additional lines to operate on. The credential contents should follow the same format as any other `sysusers.d/` drop-in. If this credential is passed it is processed after all of the drop-in files read from the file system. Note that by default the `systemd-sysusers.service` unit file is set up to inherit the `passwd.hashed-password.root`, `passwd.plaintext-password.root`, `passwd.shell.root` and `sysusers.extra` credentials from the service manager. Thus, when invoking a container with an unpopulated `/etc/` for the first time it is possible to configure the root user's password to be `systemd` like this: # systemd-nspawn --image=… --set-credential=passwd.hashed-password.root:'$y$j9T$yAuRJu1o5HioZAGDYPU5d.$F64ni6J2y2nNQve90M/p0ZP0ECP/qqzipNyaY9fjGpC' … Note again that the data specified in this credential is consulted only when creating an account for the first time, it may not be used for changing the password or shell of an account that already exists. Use `mkpasswd(1)` for generating UNIX password hashes from the command line. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `sysusers.d(5)`, [Users, Groups, UIDs and GIDs on systemd systems](https://systemd.io/UIDS-GIDS), `systemd.exec(5)`, `mkpasswd(1)` # systemd-time-wait-sync.service systemd systemd-time-wait-sync.service 8 systemd-time-wait-sync.service systemd-time-wait-sync Wait until kernel time is synchronized `systemd-time-wait-sync.service` `/usr/lib/systemd/systemd-time-wait-sync` # Description `systemd-time-wait-sync` is a system service that delays the start of units that are ordered after `time-sync.target` (see `systemd.special(7)` for details) until the system time has been synchronized with an accurate remote reference time source by `systemd-timesyncd.service`. `systemd-timesyncd.service` notifies `systemd-time-wait-sync` about successful synchronization. `systemd-time-wait-sync` also tries to detect when the kernel marks the system clock as synchronized, but this detection is not reliable and is intended only as a fallback for compatibility with alternative NTP services that can be used to synchronize time (e.g., ntpd, chronyd). # Files `/run/systemd/timesync/synchronized` The presence of this file indicates to this service that the system clock has been synchronized. # See Also `systemd(1)`, `systemd.special(7)`, `systemd-timesyncd.service(8)` # systemd-timedated.service systemd systemd-timedated.service 8 systemd-timedated.service systemd-timedated Time and date bus mechanism `systemd-timedated.service` `/usr/lib/systemd/systemd-timedated` # Description `systemd-timedated.service` is a system service that may be used as a mechanism to change the system clock and timezone, as well as to enable/disable network time synchronization. `systemd-timedated` is automatically activated on request and terminates itself when it is unused. The tool `timedatectl(1)` is a command line client to this service. `systemd-timedated` currently offers access to the following four settings: - The system time - The system timezone - A boolean controlling whether the system RTC is in local or UTC timezone - Whether the time synchronization service is enabled/started or disabled/stopped, see next section. See `org.freedesktop.timedate1(5)` and `org.freedesktop.LogControl1(5)` for information about the D-Bus API. # List of network time synchronization services `systemd-timedated` will look for files with a `.list` extension in `ntp-units.d/` directories. Each file is parsed as a list of unit names, one per line. Empty lines and lines with comments (`#`) are ignored. Files are read from `/usr/lib/systemd/ntp-units.d/` and the corresponding directories under `/etc/`, `/run/`, `/usr/local/lib/`. Files in `/etc/` override files with the same name in `/run/`, `/usr/local/lib/`, and `/usr/lib/`. Files in `/run/` override files with the same name under `/usr/`. Packages should install their configuration files in `/usr/lib/` (distribution packages) or `/usr/local/lib/` (local installs).
`ntp-units.d/` entry for `systemd-timesyncd`
# /usr/lib/systemd/ntp-units.d/80-systemd-timesync.list systemd-timesyncd.service
If the environment variable `$SYSTEMD_TIMEDATED_NTP_SERVICES` is set, `systemd-timedated` will parse the contents of that variable as a colon-separated list of unit names. When set, this variable overrides the file-based list described above.
An override that specifies that `chronyd` should be used if available
SYSTEMD_TIMEDATED_NTP_SERVICES=chronyd.service:systemd-timesyncd.service
# See Also `systemd(1)`, `timedatectl(1)`, `localtime(5)`, `hwclock(8)`, `systemd-timesyncd(8)`, `org.freedesktop.timedate1(5)` # systemd-timesyncd.service systemd systemd-timesyncd.service 8 systemd-timesyncd.service systemd-timesyncd Network Time Synchronization `systemd-timesyncd.service` `/usr/lib/systemd/systemd-timesyncd` # Description `systemd-timesyncd.service` is a system service that may be used to synchronize the local system clock with a remote Network Time Protocol (NTP) server. It also saves the local time to disk every time the clock has been synchronized and uses this to possibly advance the system realtime clock on subsequent reboots to ensure it (roughly) monotonically advances even if the system lacks a battery-buffered RTC chip. The `systemd-timesyncd.service` service implements SNTP only. This minimalistic service will step the system clock for large offsets or slowly adjust it for smaller deltas. Complex use cases that require full NTP support (and where SNTP is not sufficient) are not covered by `systemd-timesyncd.service`. The NTP servers contacted are determined from the global settings in `timesyncd.conf(5)`, the per-link static settings in `.network` files, and the per-link dynamic settings received over DHCP. See `systemd.network(5)` for further details. `timedatectl(1)`'s `set-ntp` command may be used to enable and start, or disable and stop this service. `timedatectl(1)`'s `timesync-status` or `show-timesync` command can be used to show the current status of this service. Initialization of `systemd-timesyncd.service` delays the start of units that are ordered after `time-set.target` (see `systemd.special(7)` for details) until the local time has been updated from `/var/lib/systemd/timesync/clock` (see below) in order to make it roughly monotonic. It does not delay other units until synchronization with an accurate reference time sources has been reached. Use `systemd-time-wait-sync.service(8)` to achieve that, which will delay start of units that are ordered after `time-sync.target` until synchronization to an accurate reference clock is reached. `systemd` and `systemd-timesyncd` advance the system clock to the "epoch" (the lowest date above which the system clock time is assumed to be set correctly). See "System clock epoch" section in `systemd(1)` for details. `systemd` will set the clock when initializing, but `/var/lib/systemd/timesync/clock` might not yet be available at that point. `systemd-timesyncd` will advance the clock when it is started and notices that the system clock is before the modification time of `/var/lib/systemd/timesync/clock`. # Files `/var/lib/systemd/timesync/clock` The modification time ("mtime") of this file is updated on each successful NTP synchronization or after each `SaveIntervalSec=` time interval, as specified in `timesyncd.conf(5)`. If present, the modification time of this file is used for the epoch by `systemd(1)` and `systemd-timesyncd.service`. `/run/systemd/timesync/synchronized` A file that is touched on each successful synchronization to assist `systemd-time-wait-sync.service(8)` service and other applications in detecting synchronization to an accurate reference clock. # See Also `systemd(1)`, `timesyncd.conf(5)`, `systemd.network(5)`, `systemd-networkd.service(8)`, `systemd-time-wait-sync.service(8)`, `systemd.special(7)`, `timedatectl(1)`, `localtime(5)`, `hwclock(8)` # systemd-tmpfiles systemd systemd-tmpfiles 8 systemd-tmpfiles systemd-tmpfiles-setup.service systemd-tmpfiles-setup-dev-early.service systemd-tmpfiles-setup-dev.service systemd-tmpfiles-clean.service systemd-tmpfiles-clean.timer Create, delete, and clean up files and directories systemd-tmpfiles OPTIONS CONFIGFILE System units: `systemd-tmpfiles-setup.service`, `systemd-tmpfiles-setup-dev-early.service`, `systemd-tmpfiles-setup-dev.service`, `systemd-tmpfiles-clean.service`, `systemd-tmpfiles-clean.timer` User units: `systemd-tmpfiles-setup.service`, `systemd-tmpfiles-clean.service`, `systemd-tmpfiles-clean.timer` # Description `systemd-tmpfiles` creates, deletes, and cleans up files and directories, using the configuration file format and location specified in `tmpfiles.d(5)`. Historically, it was designed to manage volatile and temporary files, as the name suggests, but it provides generic file management functionality and can be used to manage any kind of files. It must be invoked with one or more commands `--create`, `--remove`, and `--clean`, to select the respective subset of operations. If invoked with no arguments, directives from the configuration files found in the directories specified by `tmpfiles.d(5)` are executed. When invoked with positional arguments, if option `--replace=PATH` is specified, arguments specified on the command line are used instead of the configuration file \. Otherwise, just the configuration specified by the command line arguments is executed. If the string `-` is specified instead of a filename, the configuration is read from standard input. If the argument is a file name (without any slashes), all configuration directories are searched for a matching file and the file found that has the highest priority is executed. If the argument is a path, that file is used directly without searching the configuration directories for any other matching file. System services (`systemd-tmpfiles-setup.service`, `systemd-tmpfiles-setup-dev-early.service`, `systemd-tmpfiles-setup-dev.service`, `systemd-tmpfiles-clean.service`) invoke `systemd-tmpfiles` to create system files and to perform system wide cleanup. Those services read administrator-controlled configuration files in `tmpfiles.d/` directories. User services (`systemd-tmpfiles-setup.service`, `systemd-tmpfiles-clean.service`) also invoke `systemd-tmpfiles`, but it reads a separate set of files, which includes user-controlled files under `~/.config/user-tmpfiles.d/` and `~/.local/share/user-tmpfiles.d/`, and administrator-controlled files under `/usr/share/user-tmpfiles.d/`. Users may use this to create and clean up files under their control, but the system instance performs global cleanup and is not influenced by user configuration. Note that this means a time-based cleanup configured in the system instance, such as the one typically configured for `/tmp/`, will thus also affect files created by the user instance if they are placed in `/tmp/`, even if the user instance's time-based cleanup is turned off. To re-apply settings after configuration has been modified, simply restart `systemd-tmpfiles-clean.service`, which will apply any settings which can be safely executed at runtime. To debug `systemd-tmpfiles`, it may be useful to invoke it directly from the command line with increased log level (see `$SYSTEMD_LOG_LEVEL` below). # Commands and options The following commands are understood: `--create` If this command is passed, all files and directories marked with `f`, `F`, `w`, `d`, `D`, `v`, `p`, `L`, `c`, `b`, `m` in the configuration files are created or written to. Files and directories marked with `z`, `Z`, `t`, `T`, `a`, and `A` have their ownership, access mode and security labels set. `--clean` If this command is passed, all files and directories with an age parameter configured will be cleaned up. `--remove` If this command is passed, the contents of directories marked with `D` or `R`, and files or directories themselves marked with `r` or `R` are removed unless an exclusive or shared BSD lock is taken on them (see `flock(2)`). `--purge` If this option is passed, all files and directories declared for *creation* and marked with the `$` character by the `tmpfiles.d/` files specified on the command line will be *deleted*. Specifically, this acts on all files and directories marked with `f`, `F`, `d`, `D`, `v`, `q`, `Q`, `p`, `L`, `c`, `b`, `C`, `w`, `e`. If this switch is used at least one `tmpfiles.d/` file (or `-` for standard input) must be specified on the command line or the invocation will be refused, for safety reasons (as otherwise much of the installed system files might be removed). The primary usecase for this option is to automatically remove files and directories that originally have been created on behalf of an installed package at package removal time. It is recommended to first run this command in combination with `--dry-run` (see below) to verify which files and directories will be deleted. *Warning!* This is usually not the command you want! In most cases `--remove` is what you are looking for. `--user` Execute "user" configuration, i.e. `tmpfiles.d/` files in user configuration directories. `--boot` Also execute lines with an exclamation mark. Lines that are not safe to be executed on a running system may be marked in this way. `systemd-tmpfiles` is executed in early boot with `--boot` specified and will execute those lines. When invoked again later, it should be called without `--boot`. `--graceful` Ignore configuration lines pertaining to unknown users or groups. This option is intended to be used in early boot before all users or groups have been created. `-n`; `--dry-run` Process the configuration and print what operations would be performed, but do not actually change anything in the file system. The short option `-n` was added in version 262. `--inline` Treat each positional argument as a separate configuration line instead of a file name. `--prefix=path` Only apply rules with paths that start with the specified prefix. This option can be specified multiple times. `--exclude-prefix=path` Ignore rules with paths that start with the specified prefix. This option can be specified multiple times. `-E` A shortcut for `--exclude-prefix=/dev --exclude-prefix=/proc --exclude-prefix=/run --exclude-prefix=/sys`, i.e. exclude the hierarchies typically backed by virtual or memory file systems. This is useful in combination with `--root=`, if the specified directory tree contains an OS tree without these virtual/memory file systems mounted in, as it is typically not desirable to create any files and directories below these subdirectories if they are supposed to be overmounted during runtime. `--root=root` Takes a directory path as an argument. All paths will be prefixed with the given alternate \ path, including config search paths. When this option is used, the libc Name Service Switch (NSS) is bypassed for resolving users and groups. Instead the files `/etc/passwd` and `/etc/group` inside the alternate root are read directly. This means that users/groups not listed in these files will not be resolved, i.e. LDAP NIS and other complex databases are not considered. Consider combining this with `-E` to ensure the invocation does not create files or directories below mount points in the OS image operated on that are typically overmounted during runtime. Note that this is not a sandboxing or security feature. `tmpfiles.d(5)` definitions are potentially not processed in a hermetic fashion to the specified root. `--image=image` Takes a path to a disk image file or block device node. If specified all operations are applied to file system in the indicated disk image. This is similar to `--root=` but operates on file systems stored in disk images or block devices. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). For further information on supported disk images, see `systemd-nspawn(1)`'s switch of the same name. Implies `-E`. `--replace=PATH` When this option is given, one or more positional arguments must be specified. All configuration files found in the directories listed in `tmpfiles.d(5)` will be read, and the configuration given on the command line will be handled instead of and with the same priority as the configuration file \. This option is intended to be used when package installation scripts are running and files belonging to that package are not yet available on disk, so their contents must be given on the command line, but the admin configuration might already exist and should be given higher priority. It is possible to combine `--create`, `--clean`, and `--remove` in one invocation (in which case removal and cleanup are executed before creation of new files). For example, during boot the following command line is executed to ensure that all temporary and volatile directories are removed and created according to the configuration file: systemd-tmpfiles --remove --create # Credentials `systemd-tmpfiles` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `tmpfiles.extra` The contents of this credential may contain additional lines to operate on. The credential contents should follow the same format as any other `tmpfiles.d/` drop-in configuration file. If this credential is passed it is processed after all of the drop-in files read from the file system. The lines in the credential can hence augment existing lines of the OS, but not override them. Note that by default the `systemd-tmpfiles-setup.service` unit file (and related unit files) is set up to inherit the `tmpfiles.extra` credential from the service manager. # Environment # Unprivileged --cleanup operation `systemd-tmpfiles` tries to avoid changing the access and modification times on the directories it accesses, which requires `CAP_FOWNER` privileges. When running as non-root, directories which are checked for files to clean up will have their access time bumped, which might prevent their cleanup. # Exit status On success, 0 is returned. If the configuration was syntactically invalid (syntax errors, missing arguments, …), so some lines had to be ignored, but no other errors occurred, `65` is returned (`EX_DATAERR` from `/usr/include/sysexits.h`). If the configuration was syntactically valid, but could not be executed (lack of permissions, creation of files in missing directories, invalid contents when writing to `/sys/` values, …), `73` is returned (`EX_CANTCREAT` from `/usr/include/sysexits.h`). Otherwise, `1` is returned (`EXIT_FAILURE` from `/usr/include/stdlib.h`). Note: when creating items, if the target already exists, but is of the wrong type or otherwise does not match the requested state, and forced operation has not been requested with `+`, a message is emitted, but the failure is otherwise ignored. # See Also `systemd(1)`, `tmpfiles.d(5)` # systemd-tpm2-clear.service systemd systemd-tpm2-clear.service 8 systemd-tpm2-clear.service Request that the TPM security chip is cleared on next boot `systemd-tpm2-clear.service` `/usr/lib/systemd/systemd-tpm2-clear` # Description `systemd-tpm2-clear.service` is a service that requests that the TPM is reset by the PC firmware on the next boot. It makes use of the TPM Physical Presence Interface (PPI). Note that this service does not immediately execute the clear operation, but simply asks the PC firmware to execute it at next boot, where the user will be asked for confirmation before the operation is done. `systemd-tpm2-clear.service` is typically hooked into the `factory-reset.target` unit in order to request the TPM request before an immediate reboot. See [Factory Reset](https://systemd.io/FACTORY_RESET) for more information. # Options The following options are understood: `--graceful` Exit cleanly and execute no operation if the system does not possess a TPM chip. # Kernel Command Line `systemd-tpm2-clear` understands the following kernel command line parameters: `systemd.tpm2_allow_clear=` Takes a boolean argument. If false the service will succeed, but instead of requesting the TPM clear operation from the PC firmware it will not execute any operation. If not specified defaults to true. # See Also `systemd(1)`, `systemd-tpm2-setup.service(8)`, `systemd-factory-reset-request.service(8)` # systemd-tpm2-generator systemd systemd-tpm2-generator 8 systemd-tpm2-generator Generator for inserting TPM2 synchronization point in the boot process `/usr/lib/systemd/system-generators/systemd-tpm2-generator` # Description `systemd-tpm2-generator` is a generator that adds a `Wants=` dependency from `sysinit.target` to `tpm2.target` when it detects that the firmware discovered a TPM2 device but the OS kernel so far did not. `tpm2.target` is supposed to act as synchronization point for all services that require TPM2 device access. See `systemd.special(7)` for details. The `systemd.tpm2_wait=` kernel command line option may be used to override behaviour of the generator. It accepts a boolean value: if true then `tpm2.target` will be added as synchronization point even if the firmware has not detected a TPM2 device. If false, the target will not be inserted even if firmware reported a device but the OS kernel does not expose a device for it yet. The latter might be useful in environments where a suitable TPM2 driver for the available hardware is not available. The `systemd.tpm2_software_fallback=` kernel command line option (which takes a boolean argument, defaulting to false) may be used to enable an automatic software TPM fallback in case a hardware TPM is not detected and `swtpm(8)` is available. This pulls in the `systemd-tpm2-swtpm.service(8)` service. In the initrd, the generator also orders `systemd-sysext-initrd.service(8)` and `systemd-confext-initrd.service(8)` after `tpm2.target` and `systemd-pcrphase-initrd.service(8)`, so that LUKS encrypted extension images sealed to the TPM2 can be unlocked. This is not done if the software TPM fallback is in use, as the software TPM only becomes available after the extension images are merged, hence such images cannot be unlocked in the initrd in that case. `systemd-tpm2-generator` implements `systemd.generator(7)`. # See Also `systemd(1)`, `systemd.special(7)`, `kernel-command-line(7)`, `systemd-tpm2-swtpm.service(8)` # systemd-tpm2-setup.service systemd systemd-tpm2-setup.service 8 systemd-tpm2-setup.service systemd-tpm2-setup-early.service systemd-tpm2-setup Set up the TPM2 Storage Root Key (SRK), Endorsement Key (EK), and initialize NvPCRs at boot `systemd-tpm2-setup.service` `/usr/lib/systemd/systemd-tpm2-setup` # Description `systemd-tpm2-setup.service` and `systemd-tpm2-setup-early.service` are services that generate the Storage Root Key (SRK) and Endorsement Key (EK) if they have not been generated yet, and stores them in the TPM. If NvPCRs (additional PCR registers in TPM NV Indexes) are defined, these are initialized. NvPCRs can only be initialized from the initrd. Their initial write is authorized by the signed PCR policy with the `initrd` policy reference embedded in the booted UKI, or, if there is none, by a PCR policy bound to the current value of PCR 11. The services will store the public key of the SRK key pair in a PEM file in `/run/systemd/tpm2-srk-public-key.pem` and `/var/lib/systemd/tpm2-srk-public-key.pem`. They will also store it in TPM2B_PUBLIC format in `/run/systemd/tpm2-srk-public-key.tpm2_public` and `/var/lib/systemd/tpm2-srk-public-key.tpm2b_public`. `systemd-tpm2-setup-early.service` runs very early at boot (possibly in the initrd), and writes the SRK public key to `/run/systemd/tpm2-srk-public-key.*` (as `/var/` is generally not accessible this early yet), while `systemd-tpm2-setup.service` runs during a later boot phase and saves the public key to `/var/lib/systemd/tpm2-srk-public-key.*`. # Files `/run/systemd/tpm2-srk-public-key.pem`; `/run/systemd/tpm2-srk-public-key.tpm2b_public` The SRK public key in PEM and TPM2B_PUBLIC format, written during early boot. `/var/lib/systemd/tpm2-srk-public-key.pem`; `/var/lib/systemd/tpm2-srk-public-key.tpm2_public` The SRK public key in PEM and TPM2B_PUBLIC format, written during later boot (once `/var/` is available). `/usr/lib/nvpcr/*.nvpcr` Definition files for NvPCRs. # See Also `systemd(1)` # systemd-tpm2-swtpm.service systemd systemd-tpm2-swtpm.service 8 systemd-tpm2-swtpm.service systemd-tpm2-swtpm Provide a fallback software TPM `systemd-tpm2-swtpm.service` `/usr/lib/systemd/systemd-tpm2-swtpm` # Description The `systemd-tpm2-swtpm.service` provides fallback software TPM functionality, intended for use in environments where a discrete or firmware TPM ("hardware TPM") is not available. It is pulled into the boot process by `systemd-tpm2-generator(8)` if a hardware TPM is not available, and the system is configured to provide a software TPM in that case. Note that a software TPM provides only very weak security properties compared to a hardware TPM, and hence should only be used as a fallback mechanism if a hardware TPM is not available but TPM semantics are desired. This service ultimately wraps `swtpm(8)`. If the boot secret `/.extra/boot-secret` (in the initrd) or `/run/systemd/stub/boot-secret` (on the host) is available the software TPM NVRAM storage is encrypted with this key. See `systemd-stub(7)` for details. The TPM NVRAM storage is placed on the EFI System Partition as it needs to be accessible during very early boot-up, in particular before the root file system is decrypted and mounted. # See Also `systemd(1)`, `systemd-tpm2-generator(8)`, `swtpm(8)`, `systemd-stub(7)` # systemd-tty-ask-password-agent systemd systemd-tty-ask-password-agent 1 systemd-tty-ask-password-agent List or process pending systemd password requests systemd-tty-ask-password-agent OPTIONS VARIABLE=VALUE # Description `systemd-tty-ask-password-agent` is a password agent that handles password requests of the system, for example for hard disk encryption passwords or SSL certificate passwords that need to be queried at boot-time or during runtime. `systemd-tty-ask-password-agent` implements the [Password Agents Specification](https://systemd.io/PASSWORD_AGENTS/), and is one of many possible response agents which answer to queries formulated with `systemd-ask-password(1)`. # Options The following options are understood: `--list` Lists all currently pending system password requests. `--query` Process all currently pending system password requests by querying the user on the calling TTY. `--watch` Continuously process password requests. `--wall` Forward password requests to `wall(1)` instead of querying the user on the calling TTY. `--plymouth` Ask question with `plymouth(8)` instead of querying the user on the calling TTY. `--console`\[=\\] Ask question on TTY \ instead of querying the user on the calling TTY. If \ is not specified, `/dev/console` will be used. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemctl(1)`, `systemd-ask-password-console.service(8)`, `wall(1)`, `plymouth(8)` # systemd-udev-settle.service systemd systemd-udev-settle.service 8 systemd-udev-settle.service Wait for all pending udev events to be handled `systemd-udev-settle.service` # Description This service calls `udevadm settle` to wait until all events that have been queued by `udev(7)` have been processed. It is a crude way to wait until "all" hardware has been discovered. Services may pull in this service and order themselves after it to wait for the udev queue to be empty. *Using this service is not recommended.* There can be no guarantee that hardware is fully discovered at any specific time, because the kernel does hardware detection asynchronously, and certain buses and devices take a very long time to become ready, and also additional hardware may be plugged in at any time. Instead, services should subscribe to udev events and react to any new hardware as it is discovered. Services that, based on configuration, expect certain devices to appear, may warn or report failure after a timeout. This timeout should be tailored to the hardware type. Waiting for `systemd-udev-settle.service` usually slows boot significantly, because it means waiting for all unrelated events too. # See Also `udev(7)`, `udevadm(8)` # systemd-udevd.service systemd systemd-udevd.service 8 systemd-udevd.service systemd-udevd-kernel.socket systemd-udevd-varlink.socket systemd-udevd Device event managing daemon `systemd-udevd.service` `systemd-udevd-kernel.socket` `systemd-udevd-varlink.socket` /usr/lib/systemd/systemd-udevd --daemon --debug --children-max= --exec-delay= --event-timeout= --resolve-names=early\|late\|never --version --help # Description `systemd-udevd` listens to kernel uevents. For every event, systemd-udevd executes matching instructions specified in udev rules. See `udev(7)`. The behavior of the daemon can be configured using `udev.conf(5)`, its command line options, environment variables, and on the kernel command line, or changed dynamically with `udevadm control`. # Options `-d`; `--daemon` Detach and run in the background. `-D`; `--debug` Print debug messages to standard error. `-c`; `--children-max=` Limit the number of events executed in parallel. `-e`; `--exec-delay=` Delay the execution of each `RUN{program}` parameter by the given number of seconds. This option might be useful when debugging system crashes during coldplug caused by loading non-working kernel modules. `-t`; `--event-timeout=` Set the number of seconds to wait for events to finish. After this time, the event will be terminated. The default is 180 seconds. `-s`; `--timeout-signal=` Set the signal which `systemd-udevd` will send to forked off processes after reaching event timeout. The setting can be overridden at boot time with the kernel command line option `udev.timeout_signal=`. Setting to `SIGABRT` may be helpful in order to debug worker timeouts. Defaults to `SIGKILL`. Note that setting the option on the command line overrides the setting from the configuration file. `-N`; `--resolve-names=` Specify when systemd-udevd should resolve names of users and groups. When set to `early` (the default), names will be resolved when the rules are parsed. When set to `late`, names will be resolved for every event. When set to `never`, names will never be resolved and all devices will be owned by root. # Kernel command line `udev.log_level=`; `rd.udev.log_level=` Set the log level. `udev.trace[=BOOL]`; `rd.udev.trace[=BOOL]` Enable/disable trace logging. When enabled, `udev.log_level=` will be ignored, and `debug` level is assumed. `udev.children_max=`; `rd.udev.children_max=` Limit the number of events executed in parallel. `udev.exec_delay=`; `rd.udev.exec_delay=` Delay the execution of each `RUN{program}` parameter by the given number of seconds. This option might be useful when debugging system crashes during coldplug caused by loading non-working kernel modules. `udev.event_timeout=`; `rd.udev.event_timeout=` Wait for events to finish up to the given number of seconds. This option might be useful if events are terminated due to kernel drivers taking too long to initialize. `udev.timeout_signal=`; `rd.udev.timeout_signal=` Specifies a signal that `systemd-udevd` will send to workers on timeout. Note that kernel command line option overrides both the setting in the configuration file and the one on the program command line. `udev.blockdev_read_only`; `rd.udev.blockdev_read_only` If specified, mark all physical block devices read-only as they appear. Synthetic block devices (such as loopback block devices or device mapper devices) are left as they are. This is useful to guarantee that the contents of physical block devices remains unmodified during runtime, for example to implement fully stateless systems, for testing or for recovery situations where corrupted file systems shall not be corrupted further through accidental modification. A block device may be marked writable again by issuing the `blockdev --setrw` command, see `blockdev(8)` for details. `net.ifnames=` Network interfaces are renamed to give them predictable names when possible. It is enabled by default; specifying 0 disables it. `net.naming_scheme=` Network interfaces are renamed to give them predictable names when possible (unless `net.ifnames=0` is specified, see above). With this kernel command line option it is possible to pick a specific version of this algorithm and override the default chosen at compilation time. Expects one of the naming scheme identifiers listed in `systemd.net-naming-scheme(7)`, or `latest` to select the latest scheme known (to this particular version of `systemd-udevd.service`). Note that selecting a specific scheme is not sufficient to fully stabilize interface naming: the naming is generally derived from driver attributes exposed by the kernel. As the kernel is updated, previously missing attributes `systemd-udevd.service` is checking might appear, which affects older name derivation algorithms, too. `net.ifname_policy=policy1[,policy2,…][,MAC]` Specifies naming policies applied when renaming network interfaces. Takes a list of policies and an optional MAC address separated with comma. Each policy value must be one of the policies understood by the `NamePolicy=` setting in .link files, e.g. `onboard` or `path`. See `systemd.link(5)` for more details. When the MAC address is specified, the policies are applied to the interface which has the address. When no MAC address is specified, the policies are applied to all interfaces. This kernel command line argument can be specified multiple times. This argument is not directly read by `systemd-udevd`, but is instead converted to a .link file by `systemd-network-generator.service(8)`. For this argument to take effect, `systemd-network-generator.service` must be enabled. Example: net.ifname_policy=keep,kernel,path,slot,onboard,01:23:45:67:89:ab net.ifname_policy=keep,kernel,path,slot,onboard,mac This is mostly equivalent to creating the following .link files: # 91-name-policy-with-mac.link [Match] MACAddress=01:23:45:67:89:ab [Link] NamePolicy=keep kernel path slot onboard AlternativeNamePolicy=path slot onboard and # 92-name-policy-for-all.link [Match] OriginalName=* [Link] NamePolicy=keep kernel path slot onboard mac AlternativeNamePolicy=path slot onboard mac # See Also `udev.conf(5)`, `udev(7)`, `udevadm(8)` # systemd-update-done.service systemd systemd-update-done.service 8 systemd-update-done.service systemd-update-done Mark /etc/ and /var/ as fully updated `systemd-update-done.service` `/usr/lib/systemd/systemd-update-done` # Description `systemd-update-done.service` is a service that is invoked as part of the first boot after the vendor operating system resources in `/usr/` have been updated. This is useful to implement offline updates of `/usr/` which might require updates to `/etc/` or `/var/` on the following boot. `systemd-update-done.service` updates the file modification time (mtime) stored in and "on" the files `/etc/.updated` and `/var/.updated` to the modification time of the `/usr/` directory, unless the stamp files are already newer. (The timestamp is stored as the mtime field on the file, but also *in* the file to support filesystems that do not store full timestamp precision.) Services that shall run after offline upgrades of `/usr/` should order themselves before `systemd-update-done.service`, and use the `ConditionNeedsUpdate=` (see `systemd.unit(5)`) condition to make sure to run when `/etc/` or `/var/` are older than `/usr/` according to the modification times of the files described above. This requires that updates to `/usr/` are always followed by an update of the modification time of `/usr/`, for example by invoking `touch(1)` on it. Note that if the `systemd.condition_needs_update=` kernel command line option is used it overrides the `ConditionNeedsUpdate=` unit condition checks. In that case `systemd-update-done.service` will not reset the condition state until a follow-up reboot where the kernel switch is not specified anymore. # Options The following options are understood: `--root=root` Takes a directory path as an argument. The program will operate on paths below the specified root directory. # See Also `systemd(1)`, `systemd.unit(5)`, `touch(1)` # systemd-update-helper systemd systemd-update-helper 8 systemd-update-helper Enable, disable, stop, and restart units when packages are installed, upgraded, or removed /usr/lib/systemd/systemd-update-helper OPTIONS COMMAND UNIT # Description Package managers call `systemd-update-helper` from the scriptlets of packages that contain unit files. The systemd RPM macros and file triggers call it. It has to run as root. By default, the commands operate on the system service manager and the system unit directories. With `--global`, they operate on the global user unit configuration and on every running user service manager, i.e. every active `user@UID.service` unit. A user service manager that fails or does not finish the operation within 15 seconds is skipped and does not affect the others. The timeout is set at build time with the `-Dupdate-helper-user-timeout-sec=` option. If the system was not booted with systemd, or the helper runs in a `chroot(2)` environment, the commands only change unit files and skip all operations on service managers. Set `$SYSTEMD_OFFLINE=` to override this detection, see [Known Environment Variables](https://systemd.io/ENVIRONMENT). A \ argument is either a unit name or the absolute path of a unit file directly in `/usr/lib/systemd/system/` or `/etc/systemd/system/`, or in `/usr/lib/systemd/user/` or `/etc/systemd/user/` with `--global`. The path does not have to exist. Template units passed to `remove-units`, `mark-restart-units`, and `mark-reload-units` apply to all active instances of the template. # Commands `install-units` \… Enables or disables the units according to the preset policy, like `systemctl preset` does. With `--global`, applies the user preset policy to the global user unit configuration, like `systemctl --global preset` does. `remove-units` \… Disables the units and stops them. With `--global`, each running user service manager also disables the units in the configuration of its user, where `systemctl --user enable` creates its symlinks. `mark-restart-units` \…; `mark-reload-units` \… Marks the units to be restarted or reloaded by the next `enqueue-marked`. See `enqueue-marked` in `systemctl(1)`. `daemon-reload` Reloads the configuration of the service manager. With `--global`, reloads every running user service manager. `enqueue-marked` Restarts or reloads the units that are marked for it, and waits for the jobs to finish. `daemon-reload-enqueue-marked` Runs `daemon-reload`, then `enqueue-marked`. # Options `--system` Operates on the system service manager and the system unit directories. This is the default. `--global` Operates on the global user unit configuration and on every running user service manager. `--stdin` Reads the units from standard input, one unit name or unit file path per line, instead of from the arguments. Lines that do not name a unit, or name a path outside of the unit directories, are ignored. The RPM file triggers pass the unit files of removed packages this way. `--dry-run` Logs the changes and operations without performing them. `-q`; `--quiet` Only logs errors. # Exit status On success, 0 is returned, a non-zero failure code otherwise. A failure to preset a unit with `install-units` makes the command fail. Failures to disable, stop, mark, restart, or reload individual units, and failures of individual user service managers, are logged and do not change the exit status. # Examples
Disable and stop the units of a removed package
# printf '%s\n' /usr/lib/systemd/system/sshd.service /usr/lib/systemd/system/sshd@.service | \ /usr/lib/systemd/systemd-update-helper --stdin remove-units This disables `sshd.service` and `sshd@.service`, and stops `sshd.service` and all active instances of `sshd@.service`.
# See Also `systemd(1)`, `systemctl(1)`, `systemd.preset(5)`, `daemon(7)` # systemd-update-utmp.service systemd systemd-update-utmp.service 8 systemd-update-utmp.service systemd-update-utmp Write audit and utmp updates at bootup and shutdown `systemd-update-utmp.service` `/usr/lib/systemd/systemd-update-utmp` # Description `systemd-update-utmp.service` is a service that writes system reboots and shutdown requests to utmp and wtmp, as well as the audit logs. # See Also `systemd(1)`, `utmp(5)`, `auditd(8)` # systemd-user-sessions.service systemd systemd-user-sessions.service 8 systemd-user-sessions.service systemd-user-sessions Permit user logins after boot, prohibit user logins at shutdown `systemd-user-sessions.service` `/usr/lib/systemd/systemd-user-sessions` # Description `systemd-user-sessions.service` is a service that controls user logins through `pam_nologin(8)`. After basic system initialization is complete, it removes `/run/nologin`, thus permitting logins. Before system shutdown, it creates `/run/nologin`, thus prohibiting further logins. # See Also `systemd(1)`, `systemd-logind.service(8)`, `pam_nologin(8)` # systemd-userdbd.service systemd systemd-userdbd.service 8 systemd-userdbd.service systemd-userdbd JSON User/Group Record Query Multiplexer/NSS Compatibility `systemd-userdbd.service` `/usr/lib/systemd/systemd-userdbd` # Description `systemd-userdbd` is a system service that multiplexes user/group lookups to all local services that provide JSON user/group record definitions to the system. In addition it synthesizes JSON user/group records from classic UNIX/glibc NSS user/group records in order to provide full backwards compatibility. It may also pick up statically defined JSON user/group records from files in `/etc/userdb/`, `/run/userdb/`, `/run/host/userdb/` and `/usr/lib/userdb/` with the `.user` or `.group` extension. For more details about the extensions read the `nss-systemd(8)` manpage. Most of `systemd-userdbd`'s functionality is accessible through the `userdbctl(1)` command. The user and group records this service provides access to follow the [JSON User Records](https://systemd.io/USER_RECORD) and [JSON Group Record](https://systemd.io/GROUP_RECORD) definitions. This service implements the [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API), and multiplexes access other services implementing this API, too. It is thus both server and client of this API. This service provides three distinct [Varlink](https://varlink.org/) services: `io.systemd.Multiplexer` provides a single, unified API for querying JSON user and group records. Internally it talks to all other user/group record services running on the system in parallel and forwards any information discovered. This simplifies clients substantially since they need to talk to a single service only instead of all of them in parallel. `io.systemd.NameServiceSwitch` provides compatibility with classic UNIX/glibc NSS user records, i.e. converts `struct passwd` and `struct group` records as acquired with APIs such as `getpwnam(1)` to JSON user/group records, thus hiding the differences between the services as much as possible. `io.systemd.DropIn` makes JSON user/group records from the aforementioned drop-in directories available. # See Also `systemd(1)`, `nss-systemd(8)`, `userdbctl(1)`, `systemd-homed.service(8)` # systemd-validatefs@.service systemd systemd-validatefs@.service 8 systemd-validatefs@.service Validate File System Mount Constraint Data `systemd-validatefs@.service` `/usr/lib/systemd/systemd-validatefs` \ # Description `systemd-validatefs@.service` is a system service template that can be instantiated for newly established mount points. It reads file system mount constraint data from the file system, and ensures the mount runtime setup matches it. If it doesn't the service fails, which effects an immediate reboot. This functionality is supposed to ensure that trusted file systems cannot be used in a different context then what they were intended for. More specifically: in an `systemd-gpt-auto-generator(8)` based environment the file systems to mount are largely auto-discovered based on (unprotected) GPT partition table data. The mount constraint information can be used to validate the GPT partition data, based on the (protected) file system contents. Specifically, the mount constraints are encoded in the following extended attributes on the root inode of the file systems: 1. `user.validatefs.mount_point`: this extended attribute shall contain one or more absolute, normalized paths, separated by NUL bytes. If set and the specified file system is mounted to a location not matching any of the listed paths the validation check will fail. 2. `user.validatefs.gpt_label`: this extended attribute may contain one or more free-form strings, separated by NUL bytes. If set, all backing partitions of the file system are checked against this list, and if any backing partition's label is not listed, the validation will fail. Note that there may be multiple backing partition in case of Verity setups, which combines a data and a hash partition. 3. `user.validatefs.gpt_type_uuid`: this extended attribute may contain one or more GPT partition type UUIDs, formatted as string, separated by NUL bytes. As above, all backing partitions of the file system are checked against this list, and if none is matching the validation will fail. The `systemd-validatefs@.service` unit is automatically pulled into the initial transaction by `systemd-gpt-auto-generator(8)` for all file systems it discovers and generates mounts for. `systemd-fstab-generator(8)` will do this for all mounts with the `x-systemd.validatefs` mount option in `/etc/fstab`. The `systemd-repart(8)` tool generates these extended attributes automatically for the file systems it puts together, which may be controlled with the `AddValidateFS=` configuration option. The same constraints are also enforced whenever partitions of a disk image are mounted via the generic image dissection logic, i.e. by `systemd-dissect(1)`, `systemd-nspawn(1)`, `systemd-sysext(8)`, `systemd-portabled.service(8)`, `systemd-mountfsd.service(8)` or the `RootImage=` setting in unit files. In this case the mount point is checked relative to the image's root directory. Any constraint that is set must be fulfilled in full: if `user.validatefs.gpt_label` or `user.validatefs.gpt_type_uuid` are set, but the file system is not placed on a GPT partition (for example because the image is a bare file system image, or uses an MBR partition table) the mount is refused. This validation may be turned off by setting the `$SYSTEMD_DISSECT_VALIDATEFS` environment variable to `0`. # Options The `/usr/lib/systemd/systemd-validatefs` executable may also be invoked from the command line, where it expects a path to a mount and the following options: `--root=` Takes an absolute path or the special string `auto`. The specified path is removed as prefix from the specified mount point argument before the validation. If set to `auto` defaults to unspecified on the host and `/sysroot/` when run in initrd context, in order to validate the mount constraint data relative to the future file system root. # See Also `systemd(1)`, `systemd-gpt-auto-generator(8)`, `systemd-fstab-generator(8)`, `systemd-repart(8)`, `systemd-dissect(1)` # systemd-vconsole-setup.service systemd systemd-vconsole-setup.service 8 systemd-vconsole-setup.service systemd-vconsole-setup Configure the virtual consoles `systemd-vconsole-setup.service` /usr/lib/systemd/systemd-vconsole-setup TTY # Description `systemd-vconsole-setup` sets up and configures either all virtual consoles, or — if the optional \ parameter is provided — a specific one. When the system is booting up, `systemd-vconsole-setup.service` is called by `systemd-udevd(8)` during VT console subsystem initialization. Also, `systemd-localed.service(8)` invokes it as needed when language or console changes are made. Internally, this program calls `loadkeys(1)` and `setfont(8)`. Execute `systemctl restart systemd-vconsole-setup.service` in order to apply any manual changes made to `/etc/vconsole.conf`. See `vconsole.conf(5)` for information about the configuration files and kernel command line options understood by this program. # Credentials `systemd-vconsole-setup` supports the service credentials logic as implemented by `ImportCredential=`/`LoadCredential=`/`SetCredential=` (see `systemd.exec(5)` for details). The following credentials are used when passed in: `vconsole.keymap`; `vconsole.keymap_toggle` The keymap (and toggle keymap) to apply. The matching options in `vconsole.conf` and on the kernel command line take precedence over these credentials. Note the relationship to the `firstboot.keymap` credential understood by `systemd-firstboot.service(1)`: both ultimately affect the same setting, but `firstboot.keymap` is written into `/etc/vconsole.conf` on first boot (if not already configured), and then read from there by `systemd-vconsole-setup`, while `vconsole.keymap` is read on every boot, and is not persisted to disk (but any configuration in `vconsole.conf` will take precedence if present). `vconsole.font`; `vconsole.font_map`; `vconsole.font_unimap`; `vconsole.font_scale` The console font settings to apply. The matching options in `vconsole.conf` and on the kernel command line take precedence over these credentials. `vconsole.font_scale` was added in version 262. # Firmware-provided keyboard layout If the boot loader reports the firmware-configured keyboard layout via the `LoaderKeyboardLayout` EFI variable (see the [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)), `systemd-vconsole-setup` uses it as the lowest-priority fallback for the keymap. The RFC 4646 / BCP 47 language tag reported by the firmware (e.g. `de-DE`) is matched against the optional sixth column of `/usr/share/systemd/kbd-model-map`, which lists the language tags each virtual-console keymap covers. Credentials, `/etc/vconsole.conf`, and kernel command line options all override this firmware-provided default. # See Also `systemd(1)`, `vconsole.conf(5)`, `loadkeys(1)`, `setfont(8)`, `systemd-localed.service(8)` # systemd-veritysetup-generator systemd systemd-veritysetup-generator 8 systemd-veritysetup-generator Unit generator for verity protected block devices `/usr/lib/systemd/system-generators/systemd-veritysetup-generator` # Description `systemd-veritysetup-generator` is a generator that translates kernel command line options configuring verity protected block devices into native systemd units early at boot and when configuration of the system manager is reloaded. This will create `systemd-veritysetup@.service(8)` units as necessary. Currently, only two verity devices may be set up with this generator, backing the root and `/usr` file systems of the OS. `systemd-veritysetup-generator` implements `systemd.generator(7)`. # Kernel Command Line `systemd-veritysetup-generator` understands the following kernel command line parameters: `systemd.verity=`; `rd.systemd.verity=` Takes a boolean argument. Defaults to `yes`. If `no`, disables the generator entirely. `rd.systemd.verity=` is honored only in the initrd while `systemd.verity=` is honored by both the main system and in the initrd. `veritytab=`; `rd.veritytab=` Takes a boolean argument. Defaults to `yes`. If `no`, causes the generator to ignore any devices configured in `/etc/veritytab`. `rd.veritytab=` is honored only in the initrd while `veritytab=` is honored by both the main system and in the initrd. `roothash=` Takes a root hash value for the root file system. Expects a hash value formatted in hexadecimal characters of the appropriate length (i.e. most likely 256 bit/64 characters, or longer). If not specified via `systemd.verity_root_data=` and `systemd.verity_root_hash=`, the hash and data devices to use are automatically derived from the specified hash value. Specifically, the data partition device is looked for under a GPT partition UUID derived from the first 128-bit of the root hash, the hash partition device is looked for under a GPT partition UUID derived from the last 128-bit of the root hash. Hence it is usually sufficient to specify the root hash to boot from a verity protected root file system, as device paths are automatically determined from it — as long as the partition table is properly set up. `systemd.verity_root_data=`; `systemd.verity_root_hash=` These two settings take block device paths as arguments and may be used to explicitly configure the data partition and hash partition to use for setting up the verity protection for the root file system. If not specified, these paths are automatically derived from the `roothash=` argument (see above). `systemd.verity_root_options=` Takes a comma-separated list of dm-verity options. Expects the following options `superblock=BOOLEAN`, `format=NUMBER`, `data-block-size=BYTES`, `hash-block-size=BYTES`, `data-blocks=BLOCKS`, `hash-offset=BYTES`, `salt=HEX`, `uuid=UUID`, `ignore-corruption`, `restart-on-corruption`, `ignore-zero-blocks`, `check-at-most-once`, `panic-on-corruption`, `hash=HASH`, `fec-device=PATH`, `fec-offset=BYTES`, `fec-roots=NUM` and `root-hash-signature=PATH|base64:HEX`. See `veritysetup(8)` for more details. `usrhash=`; `systemd.verity_usr_data=`; `systemd.verity_usr_hash=`; `systemd.verity_usr_options=` Equivalent to their counterparts for the root file system as described above, but apply to the `/usr/` file system instead. # See Also `systemd(1)`, `systemd-veritysetup@.service(8)`, `veritysetup(8)`, `systemd-fstab-generator(8)` # systemd-veritysetup@.service systemd systemd-veritysetup@.service 8 systemd-veritysetup@.service systemd-veritysetup Disk verity protection logic `systemd-veritysetup@.service` `/usr/lib/systemd/systemd-veritysetup` # Description `systemd-veritysetup@.service` is a service responsible for setting up verity protection block devices. It should be instantiated for each device that requires verity protection. At early boot and when the system manager configuration is reloaded kernel command line configuration for verity protected block devices is translated into `systemd-veritysetup@.service` units by `systemd-veritysetup-generator(8)`. `systemd-veritysetup@.service` calls `systemd-veritysetup`. # Commands The following commands are understood by `systemd-veritysetup`: `attach` \ \ \ \ \[\...\] Create a block device \ using \ and \ as the backing devices. \ forms the root of the tree of hashes stored on \. See [ Kernel dm-verity](https://docs.kernel.org/admin-guide/device-mapper/verity.html) documentation for details. `detach` \ Detach (destroy) the block device \. `help` Print short information about command syntax. # See Also `systemd(1)`, `systemd-veritysetup-generator(8)`, `veritysetup(8)` # systemd-volatile-root.service systemd systemd-volatile-root.service 8 systemd-volatile-root.service systemd-volatile-root Make the root file system volatile `systemd-volatile-root.service` `/usr/lib/systemd/systemd-volatile-root` # Description `systemd-volatile-root.service` is a service that replaces the root directory with a volatile memory file system (`tmpfs`), mounting the original (non-volatile) `/usr/` inside it read-only. This way, vendor data from `/usr/` is available as usual, but all configuration data in `/etc/`, all state data in `/var/` and all other resources stored directly under the root directory are reset on boot and lost at shutdown, enabling fully stateless systems. This service is only enabled if full volatile mode is selected, for example by specifying `systemd.volatile=yes` on the kernel command line. This service runs only in the initrd, before the system transitions to the host's root directory. Note that this service is not used if `systemd.volatile=state` is used, as in that mode the root directory is non-volatile. # See Also `systemd(1)`, `systemd-fstab-generator(8)`, `kernel-command-line(7)` # systemd-vpick systemd systemd-vpick 1 systemd-vpick Resolve paths to .v/ versioned directories systemd-vpick OPTIONS PATH # Description `systemd-vpick` resolves a file system path referencing a `.v/` versioned directory to a path to the newest (by version) file contained therein. This tool provides a command line interface for the `systemd.v(7)` logic. The tool expects a path to a `.v/` directory as argument (either directly, or with a triple underscore pattern as final component). It then determines the newest file contained in that directory, and writes its path to standard output. Unless the triple underscore pattern is passed as last component of the path, it is typically necessary to at least specify the `--suffix=` switch to configure the file suffix to look for. If the specified path does not reference a `.v/` path (i.e. neither the final component ends in `.v`, nor the penultimate does or the final one does contain a triple underscore) its specified path is written unmodified to standard output. # Options The following options are understood: `--basename=`; `-B` Overrides the "basename" of the files to look for, i.e. the part to the left of the variable part of the filenames. Normally this is derived automatically from the filename of the `.v` component of the specified path, or from the triple underscore pattern in the last component of the specified path. `-V` Explicitly configures the version to select. If specified, a filename with the specified version string will be looked for, instead of the newest version available. `-A` Explicitly configures the architecture to select. If specified, a filename with the specified architecture identifier will be looked for. If not specified, only filenames with a locally supported architecture are considered, or those without any architecture identifier. `--suffix=`; `-S` Configures the suffix of the filenames to consider. For the `.v/` logic it is necessary to specify the suffix to look for, and the `.v/` component must also carry the suffix immediately before `.v` in its name. `--type=`; `-t` Configures the inode type to look for in the `.v/` directory. Takes one of `reg`, `dir`, `sock`, `fifo`, `blk`, `chr`, `lnk` as argument, each identifying an inode type. See `inode(7)` for details about inode types. If this option is used inodes not matching the specified type are filtered and not taken into consideration. `--print=`; `-p` Configures what precisely to write to standard output. If not specified, prints the full, resolved path of the newest matching file in the `.v/` directory. This switch can be set to one of the following: - If set to `filename`, will print only the filename instead of the full path of the resolved file. - If set to `version`, will print only the version of the resolved file. - If set to `type`, will print only the inode type of the resolved file (i.e. a string such as `reg` for regular files, or `dir` for directories). - If set to `arch`, will print only the architecture of the resolved file. - If set to `tries`, will print only the tries left/tries done of the resolved file. - If set to `all`, will print all of the above in a simple tabular output. `--resolve=` Takes a boolean argument. If true the path to the versioned file is fully canonicalized (i.e. symlinks resolved, and redundant path components removed) before it is shown. If false (the default) this is not done, and the path is shown without canonicalization. # Examples Use a command like the following to automatically pick the newest raw disk image from a `.v/` directory: $ systemd-vpick --suffix=.raw --type=reg /var/lib/machines/quux.raw.v/ This will enumerate all regular files matching `/var/lib/machines/quux.raw.v/quux*.raw`, filter and sort them according to the rules described in `systemd.v(7)`, and then write the path to the newest (by version) file to standard output. Use a command like the following to automatically pick the newest OS directory tree from a `.v/` directory: $ systemd-vpick --type=dir /var/lib/machines/waldo.v/ This will enumerate all directory inodes matching `/var/lib/machines/waldo.v/waldo*`, filter and sort them according to the rules described in `systemd.v(7)`, and then write the path to the newest (by version) directory to standard output. For further examples see `systemd.v(7)`. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd.v(7)` # systemd-xdg-autostart-generator systemd systemd-xdg-autostart-generator 8 systemd-xdg-autostart-generator User unit generator for XDG autostart files `/usr/lib/systemd/user-generators/systemd-xdg-autostart-generator` # Description `systemd-xdg-autostart-generator` is a generator that creates .service units for [XDG autostart](https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html) files. This permits desktop environments to delegate startup of these applications to `systemd(1)` . Units created by `systemd-xdg-autostart-generator` can be started by the desktop environment using `xdg-desktop-autostart.target`. See `systemd.special(7)` for more details. XDG autostart may be conditionalized using both standardized and non-standardized keys. In order to handle these, the generator may create one or more `ExecCondition=` entries. For non-standardized keys, well-known helper binaries provided by Desktop Environments are used. All external helpers *must* detect their corresponding desktop environment and *must* return success when run in a different environment. This is important as all `ExecCondition=` directives must succeed for an application to be started. | Entry | Handling | |----|----| | `Hidden=`, `X-systemd-skip=` | No service will be generated if set to true | | `OnlyShowIn=`, `NotShowIn=` | `ExecCondition=` using `systemd-xdg-autostart-condition` | | `TryExec=` | No service will be generated if the binary does not exist or cannot be executed | | `AutostartCondition=` (GNOME extension) | `ExecCondition=` using `gnome-systemd-autostart-condition` | | `X-GNOME-Autostart-Phase=` | No service will be generated if set to any value | | `X-KDE-autostart-condition=` | `ExecCondition=` using `kde-systemd-start-condition` | Special XDG desktop file entries that are processed `systemd-xdg-autostart-generator` implements `systemd.generator(7)`. # See Also `systemd(1)`, `systemd.service(5)`, `systemd.target(5)` # systemd.automount systemd systemd.automount 5 systemd.automount Automount unit configuration `automount.automount` # Description A unit configuration file whose name ends in `.automount` encodes information about a file system automount point controlled and supervised by systemd. Automount units may be used to implement on-demand mounting as well as parallelized mounting of file systems. This man page lists the configuration options specific to this unit type. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. The automount specific configuration options are configured in the \[Automount\] section. Automount units must be named after the automount directories they control. Example: the automount point `/home/lennart` must be configured in a unit file `home-lennart.automount`. For details about the escaping logic used to convert a file system path to a unit name see `systemd.unit(5)`. Note that automount units cannot be templated, nor is it possible to add multiple names to an automount unit by creating symlinks to its unit file. For each automount unit file a matching mount unit file (see `systemd.mount(5)` for details) must exist which is activated when the automount path is accessed. Example: if an automount unit `home-lennart.automount` is active and the user accesses `/home/lennart` the mount unit `home-lennart.mount` will be activated. Note that automount units are separate from the mount itself, so you should not set `After=` or `Requires=` for mount dependencies here. For example, you should not set `After=network-online.target` or similar on network filesystems. Doing so may result in an ordering cycle. Note that automount support on Linux is privileged, automount units are hence only available in the system service manager (and root's user service manager), but not in unprivileged users' service managers. Note that automount units should not be nested. (The establishment of the inner automount point would unconditionally pin the outer mount point, defeating its purpose.) # Automatic Dependencies ## Implicit Dependencies The following dependencies are implicitly added: - If an automount unit is beneath another mount unit in the file system hierarchy, a requirement and ordering dependencies are created to the on the unit higher in the hierarchy. - An implicit `Before=` dependency is created between an automount unit and the mount unit it activates. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - Automount units acquire automatic `Before=` and `Conflicts=` on `umount.target` in order to be stopped during shutdown. - Automount units automatically gain an `After=` dependency on `local-fs-pre.target`, and a `Before=` dependency on `local-fs.target`. # `fstab` Automount units may either be configured via unit files, or via `/etc/fstab` (see `fstab(5)` for details). For details how systemd parses `/etc/fstab` see `systemd.mount(5)`. If an automount point is configured in both `/etc/fstab` and a unit file, the configuration in the latter takes precedence. # Options Automount unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. Automount unit files must include an \[Automount\] section, which carries information about the file system automount points it supervises. The options specific to the \[Automount\] section of automount units are the following: `Where=` Takes an absolute path of a directory of the automount point. If the automount point does not exist at time that the automount point is installed, it is created. This string must be reflected in the unit filename. (See above.) This option is mandatory. `ExtraOptions=` Extra mount options to use when creating the autofs mountpoint. This takes a comma-separated list of options. This setting is optional. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as `%%`. `DirectoryMode=` Directories of automount points (and any parent directories) are automatically created if needed. This option specifies the file system access mode used when creating these directories. Takes an access mode in octal notation. Defaults to 0755. `TimeoutIdleSec=` Configures an idle timeout. Once the mount has been idle for the specified time, systemd will attempt to unmount. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass 0 to disable the timeout logic. The timeout is disabled by default. # See Also `systemd(1)`, `systemctl(1)`, `systemd.unit(5)`, `systemd.mount(5)`, `mount(8)`, `automount(8)`, `systemd.directives(7)` # systemd.device systemd systemd.device 5 systemd.device Device unit configuration `device.device` # Description A unit configuration file whose name ends in `.device` encodes information about a device unit as exposed in the sysfs/`udev(7)` device tree. This may be used to define dependencies between devices and other units. This unit type has no specific options. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. A separate \[Device\] section does not exist, since no device-specific options may be configured. systemd will dynamically create device units for all kernel devices that are marked with the `systemd` udev tag (by default all block and network devices, and a few others). Note that *if `systemd-udevd.service` is not running, no device units will be available (for example in a typical container)*. Device units are named after the `/sys/` and `/dev/` paths they control. Example: the device `/dev/sda5` is exposed in systemd as `dev-sda5.device`. For details about the escaping logic used to convert a file system path to a unit name see `systemd.unit(5)`. To tag a udev device, use `TAG+="systemd"` in the udev rules file, see `udev(7)` for details. Device units will be reloaded by systemd whenever the corresponding device generates a `changed` event. Other units can use `ReloadPropagatedFrom=` to react to that event. # Automatic Dependencies ## Implicit Dependencies Many unit types automatically acquire dependencies on device units of devices they require. For example, `.socket` unit acquire dependencies on the device units of the network interface specified in `BindToDevice=`. Similar, swap and mount units acquire dependencies on the units encapsulating their backing block devices. ## Default Dependencies There are no default dependencies for device units. # The udev Database Unit settings of device units may either be configured via unit files, or directly from the udev database. The following udev device properties are understood by the service manager: `SYSTEMD_WANTS=`; `SYSTEMD_USER_WANTS=` Adds dependencies of type `Wants=` from the device unit to the specified units. `SYSTEMD_WANTS=` is read by the system service manager, `SYSTEMD_USER_WANTS=` by user service manager instances. These properties may be used to activate arbitrary units when a specific device becomes available. Note that this and the other udev device properties are not taken into account unless the device is tagged with the `systemd` tag in the udev database, because otherwise the device is not exposed as a systemd unit (see above). Note that systemd will only act on `Wants=` dependencies when a device first becomes active. It will not act on them if they are added to devices that are already active. Use `SYSTEMD_READY=` (see below) to configure when a udev device shall be considered active, and thus when to trigger the dependencies. The specified property value should be a space-separated list of valid unit names. If a unit template name is specified (that is, a unit name containing an `@` character indicating a unit name to use for multiple instantiation, but with an empty instance name following the `@`), it will be automatically instantiated by the device's `sysfs` path (that is: the path is escaped and inserted as instance name into the template unit name). This is useful in order to instantiate a specific template unit once for each device that appears and matches specific properties. `SYSTEMD_ALIAS=` Adds an additional alias name to the device unit. This must be an absolute path that is automatically transformed into a unit name. (See above.) `SYSTEMD_READY=` If set to 0, systemd will consider this device unplugged even if it shows up in the udev tree. If this property is unset or set to 1, the device will be considered plugged if it is visible in the udev tree. This option is useful for devices that initially show up in an uninitialized state in the tree, and for which a `changed` event is generated the moment they are fully set up. Note that `SYSTEMD_WANTS=` (see above) is not acted on as long as `SYSTEMD_READY=0` is set for a device. `ID_MODEL_FROM_DATABASE=`; `ID_MODEL=` If set, this property is used as description string for the device unit. # Options Device unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. No options specific to this file type are supported. # See Also `systemd(1)`, `systemctl(1)`, `systemd.unit(5)`, `udev(7)`, `systemd.directives(7)` # systemd.dns-delegate systemd systemd.dns-delegate 5 systemd.dns-delegate DNS Server Delegation Configuration `/etc/systemd/dns-delegate.d/*.dns-delegate`, `/run/systemd/dns-delegate.d/*.dns-delegate`, `/usr/local/lib/systemd/dns-delegate.d/*.dns-delegate`, `/usr/lib/systemd/dns-delegate.d/*.dns-delegate` # Description `*.dns-delegate` files may be used to delegate DNS lookups in specific domains to specific DNS servers. These files are read by `systemd-resolved.service(8)`. Each such file defines a combination of one or more DNS servers and one or more DNS domains. Each such definition synthesizes a DNS lookup scope that ensure lookups below the specified domains are sent to the specified DNS servers, possibly in addition to any per-interface scopes and the global scope that `systemd-resolved` maintains anyway. # \[Delegate\] Section Options `DNS=` Takes one or more DNS server specifications, in the same syntax as the option of the same name in `resolved.conf(5)`. `Domains=` Takes one or more domain name specifications, in the same syntax as the option of the same name in `resolved.conf(5)`. `DefaultRoute=` Takes a boolean value, defaults to off. Controls whether this DNS server is a candidate for looking up records for which no better route exists. `FirewallMark=` Takes a 32 bit unsigned integer value. Controls the firewall mark of packets generated by the socket used to make DNS requests for this DNS delegate. This can be used in the firewall logic to filter packets from this socket. This sets the `SO_MARK` socket option. See `iptables(8)` for details. # Examples
# /etc/systemd/dns-delegate.d/foobar.dns-delegate [Delegate] DNS=203.0.113.47 Domains=foobar.com FirewallMark=42 This ensures lookups of `foobar.com` and any domains below it are directed to DNS server 203.0.113.47 and any packets related to this lookup have a firewall mark set to 42.
# See Also `systemd(1)`, `systemd-resolved.service(8)`, `resolved.conf(5)`, `resolvectl(1)` # systemd.dnssd systemd systemd.dnssd 5 systemd.dnssd DNS-SD configuration `network_service.dnssd` # Description DNS-SD setup is performed by `systemd-resolved(8)`. The main network service file must have the extension `.dnssd`; other extensions are ignored. The `.dnssd` files are read from the files located in the system network directories `/usr/lib/systemd/dnssd` and `/usr/local/lib/systemd/dnssd`, the volatile runtime network directory `/run/systemd/dnssd` and the local administration network directory `/etc/systemd/dnssd`. All configuration files are collectively sorted and processed in lexicographic order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in `/etc/` have the highest priority, files in `/run/` take precedence over files with the same name in `/usr/lib/`. This can be used to override a system-supplied configuration file with a local file if needed. Along with the network service file `foo.dnssd`, a "drop-in" directory `foo.dnssd.d/` may exist. All files with the suffix `.conf` from this directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings, without having to modify the main configuration file. Each drop-in file must have appropriate section headers. In addition to `/etc/systemd/dnssd`, drop-in `.d` directories can be placed in `/usr/lib/systemd/dnssd` or `/run/systemd/dnssd` directories. Drop-in files in `/etc/` take precedence over those in `/run/` which in turn take precedence over those in `/usr/lib/` or `/usr/local/lib`. Drop-in files under any of these directories take precedence over the main network service file wherever located. # \[Service\] Section Options The network service file contains a \[Service\] section, which specifies a discoverable network service announced in a local network with Multicast DNS broadcasts. `Name=` An instance name of the network service as defined in the section 4.1.1 of [RFC 6763](https://tools.ietf.org/html/rfc6763), e.g. `webserver`. The option supports simple specifier expansion. The following expansions are understood: | Specifier | Meaning | Details | |-----------|---------|---------| Specifiers available {.specifiers} `Type=` A type of the network service as defined in the section 4.1.2 of [RFC 6763](https://tools.ietf.org/html/rfc6763), e.g. `_http._tcp`. `SubType=` A subtype of the network service as defined in the section 7.1 of [RFC 6763](https://tools.ietf.org/html/rfc6763), e.g. `_printer`. `Port=` An IP port number of the network service. `Priority=` A priority number set in `SRV` resource records corresponding to the network service. `Weight=` A weight number set in `SRV` resource records corresponding to the network service. `TxtText=` A whitespace-separated list of arbitrary key/value pairs conveying additional information about the named service in the corresponding TXT resource record, e.g. `path=/portal/index.html`. Keys and values can contain C-style escape sequences which get translated upon reading configuration files. This option together with `TxtData=` may be specified more than once, in which case multiple TXT resource records will be created for the service. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect. `TxtData=` A whitespace-separated list of arbitrary key/value pairs conveying additional information about the named service in the corresponding TXT resource record where values are base64-encoded string representing any binary data, e.g. `data=YW55IGJpbmFyeSBkYXRhCg==`. Keys can contain C-style escape sequences which get translated upon reading configuration files. This option together with `TxtText=` may be specified more than once, in which case multiple TXT resource records will be created for the service. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect. # Examples
HTTP service
# /etc/systemd/dnssd/http.dnssd [Service] Name=%H Type=_http._tcp Port=80 TxtText=path=/stats/index.html t=temperature_sensor This makes the http server running on the host discoverable in the local network given MulticastDNS is enabled on the network interface. Now the utility `resolvectl` should be able to resolve the service to the host's name: $ resolvectl service meteo._http._tcp.local meteo._http._tcp.local: meteo.local:80 [priority=0, weight=0] 169.254.208.106%senp0s21f0u2u4 fe80::213:3bff:fe49:8aa%senp0s21f0u2u4 path=/stats/index.html t=temperature_sensor (meteo/_http._tcp/local) -- Information acquired via protocol mDNS/IPv6 in 4.0ms. -- Data is authenticated: yes `Avahi` running on a different host in the same local network should see the service as well: $ avahi-browse -a -r + enp3s0 IPv6 meteo Web Site local + enp3s0 IPv4 meteo Web Site local = enp3s0 IPv6 meteo Web Site local hostname = [meteo.local] address = [fe80::213:3bff:fe49:8aa] port = [80] txt = ["path=/stats/index.html" "t=temperature_sensor"] = enp3s0 IPv4 meteo Web Site local hostname = [meteo.local] address = [169.254.208.106] port = [80] txt = ["path=/stats/index.html" "t=temperature_sensor"]
# See Also `systemd(1)`, `systemd-resolved.service(8)`, `resolvectl(1)` # systemd.exec systemd systemd.exec 5 systemd.exec Execution environment configuration `service.service`, `socket.socket`, `mount.mount`, `swap.swap` # Description Unit configuration files for services, sockets, mount points, and swap devices share a subset of configuration options which define the execution environment of spawned processes. This man page lists the configuration options shared by these four unit types. See `systemd.unit(5)` for the common options of all unit configuration files, and `systemd.service(5)`, `systemd.socket(5)`, `systemd.swap(5)`, and `systemd.mount(5)` for more information on the specific unit configuration files. The execution specific configuration options are configured in the \[Service\], \[Socket\], \[Mount\], or \[Swap\] sections, depending on the unit type. In addition, options which control resources through Linux Control Groups (cgroups) are listed in `systemd.resource-control(5)`. Those options complement options listed here. # Implicit Dependencies A few execution parameters result in additional, automatic dependencies to be added: - Units with `WorkingDirectory=`, `RootDirectory=`, `RootImage=`, `RuntimeDirectory=`, `StateDirectory=`, `CacheDirectory=`, `LogsDirectory=` or `ConfigurationDirectory=` set automatically gain dependencies of type `Requires=` and `After=` on all mount units required to access the specified paths. This is equivalent to having them listed explicitly in `RequiresMountsFor=`. - Units with `PrivateTmp=yes` automatically gain dependencies of type `Wants=` and `After=` on all mounts required to access `/tmp/` and `/var/tmp/` and an automatic `After=` dependency on `systemd-tmpfiles-setup.service(8)`, unless `DefaultDependencies=no` is specified. If `DefaultDependencies=no` is specified, and a `RequiresMountsFor=/tmp/`, `WantsMountsFor=/tmp/`, `After=tmp.mount`, or `RootDirectory=`/`RootImage=` are not specified, `PrivateTmp=yes` is converted to `PrivateTmp=disconnected`. - Units with `PrivateTmp=disconnected` automatically gain dependencies of type `Wants=` and `After=` on the mount required to access `/var/`, unless `DefaultDependencies=no` and/or `RootDirectory=`/`RootImage=` are specified. If `DefaultDependencies=no` is specified, and a `RequiresMountsFor=/var/`, `WantsMountsFor=/var/`, `After=var.mount`, `RootDirectory=`/`RootImage=` are not specified, the private mount on `/tmp/` is reused for `/var/tmp/` by setting `$TMPDIR` appropriately. - Units whose standard output or error output is connected to `journal` or `kmsg` (or their combinations with console output, see below) automatically acquire dependencies of type `After=` on `systemd-journald.socket`. - Units whose standard input, output or error output is connected to a pseudo TTY allocated by the PTY broker (i.e. `broker` or `broker-log`, see below) automatically acquire dependencies of type `After=` and `Wants=` on `systemd-ptybrokerd.socket`. - Units using `LogNamespace=` will automatically gain ordering and requirement dependencies on the two socket units associated with `systemd-journald@.service` instances. # Paths The following settings may be used to change a service's view of the filesystem. Please note that the paths must be absolute and must not contain a `..` path component. `ExecSearchPath=` Takes a colon separated list of absolute paths relative to which the executable used by the `Exec*=` (e.g. `ExecStart=`, `ExecStop=`, etc.) properties can be found. `ExecSearchPath=` overrides `$PATH` if `$PATH` is not supplied by the user through `Environment=`, `EnvironmentFile=` or `PassEnvironment=`. Assigning an empty string removes previous assignments and setting `ExecSearchPath=` to a value multiple times will append to the previous setting. `WorkingDirectory=` Takes a directory path relative to the service's root directory specified by `RootDirectory=`, or the special value `~`. Sets the working directory for executed processes. If set to `~`, the home directory of the user specified in `User=` is used. If not set, defaults to the root directory when systemd is running as a system instance and the respective user's home directory if run as user. If the setting is prefixed with the `-` character, a missing working directory is not considered fatal. If `RootDirectory=`/`RootImage=` is not set, then `WorkingDirectory=` is relative to the root of the system running the service manager. Note that setting this parameter might result in additional dependencies to be added to the unit (see above). `RootDirectory=` Takes a directory path relative to the host's root directory (i.e. the root of the system running the service manager). Sets the root directory for executed processes, with the `pivot_root(2)` or `chroot(2)` system call. If this is used, it must be ensured that the process binary and all its auxiliary files are available in the new root. Note that setting this parameter might result in additional dependencies to be added to the unit (see above). The `MountAPIVFS=` and `PrivateUsers=` settings are particularly useful in conjunction with `RootDirectory=`. For details, see below. If `RootDirectory=`/`RootImage=` are used together with `NotifyAccess=` the notification socket is automatically mounted from the host into the root environment, to ensure the notification interface can work correctly. Note that services using `RootDirectory=`/`RootImage=` will not be able to log via the syslog or journal protocols to the host logging infrastructure, unless the relevant sockets are mounted from the host, specifically: The host's `os-release(5)` file will be made available for the service (read-only) as `/run/host/os-release`. It will be updated automatically on soft reboot (see: `systemd-soft-reboot.service(8)`), in case the service is configured to survive it.
Mounting logging sockets into root environment
BindReadOnlyPaths=/dev/log /run/systemd/journal/socket /run/systemd/journal/stdout
`RootImage=` Takes a path to a block device node or regular file as argument. This call is similar to `RootDirectory=` however mounts a file system hierarchy from a block device node or loopback file instead of a directory. The device node or file system image file needs to contain a file system without a partition table, or a file system within an MBR/MS-DOS or GPT partition table with only a single Linux-compatible partition, or a set of file systems within a GPT partition table that follows the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). When `DevicePolicy=` is set to `closed` or `strict`, or set to `auto` and `DeviceAllow=` is set, then this setting adds `/dev/loop-control` with `rw` mode, `block-loop` and `block-blkext` with `rwm` mode to `DeviceAllow=`. See `systemd.resource-control(5)` for the details about `DevicePolicy=` or `DeviceAllow=`. Also, see `PrivateDevices=` below, as it may change the setting of `DevicePolicy=`. Units making use of `RootImage=` automatically gain an `After=` dependency on `systemd-udevd.service`. The host's `os-release(5)` file will be made available for the service (read-only) as `/run/host/os-release`. It will be updated automatically on soft reboot (see: `systemd-soft-reboot.service(8)`), in case the service is configured to survive it. `RootImageOptions=` Takes a comma-separated list of mount options that will be used on disk images specified by `RootImage=`. Optionally a partition name can be prefixed, followed by colon, in case the image has multiple partitions, otherwise partition name `root` is implied. Options for multiple partitions can be specified in a single line with space separators. Assigning an empty string removes previous assignments. For a list of valid mount options, please refer to `mount(8)`. Valid partition names follow the [ Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification): `root`, `usr`, `home`, `srv`, `esp`, `xbootldr`, `tmp`, `var`. `RootEphemeral=` Takes a boolean argument. If enabled, executed processes will run in an ephemeral copy of the root directory or root image. The ephemeral copy is placed in `/var/lib/systemd/ephemeral-trees/` while the service is active and is cleaned up when the service is stopped or restarted. If `RootDirectory=` is used and the root directory is a subvolume, the ephemeral copy will be created by making a snapshot of the subvolume. To make sure making ephemeral copies can be made efficiently, the root directory or root image should be located on the same filesystem as `/var/lib/systemd/ephemeral-trees/`. When using `RootEphemeral=` with root directories, `btrfs(5)` should be used as the filesystem and the root directory should ideally be a subvolume which `systemd` can snapshot to make the ephemeral copy. For root images, a filesystem with support for reflinks should be used to ensure an efficient ephemeral copy. `RootHash=` Takes a data integrity (dm-verity) root hash specified in hexadecimal, or the path to a file containing a root hash in ASCII hexadecimal format. This option enables data integrity checks using dm-verity, if the used image contains the appropriate integrity data (see above) or if `RootVerity=` is used. The specified hash must match the root hash of integrity data, and is usually at least 256 bits (and hence 64 formatted hexadecimal characters) long (in case of SHA256 for example). If this option is not specified, but the image file carries the `user.verity.roothash` extended file attribute (see `xattr(7)`), then the root hash is read from it, also as formatted hexadecimal characters. If the extended file attribute is not found (or is not supported by the underlying file system), but a file with the `.roothash` suffix is found next to the image file, bearing otherwise the same name (except if the image has the `.raw` suffix, in which case the root hash file must not have it in its name), the root hash is read from it and automatically used, also as formatted hexadecimal characters. If the disk image contains a separate `/usr/` partition it may also be Verity protected, in which case the root hash may configured via an extended attribute `user.verity.usrhash` or a `.usrhash` file adjacent to the disk image. There's currently no option to configure the root hash for the `/usr/` file system via the unit file directly. `RootHashSignature=` Takes a PKCS7 signature of the `RootHash=` option as a path to a DER-encoded signature file, or as an ASCII base64 string encoding of a DER-encoded signature prefixed by `base64:`. The signature is validated against the public keys in the kernel keyring and the certificates in `/etc/verity.d/`. If neither validates the signature, the dm-verity volume is only opened if `RootImagePolicy=` allows `verity` for the root partition, which the default policy does. To require a valid signature, set `RootImagePolicy=` to a policy that allows `signed` but not `verity` for the root partition. If this option is not specified, but a file with the `.roothash.p7s` suffix is found next to the image file, bearing otherwise the same name (except if the image has the `.raw` suffix, in which case the signature file must not have it in its name), the signature is read from it and automatically used. If the disk image contains a separate `/usr/` partition it may also be Verity protected, in which case the signature for the root hash may configured via a `.usrhash.p7s` file adjacent to the disk image. There's currently no option to configure the root hash signature for the `/usr/` via the unit file directly. `RootVerity=` Takes the path to a data integrity (dm-verity) file. This option enables data integrity checks using dm-verity, if `RootImage=` is used and a root-hash is passed and if the used image itself does not contain the integrity data. The integrity data must be matched by the root hash. If this option is not specified, but a file with the `.verity` suffix is found next to the image file, bearing otherwise the same name (except if the image has the `.raw` suffix, in which case the verity data file must not have it in its name), the verity data is read from it and automatically used. This option is supported only for disk images that contain a single file system, without an enveloping partition table. Images that contain a GPT partition table should instead include both root file system and matching Verity data in the same image, implementing the [ Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). `RootImagePolicy=`; `MountImagePolicy=`; `ExtensionImagePolicy=` Takes an image policy string as per `systemd.image-policy(7)` to use when mounting the disk images (DDI) specified in `RootImage=`, `MountImage=`, `ExtensionImage=`, respectively. If not specified the following policy string is the default for `RootImagePolicy=` and `MountImagePolicy`: root=verity+signed+encrypted+unprotected+absent: \ usr=verity+signed+encrypted+unprotected+absent: \ home=encrypted+unprotected+absent: \ srv=encrypted+unprotected+absent: \ tmp=encrypted+unprotected+absent: \ var=encrypted+unprotected+absent The default policy for `ExtensionImagePolicy=` is: root=verity+signed+encrypted+unprotected+absent: \ usr=verity+signed+encrypted+unprotected+absent `RootMStack=` Takes a path to a `systemd.mstack(7)` directory encapsulating a mount stack consisting of layers and bind mounts. Similar to `RootDirectory=` and `RootImage=` this runs the service off a distinct root file system, in this case set up via `overlayfs`. Since `.mstack/` directories may reference disk images (DDIs) similar device policy extensions and dependencies are in effect when `RootMStack=` is used as are if `RootImage=` is used. `MountAPIVFS=` Takes a boolean argument. If on, a private mount namespace for the unit's processes is created and the API file systems `/proc/`, `/sys/`, `/dev/` and `/run/` (as an empty `tmpfs`) are mounted inside of it, unless they are already mounted. Note that this option has no effect unless used in conjunction with `RootDirectory=`/`RootImage=` as these four mounts are generally mounted in the host anyway, and unless the root directory is changed, the private mount namespace will be a 1:1 copy of the host's, and include these four mounts. Note that the `/dev/` file system of the host is bind mounted if this option is used without `PrivateDevices=`. To run the service with a private, minimal version of `/dev/`, combine this option with `PrivateDevices=`. In order to allow propagating mounts at runtime in a safe manner, `/run/systemd/propagate/` on the host will be used to set up new mounts, and `/run/host/incoming/` in the private namespace will be used as an intermediate step to store them before being moved to the final mount point. `BindLogSockets=` Takes a boolean argument. If true, sockets from `systemd-journald.socket(8)` will be bind mounted into the mount namespace. This is particularly useful when a different instance of `/run/` is employed, to make sure processes running in the namespace can still make use of `sd-journal(3)`. This option is implied when `LogNamespace=` is used, when `MountAPIVFS=yes`, or when `PrivateDevices=yes` is used in conjunction with either `RootDirectory=` or `RootImage=`. `ProtectProc=` Takes one of `noaccess`, `invisible`, `ptraceable` or `default` (which it defaults to). When set, this controls the `hidepid=` mount option of the `procfs` instance for the unit that controls which directories with process metainformation (`/proc/PID`) are visible and accessible: when set to `noaccess` the ability to access most of other users' process metadata in `/proc/` is taken away for processes of the service. When set to `invisible` processes owned by other users are hidden from `/proc/`. If `ptraceable` all processes that cannot be `ptrace()`'ed by a process are hidden to it. If `default` no restrictions on `/proc/` access or visibility are made. For further details see [The /proc Filesystem](https://docs.kernel.org/filesystems/proc.html#mount-options). It is generally recommended to run most system services with this option set to `invisible`. This option is implemented via file system namespacing, and thus cannot be used with services that shall be able to install mount points in the host file system hierarchy. Note that the root user is unaffected by this option, so to be effective it has to be used together with `User=` or `DynamicUser=yes`, and also without the `CAP_SYS_PTRACE` capability, which also allows a process to bypass this feature. It cannot be used for services that need to access metainformation about other users' processes. This option implies `MountAPIVFS=`. If the kernel does not support per-mount point `hidepid=` mount options this setting remains without effect, and the unit's processes will be able to access and see other process as if the option was not used. `ProcSubset=` Takes one of `all` (the default) and `pid`. If `pid`, all files and directories not directly associated with process management and introspection are made invisible in the `/proc/` file system configured for the unit's processes. This controls the `subset=` mount option of the `procfs` instance for the unit. For further details see [The /proc Filesystem](https://docs.kernel.org/filesystems/proc.html#mount-options). Note that Linux exposes various kernel APIs via `/proc/`, which are made unavailable with this setting. Since these APIs are used frequently this option is useful only in a few, specific cases, and is not suitable for most non-trivial programs. Much like `ProtectProc=` above, this is implemented via file system mount namespacing, and hence the same restrictions apply: it is only available to system services, it disables mount propagation to the host mount table, and it implies `MountAPIVFS=`. Also, like `ProtectProc=` this setting is gracefully disabled if the used kernel does not support the `subset=` mount option of `procfs`. `BindPaths=`; `BindReadOnlyPaths=` Configures unit-specific bind mounts. A bind mount makes a particular file or directory available at an additional place in the unit's view of the file system. Any bind mounts created with this option are specific to the unit, and are not visible in the host's mount table. This option expects a whitespace separated list of bind mount definitions. Each definition consists of a colon-separated triple of source path, destination path and option string, where the latter two are optional. If only a source path is specified the source and destination is taken to be the same. The option string may be either `rbind` or `norbind` for configuring a recursive or non-recursive bind mount. If the destination path is omitted, the option string must be omitted too. Each bind mount definition may be prefixed with `-`, in which case it will be ignored when its source path does not exist or is not accessible. `BindPaths=` creates regular writable bind mounts (unless the source file system mount is already marked read-only), while `BindReadOnlyPaths=` creates read-only bind mounts. These settings may be used more than once, each usage appends to the unit's list of bind mounts. If the empty string is assigned to either of these two options the entire list of bind mounts defined prior to this is reset. Note that, in this case, both read-only and regular bind mounts are reset, regardless which of the two settings is used. Using this option implies that a mount namespace is allocated for the unit, i.e. it implies the effect of `PrivateMounts=` (see below). This option is particularly useful when `RootDirectory=`/`RootImage=` is used. In this case, the source path refers to a path on the host file system, while the destination path refers to a path below the root directory of the unit. Note that the destination directory must exist or systemd must be able to create it. Thus, it is not possible to use those options for mount points nested underneath paths specified in `InaccessiblePaths=`, or under `/home/` and other protected directories if `ProtectHome=yes` is specified. `TemporaryFileSystem=` with `:ro` or `ProtectHome=tmpfs` should be used instead. `MountImages=` This setting is similar to `RootImage=` in that it mounts a file system hierarchy from a block device node or loopback file, but the destination directory can be specified as well as mount options. This option expects a whitespace separated list of mount definitions. Each definition consists of a colon-separated tuple of source path and destination definitions, optionally followed by another colon and a list of mount options. Mount options may be defined as a single comma-separated list of options, in which case they will be implicitly applied to the root partition on the image, or a series of colon-separated tuples of partition name and mount options. Valid partition names and mount options are the same as for `RootImageOptions=` setting described above. Each mount definition may be prefixed with `-`, in which case it will be ignored when its source path does not exist. The source argument is a path to a block device node or regular file. If source or destination contain a `:`, it needs to be escaped as `\:`. The device node or file system image file needs to follow the same rules as specified for `RootImage=`. Any mounts created with this option are specific to the unit, and are not visible in the host's mount table. These settings may be used more than once, each usage appends to the unit's list of mount paths. If the empty string is assigned, the entire list of mount paths defined prior to this is reset. Note that the destination directory must exist or systemd must be able to create it. Thus, it is not possible to use those options for mount points nested underneath paths specified in `InaccessiblePaths=`, or under `/home/` and other protected directories if `ProtectHome=yes` is specified. When `DevicePolicy=` is set to `closed` or `strict`, or set to `auto` and `DeviceAllow=` is set, then this setting adds `/dev/loop-control` with `rw` mode, `block-loop` and `block-blkext` with `rwm` mode to `DeviceAllow=`. See `systemd.resource-control(5)` for the details about `DevicePolicy=` or `DeviceAllow=`. Also, see `PrivateDevices=` below, as it may change the setting of `DevicePolicy=`. `ExtensionImages=` This setting is similar to `MountImages=` in that it mounts a file system hierarchy from a block device node or loopback file, but instead of providing a destination path, an overlay will be set up. This option expects a whitespace separated list of mount definitions. Each definition consists of a source path, optionally followed by a colon and a list of mount options. A read-only OverlayFS will be set up on top of `/usr/` and `/opt/` hierarchies for sysext images and `/etc/` hierarchy for confext images. The order in which the images are listed will determine the order in which the overlay is laid down: images specified first to last will result in overlayfs layers bottom to top. Mount options may be defined as a single comma-separated list of options, in which case they will be implicitly applied to the root partition on the image, or a series of colon-separated tuples of partition name and mount options. Valid partition names and mount options are the same as for `RootImageOptions=` setting described above. Each mount definition may be prefixed with `-`, in which case it will be ignored when its source path does not exist. The source argument is a path to a block device node or regular file. If the source path contains a `:`, it needs to be escaped as `\:`. The device node or file system image file needs to follow the same rules as specified for `RootImage=`. Any mounts created with this option are specific to the unit, and are not visible in the host's mount table. These settings may be used more than once, each usage appends to the unit's list of image paths. If the empty string is assigned, the entire list of mount paths defined prior to this is reset. Each sysext image must carry a `/usr/lib/extension-release.d/extension-release.IMAGE` file while each confext image must carry a `/etc/extension-release.d/extension-release.IMAGE` file, with the appropriate metadata which matches `RootImage=`/`RootDirectory=` or the host. See: `os-release(5)`. To disable the safety check that the extension-release file name matches the image file name, the `x-systemd.relax-extension-release-check` mount option may be appended. If a service employs this option with `systemd.v(7)`, and has `RefreshOnReload=extensions` enabled (the default), the confexts will be refreshed to pick up any changes on service reload. This only applies to confext extensions. Note that in case a service has this configuration enabled at first, and then it is subsequently removed in an update followed by a daemon-reload operation, reloading the confexts will be a no-op, and a full service restart is required instead. See `systemd.service(5)` also for details. When `DevicePolicy=` is set to `closed` or `strict`, or set to `auto` and `DeviceAllow=` is set, then this setting adds `/dev/loop-control` with `rw` mode, `block-loop` and `block-blkext` with `rwm` mode to `DeviceAllow=`. See `systemd.resource-control(5)` for the details about `DevicePolicy=` or `DeviceAllow=`. Also, see `PrivateDevices=` below, as it may change the setting of `DevicePolicy=`. `ExtensionDirectories=` This setting is similar to `BindReadOnlyPaths=` in that it mounts a file system hierarchy from a directory, but instead of providing a destination path, an overlay will be set up. This option expects a whitespace separated list of source directories. A read-only OverlayFS will be set up on top of `/usr/` and `/opt/` hierarchies for sysext images and `/etc/` hierarchy for confext images. The order in which the directories are listed will determine the order in which the overlay is laid down: directories specified first to last will result in overlayfs layers bottom to top. Each directory listed in `ExtensionDirectories=` may be prefixed with `-`, in which case it will be ignored when its source path does not exist. Any mounts created with this option are specific to the unit, and are not visible in the host's mount table. These settings may be used more than once, each usage appends to the unit's list of directories paths. If the empty string is assigned, the entire list of mount paths defined prior to this is reset. Each sysext directory must contain a `/usr/lib/extension-release.d/extension-release.IMAGE` file while each confext directory must carry a `/etc/extension-release.d/extension-release.IMAGE` file, with the appropriate metadata which matches `RootImage=`/`RootDirectory=` or the host. See: `os-release(5)`. If a service employs this option with `systemd.v(7)`, and has `RefreshOnReload=extensions` enabled (the default), the confexts will be refreshed to pick up any changes on service reload. This only applies to confext extensions. Note that in case a service has this configuration enabled at first, and then it is subsequently removed in an update followed by a daemon-reload operation, reloading the confexts will be a no-op, and a full service restart is required instead. See `systemd.service(5)` also for details. Note that usage from user units requires overlayfs support in unprivileged user namespaces, which was first introduced in kernel v5.11. # User/Group Identity `User=`; `Group=` Set the UNIX user or group that the processes are executed as, respectively. Takes a single user or group name, or a numeric ID as argument. For system services (services run by the system service manager, i.e. managed by PID 1) and for user services of the root user (services managed by root's instance of `systemd --user`), the default is `root`, but `User=` may be used to specify a different user. For user services of any other user, switching user identity is not permitted, hence the only valid setting is the same user the user's service manager is running as. If no group is set, the default group of the user is used. This setting does not affect commands whose command line is prefixed with `+`. Note that this enforces only weak restrictions on the user/group name syntax, but will generate warnings in many cases where user/group names do not adhere to the following rules: the specified name should consist only of the characters a-z, A-Z, 0-9, `_` and `-`, except for the first character which must be one of a-z, A-Z and `_` (i.e. digits and `-` are not permitted as first character). The user/group name must have at least one character, and at most 31. These restrictions are made in order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux systems. For further details on the names accepted and the names warned about see [User/Group Name Syntax](https://systemd.io/USER_NAMES). When used in conjunction with `DynamicUser=` the user/group name specified is dynamically allocated at the time the service is started, and released at the time the service is stopped — unless it is already allocated statically (see below). If `DynamicUser=` is not used the specified user and group must have been created statically in the user database no later than the moment the service is started, for example using the `sysusers.d(5)` facility, which is applied at boot or package install time. If the user does not exist by then program invocation will fail. If the `User=` setting is used the supplementary group list is initialized from the specified user's default group list, as defined in the system's user and group database. Additional groups may be configured through the `SupplementaryGroups=` setting (see below). `DynamicUser=` Takes a boolean parameter. If set, a UNIX user and group pair is allocated dynamically when the unit is started, and released as soon as it is stopped. The user and group will not be added to `/etc/passwd` or `/etc/group`, but are managed transiently during runtime. The `nss-systemd(8)` glibc NSS module provides integration of these dynamic users/groups into the system's user and group databases. The user and group name to use may be configured via `User=` and `Group=` (see above). If these options are not used and dynamic user/group allocation is enabled for a unit, the name of the dynamic user/group is implicitly derived from the unit name. If the unit name without the type suffix qualifies as valid user name it is used directly, otherwise a name incorporating a hash of it is used. If a statically allocated user or group of the configured name already exists, it is used and no dynamic user/group is allocated. Note that if `User=` is specified and the static group with the name exists, then it is required that the static user with the name already exists. Similarly, if `Group=` is specified and the static user with the name exists, then it is required that the static group with the name already exists. Dynamic users/groups are allocated from the UID/GID range 61184…65519. It is recommended to avoid this range for regular system or login users. At any point in time each UID/GID from this range is only assigned to zero or one dynamically allocated users/groups in use. However, UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to these files or directories. If `DynamicUser=` is enabled, `RemoveIPC=` is implied (and cannot be turned off). This ensures that the lifetime of IPC objects and temporary files created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic user/group. Since `/tmp/` and `/var/tmp/` are usually the only world-writable directories on a system, unless `PrivateTmp=` is manually set to `true`, `disconnected` would be implied. This ensures that a unit making use of dynamic user/group allocation cannot leave files around after unit termination. Furthermore `NoNewPrivileges=` and `RestrictSUIDSGID=` are implicitly enabled (and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID files or directories. Moreover, `ProtectSystem=strict` and `ProtectHome=read-only` are implied, thus prohibiting the service to write to arbitrary file system locations. In order to allow the service to write to certain directories, they have to be allow-listed using `ReadWritePaths=`, but care must be taken so that UID/GID recycling does not create security issues involving files created by the service. Use `RuntimeDirectory=` (see below) in order to assign a writable runtime directory to a service, owned by the dynamic user/group and removed automatically when the unit is terminated. Use `StateDirectory=`, `CacheDirectory=` and `LogsDirectory=` in order to assign a set of writable directories for specific purposes to the service in a way that they are protected from vulnerabilities due to UID reuse (see below). If this option is enabled, care should be taken that the unit's processes do not get access to directories outside of these explicitly configured and managed ones. Specifically, do not use `BindPaths=` and be careful with `AF_UNIX` file descriptor passing for directory file descriptors, as this would permit processes to create files or directories owned by the dynamic user/group that are not subject to the lifecycle and access guarantees of the service. Note that this option is currently incompatible with D-Bus policies, thus a service using this option may currently not allocate a D-Bus service name (note that this does not affect calling into other D-Bus services). Defaults to off. `SupplementaryGroups=` Sets the supplementary Unix groups the processes are executed as. This takes a space-separated list of group names or IDs. This option may be specified more than once, in which case all listed groups are set as supplementary groups. When the empty string is assigned, the list of supplementary groups is reset, and all assignments prior to this one will have no effect. In any way, this option does not override, but extends the list of supplementary groups configured in the system group database for the user. This does not affect commands prefixed with `+`. `SetLoginEnvironment=` Takes a boolean parameter that controls whether to set the `$HOME`, `$LOGNAME`, and `$SHELL` environment variables. If not set, this defaults to true if `User=`, `DynamicUser=` or `PAMName=` are set, false otherwise. If set to true, the variables will always be set for system services, i.e. even when the default user `root` is used. If set to false, the mentioned variables are not set by the service manager, no matter whether `User=`, `DynamicUser=`, or `PAMName=` are used or not. This option normally has no effect on services of the per-user service manager, since in that case these variables are typically inherited from user manager's own environment anyway. `PAMName=` Sets the PAM service name to set up a session as. If set, the executed process will be registered as a PAM session under the specified service name. This is only useful in conjunction with the `User=` setting, and is otherwise ignored. If not set, no PAM session will be opened for the executed processes. See `pam(8)` for details. Note that for each unit making use of this option a PAM session handler process will be maintained as part of the unit and stays around as long as the unit is active, to ensure that appropriate actions can be taken when the unit and hence the PAM session terminates. This process is named `(sd-pam)` and is an immediate child process of the unit's main process. Note that when this option is used for a unit it is very likely (depending on PAM configuration) that the main unit process will be migrated to its own session scope unit when it is activated. This process will hence be associated with two units: the unit it was originally started from (and for which `PAMName=` was configured), and the session scope unit. Any child processes of that process will however be associated with the session scope unit only. This has implications when used in combination with `NotifyAccess=``all`, as these child processes will not be able to affect changes in the original unit through notification messages. These messages will be considered belonging to the session scope unit and not the original unit. It is hence not recommended to use `PAMName=` in combination with `NotifyAccess=``all`. If a PAM module interactively requests input (a password or suchlike) it will be attempted to be read from a service credential (as configured via `SetCredential=`, `ImportCredential=` and related calls) under the name `pam.authtok.pamservice`, where \ is replaced by the PAM service name as configured with `PAMName=`. (Note that the credential remains accessible for the runtime of the service!) If no matching credential is set, the user is prompted for it interactively via the [Password Agent](https://systemd.io/PASSWORD_AGENTS) logic. # Capabilities `CapabilityBoundingSet=` Controls which capabilities to include in the capability bounding set for the executed process. See `capabilities(7)` for details. Takes a whitespace-separated list of capability names, e.g. `CAP_SYS_ADMIN`, `CAP_DAC_OVERRIDE`, `CAP_SYS_PTRACE`. Capabilities listed will be included in the bounding set, all others are removed. If the list of capabilities is prefixed with `~`, all but the listed capabilities will be included, the effect of the assignment inverted. Note that this option also affects the respective capabilities in the effective, permitted and inheritable capability sets. If this option is not used, the capability bounding set is not modified on process execution, hence no limits on the capabilities of the process are enforced. This option may appear more than once, in which case the bounding sets are merged by `OR`, or by `AND` if the lines are prefixed with `~` (see below). If the empty string is assigned to this option, the bounding set is reset to the empty capability set, and all prior settings have no effect. If set to `~` (without any further argument), the bounding set is reset to the full set of available capabilities, also undoing any previous settings. This does not affect commands prefixed with `+`. Use `systemd-analyze(1)`'s `capability` command to retrieve a list of capabilities defined on the local system. Example: if a unit has the following, CapabilityBoundingSet=CAP_A CAP_B CapabilityBoundingSet=CAP_B CAP_C then `CAP_A`, `CAP_B`, and `CAP_C` are set. If the second line is prefixed with `~`, e.g., CapabilityBoundingSet=CAP_A CAP_B CapabilityBoundingSet=~CAP_B CAP_C then, only `CAP_A` is set. `AmbientCapabilities=` Controls which capabilities to include in the ambient capability set for the executed process. Takes a whitespace-separated list of capability names, e.g. `CAP_SYS_ADMIN`, `CAP_DAC_OVERRIDE`, `CAP_SYS_PTRACE`. This option may appear more than once, in which case the ambient capability sets are merged (see the above examples in `CapabilityBoundingSet=`). If the list of capabilities is prefixed with `~`, all but the listed capabilities will be included, the effect of the assignment inverted. If the empty string is assigned to this option, the ambient capability set is reset to the empty capability set, and all prior settings have no effect. If set to `~` (without any further argument), the ambient capability set is reset to the full set of available capabilities, also undoing any previous settings. Note that adding capabilities to the ambient capability set adds them to the process's inherited capability set. Ambient capability sets are useful if you want to execute a process as a non-privileged user but still want to give it some capabilities. Note that, in this case, option `keep-caps` is automatically added to `SecureBits=` to retain the capabilities over the user change. `AmbientCapabilities=` does not affect commands prefixed with `+`. # Security `NoNewPrivileges=` Takes a boolean argument. If true, ensures that the service process and all its children can never gain new privileges through `execve()` (e.g. via setuid or setgid bits, or filesystem capabilities). This is the simplest and most effective way to ensure that a process and its children can never elevate privileges again. Defaults to false. In case the service will be run in a new mount namespace anyway and SELinux is disabled, all file systems are mounted with `MS_NOSUID` flag. Also see [No New Privileges Flag](https://docs.kernel.org/userspace-api/no_new_privs.html). Note that this setting only has an effect on the unit's processes themselves (or any processes directly or indirectly forked off them). It has no effect on processes potentially invoked on request of them through tools such as `at(1)`, `crontab(1)`, `systemd-run(1)`, or arbitrary IPC services. `SecureBits=` Controls the secure bits set for the executed process. Takes a space-separated combination of options from the following list: `keep-caps`, `keep-caps-locked`, `no-setuid-fixup`, `no-setuid-fixup-locked`, `noroot`, `noroot-locked`, `no-cap-ambient-raise`, `no-cap-ambient-raise-locked`, `exec-restrict-file`, `exec-restrict-file-locked`, `exec-deny-interactive`, and `exec-deny-interactive-locked`. This option may appear more than once, in which case the secure bits are ORed. If the empty string is assigned to this option, the bits are reset to 0. This does not affect commands prefixed with `+`. Bits set for the service manager itself, see `SecureBits=` in `systemd-system.conf(5)`, are inherited and cannot be cleared here, the listed bits are added to them. See `capabilities(7)` and [Executability check](https://docs.kernel.org/userspace-api/check_exec.html) for details. # Mandatory Access Control `SELinuxContext=` Set the SELinux security context of the executed process. If set, this will override the automated domain transition. However, the policy still needs to authorize the transition. This directive is ignored if SELinux is disabled. If prefixed by `-`, failing to set the SELinux security context will be ignored, but it is still possible that the subsequent `execve()` may fail if the policy does not allow the transition for the non-overridden context. This does not affect commands prefixed with `+`. See `setexeccon(3)` for details. `AppArmorProfile=` Takes a profile name as argument. The process executed by the unit will switch to this profile when started. Profiles must already be loaded in the kernel, or the unit will fail. If prefixed by `-`, all errors will be ignored. This setting has no effect if AppArmor is not enabled. This setting does not affect commands prefixed with `+`. `SmackProcessLabel=` Takes a `SMACK64` security label as argument. The process executed by the unit will be started under this label and SMACK will decide whether the process is allowed to run or not, based on it. The process will continue to run under the label specified here unless the executable has its own `SMACK64EXEC` label, in which case the process will transition to run under that label. When not specified, the label that systemd is running under is used. This directive is ignored if SMACK is disabled. The value may be prefixed by `-`, in which case all errors will be ignored. An empty value may be specified to unset previous assignments. This does not affect commands prefixed with `+`. # Process Properties `LimitCPU=`; `LimitFSIZE=`; `LimitDATA=`; `LimitSTACK=`; `LimitCORE=`; `LimitRSS=`; `LimitNOFILE=`; `LimitAS=`; `LimitNPROC=`; `LimitMEMLOCK=`; `LimitLOCKS=`; `LimitSIGPENDING=`; `LimitMSGQUEUE=`; `LimitNICE=`; `LimitRTPRIO=`; `LimitRTTIME=` Set soft and hard limits on various resources for executed processes. See `setrlimit(2)` for details on the process resource limit concept. Process resource limits may be specified in two formats: either as single value to set a specific soft and hard limit to the same value, or as colon-separated pair `soft:hard` to set both limits individually (e.g. `LimitAS=4G:16G`). Use the string `infinity` to configure no limit on a specific resource. The multiplicative suffixes K, M, G, T, P and E (to the base 1024) may be used for resource limits measured in bytes (e.g. `LimitAS=16G`). For the limits referring to time values, the usual time units ms, s, min, h and so on may be used (see `systemd.time(7)` for details). Note that if no time unit is specified for `LimitCPU=` the default unit of seconds is implied, while for `LimitRTTIME=` the default unit of microseconds is implied. Also, note that the effective granularity of the limits might influence their enforcement. For example, time limits specified for `LimitCPU=` will be rounded up implicitly to multiples of 1s. For `LimitNICE=` the value may be specified in two syntaxes: if prefixed with `+` or `-`, the value is understood as regular Linux nice value in the range -20…19. If not prefixed like this the value is understood as raw resource limit parameter in the range 0…40 (with 0 being equivalent to 1). Note that most process resource limits configured with these options are per-process, and processes may fork in order to acquire a new set of resources that are accounted independently of the original process, and may thus escape limits set. Also note that `LimitRSS=` is not implemented on Linux, and setting it has no effect. Often it is advisable to prefer the resource controls listed in `systemd.resource-control(5)` over these per-process limits, as they apply to services as a whole, may be altered dynamically at runtime, and are generally more expressive. For example, `MemoryMax=` is a more powerful (and working) replacement for `LimitRSS=`. Note that `LimitNPROC=` will limit the number of processes from one (real) UID and not the number of processes started (forked) by the service. Therefore the limit is cumulative for all processes running under the same UID. Please also note that the `LimitNPROC=` will not be enforced if the service is running as root (and not dropping privileges). Due to these limitations, `TasksMax=` (see `systemd.resource-control(5)`) is typically a better choice than `LimitNPROC=`. These settings, including the defaults described below, do not affect commands prefixed with `+`. Such commands inherit the resource limits of the service manager itself, which may be different. Resource limits not configured explicitly for a unit default to the value configured in the various `DefaultLimitCPU=`, `DefaultLimitFSIZE=`, … options available in `systemd-system.conf(5)`, and – if not configured there – the kernel or per-user defaults, as defined by the OS (the latter only for user services, see below). For system units these resource limits may be chosen freely. When these settings are configured in a user service (i.e. a service run by the per-user instance of the service manager) they cannot be used to raise the limits above those set for the user manager itself when it was first invoked, as the user's service manager generally lacks the privileges to do so. In user context these configuration options are hence only useful to lower the limits passed in or to raise the soft limit to the maximum of the hard limit as configured for the user. To raise the user's limits further, the available configuration mechanisms differ between operating systems, but typically require privileges. In most cases it is possible to configure higher per-user resource limits via PAM or by setting limits on the system service encapsulating the user's service manager, i.e. the user's instance of `user@.service`. After making such changes, make sure to restart the user's service manager. | Directive | `ulimit` equivalent | Unit | Notes | |----|----|----|----| | LimitCPU= | ulimit -t | Seconds | \- | | LimitFSIZE= | ulimit -f | Bytes | \- | | LimitDATA= | ulimit -d | Bytes | Do not use. This limits the allowed address range, not memory use! Defaults to unlimited and should not be lowered. To limit memory use, see `MemoryMax=` in `systemd.resource-control(5)`. | | LimitSTACK= | ulimit -s | Bytes | \- | | LimitCORE= | ulimit -c | Bytes | \- | | LimitRSS= | ulimit -m | Bytes | Do not use. No effect on Linux. | | LimitNOFILE= | ulimit -n | Number of File Descriptors | Do not use. Be careful when raising the soft limit above 1024, since `select(2)` cannot function with file descriptors above 1023 on Linux. Nowadays, the hard limit defaults to 524288, a very high value compared to historical defaults. Typically applications should increase their soft limit to the hard limit on their own, if they are OK with working with file descriptors above 1023, i.e. do not use `select(2)`. Note that file descriptors are nowadays accounted like any other form of memory, thus there should not be any need to lower the hard limit. Use `MemoryMax=` to control overall service memory use, including file descriptor memory. | | LimitAS= | ulimit -v | Bytes | Do not use. This limits the allowed address range, not memory use! Defaults to unlimited and should not be lowered. To limit memory use, see `MemoryMax=` in `systemd.resource-control(5)`. | | LimitNPROC= | ulimit -u | Number of Processes | This limit is enforced based on the number of processes belonging to the user. Typically it is better to track processes per service, i.e. use `TasksMax=`, see `systemd.resource-control(5)`. | | LimitMEMLOCK= | ulimit -l | Bytes | \- | | LimitLOCKS= | ulimit -x | Number of Locks | \- | | LimitSIGPENDING= | ulimit -i | Number of Queued Signals | \- | | LimitMSGQUEUE= | ulimit -q | Bytes | \- | | LimitNICE= | ulimit -e | Nice Level | \- | | LimitRTPRIO= | ulimit -r | Realtime Priority | \- | | LimitRTTIME= | ulimit -R | Microseconds | \- | Resource limit directives, their equivalent `ulimit` shell commands and the unit used `UMask=` Controls the file mode creation mask. Takes an access mode in octal notation. See `umask(2)` for details. Defaults to 0022 for system units. For user units the default value is inherited from the per-user service manager (whose default is in turn inherited from the system service manager, and thus typically also is 0022 — unless overridden by a PAM module). In order to change the per-user mask for all user services, consider setting the `UMask=` setting of the user's `user@.service` system service instance. The per-user umask may also be set via the `umask` field of a user's [JSON User Record](https://systemd.io/USER_RECORD) (for users managed by `systemd-homed.service(8)` this field may be controlled via `homectl --umask=`). It may also be set via a PAM module, such as `pam_umask(8)`. `CoredumpFilter=` Controls which types of memory mappings will be saved if the process dumps core (using the `/proc/pid/coredump_filter` file). Takes a whitespace-separated combination of mapping type names or numbers (with the default base 16). Mapping type names are `private-anonymous`, `shared-anonymous`, `private-file-backed`, `shared-file-backed`, `elf-headers`, `private-huge`, `shared-huge`, `private-dax`, `shared-dax`, and the special values `all` (all types) and `default` (the kernel default of `private-anonymous shared-anonymous elf-headers private-huge`). See `core(5)` for the meaning of the mapping types. When specified multiple times, all specified masks are ORed. When not set, or if the empty value is assigned, the inherited value is not changed.
Add DAX pages to the dump filter
CoredumpFilter=default private-dax shared-dax
`KeyringMode=` Controls how the kernel session keyring is set up for the service (see `session-keyring(7)` for details on the session keyring). Takes one of `inherit`, `private`, `shared`. If set to `inherit` no special keyring setup is done, and the kernel's default behaviour is applied. If `private` is used a new session keyring is allocated when a service process is invoked, and it is not linked up with any user keyring. This is the recommended setting for system services, as this ensures that multiple services running under the same system user ID (in particular the root user) do not share their key material among each other. If `shared` is used a new session keyring is allocated as for `private`, but the user keyring of the user configured with `User=` is linked into it, so that keys assigned to the user may be requested by the unit's processes. In this mode multiple units running processes under the same user ID may share key material. Unless `inherit` is selected the unique invocation ID for the unit (see below) is added as a protected key by the name `invocation_id` to the newly created session keyring. Defaults to `private` for services of the system service manager and to `inherit` for non-service units and for services of the user service manager. `OOMScoreAdjust=` Sets the adjustment value for the Linux kernel's Out-Of-Memory (OOM) killer score for executed processes. Takes an integer between -1000 (to disable OOM killing of processes of this unit) and 1000 (to make killing of processes of this unit under memory pressure very likely). See [The /proc Filesystem](https://docs.kernel.org/filesystems/proc.html) for details. If not specified, defaults to the OOM score adjustment level of the service manager itself, which is normally at 0. Use the `OOMPolicy=` setting of service units to configure how the service manager shall react to the kernel OOM killer or `systemd-oomd` terminating a process of the service. See `systemd.service(5)` for details. `TimerSlackNSec=` Sets the timer slack in nanoseconds for the executed processes. The timer slack controls the accuracy of wake-ups triggered by timers. See `prctl(2)` for more information. Note that in contrast to most other time span definitions this parameter takes an integer value in nano-seconds if no unit is specified. The usual time units are understood too. `Personality=` Controls which kernel architecture `uname(2)` shall report, when invoked by unit processes. Takes one of the architecture identifiers `arm64`, `arm64-be`, `arm`, `arm-be`, `x86`, `x86-64`, `ppc`, `ppc-le`, `ppc64`, `ppc64-le`, `s390` or `s390x`. Which personality architectures are supported depends on the kernel's native architecture. Usually the 64-bit versions of the various system architectures support their immediate 32-bit personality architecture counterpart, but no others. For example, `x86-64` systems support the `x86-64` and `x86` personalities but no others. The personality feature is useful when running 32-bit services on a 64-bit host system. If not specified, the personality is left unmodified and thus reflects the personality of the host system's kernel. This option is not useful on architectures for which only one native word width was ever available, such as `m68k` (32-bit only) or `alpha` (64-bit only). `IgnoreSIGPIPE=` Takes a boolean argument. If true, `SIGPIPE` is ignored in the executed process. Defaults to true since `SIGPIPE` is generally only useful in shell pipelines. # Scheduling `Nice=` Sets the default nice level (scheduling priority) for executed processes. Takes an integer between -20 (highest priority) and 19 (lowest priority). In case of resource contention, smaller values mean more resources will be made available to the unit's processes, larger values mean less resources will be made available. See `setpriority(2)` for details. `CPUSchedulingPolicy=` Sets the CPU scheduling policy for executed processes. Takes one of `other`, `batch`, `idle`, `fifo`, `rr` or `ext`. See `sched_setscheduler(2)` for details. `CPUSchedulingPriority=` Sets the CPU scheduling priority for executed processes. The available priority range depends on the selected CPU scheduling policy (see above). For real-time scheduling policies an integer between 1 (lowest priority) and 99 (highest priority) can be used. In case of CPU resource contention, smaller values mean less CPU time is made available to the service, larger values mean more. See `sched_setscheduler(2)` for details. `CPUSchedulingResetOnFork=` Takes a boolean argument. If true, elevated CPU scheduling priorities and policies will be reset when the executed processes call `fork(2)`, and can hence not leak into child processes. See `sched_setscheduler(2)` for details. Defaults to false. `CPUAffinity=` Controls the CPU affinity of the executed processes. Takes a list of CPU indices or ranges separated by either whitespace or commas. Alternatively, takes a special "numa" value in which case systemd automatically derives allowed CPU range based on the value of `NUMAMask=` option. CPU ranges are specified by the lower and upper CPU indices separated by a dash. This option may be specified more than once, in which case the specified CPU affinity masks are merged. If the empty string is assigned, the mask is reset, all assignments prior to this will have no effect. See `sched_setaffinity(2)` for details. `NUMAPolicy=` Controls the NUMA memory policy of the executed processes. Takes a policy type, one of: `default`, `preferred`, `bind`, `interleave`, `local`, `preferred-many` (requires Linux 5.15 or newer) and `weighted-interleave` (requires Linux 6.9 or newer, weights are configured via `/sys/kernel/mm/mempolicy/weighted_interleave/`). A list of NUMA nodes that should be associated with the policy must be specified in `NUMAMask=`. For more details on each policy please see, `set_mempolicy(2)`. For overall overview of NUMA support in Linux see, `numa(7)`. If the kernel does not support the requested policy, a warning is logged and the setting is ignored. `NUMAMask=` Controls the NUMA node list which will be applied alongside with selected NUMA policy. Takes a list of NUMA nodes and has the same syntax as a list of CPUs for `CPUAffinity=` option or special "all" value which will include all available NUMA nodes in the mask. Note that the list of NUMA nodes is not required for `default` and `local` policies and for `preferred` policy we expect a single NUMA node. `IOSchedulingClass=` Sets the I/O scheduling class for executed processes. Takes one of the strings `realtime`, `best-effort` or `idle`. The kernel's default scheduling class is `best-effort` at a priority of 4. If the empty string is assigned to this option, all prior assignments to both `IOSchedulingClass=` and `IOSchedulingPriority=` have no effect. See `ioprio_set(2)` for details. `IOSchedulingPriority=` Sets the I/O scheduling priority for executed processes. Takes an integer between 0 (highest priority) and 7 (lowest priority). In case of I/O contention, smaller values mean more I/O bandwidth is made available to the unit's processes, larger values mean less bandwidth. The available priorities depend on the selected I/O scheduling class (see above). If the empty string is assigned to this option, all prior assignments to both `IOSchedulingClass=` and `IOSchedulingPriority=` have no effect. For the kernel's default scheduling class (`best-effort`) this defaults to 4. See `ioprio_set(2)` for details. # Sandboxing The following sandboxing options are an effective way to limit the exposure of the system towards the unit's processes. It is recommended to turn on as many of these options for each unit as is possible without negatively affecting the process' ability to operate. Note that many of these sandboxing features are gracefully turned off on systems where the underlying security mechanism is not available. For example, `ProtectSystem=` has no effect if the kernel is built without file system namespacing or if the service manager runs in a container manager that makes file system namespacing unavailable to its payload. Similarly, `RestrictRealtime=` has no effect on systems that lack support for SECCOMP system call filtering, or in containers where support for this is turned off. Also note that some sandboxing functionality is generally not available in user services (i.e. services run by the per-user service manager). Specifically, the various settings requiring file system namespacing support (such as `ProtectSystem=`) are not available, as the underlying kernel functionality is only accessible to privileged processes. However, most namespacing settings, that will not work on their own in user services, will work when used in conjunction with `PrivateUsers=``true`. Note that the various options that turn directories read-only (such as `ProtectSystem=`, `ReadOnlyPaths=`, …) do not affect the ability for programs to connect to and communicate with `AF_UNIX` sockets in these directories. These options cannot be used to lock down access to IPC services hence. `ProtectSystem=` Takes a boolean argument or the special values `full` or `strict`. If true, mounts the `/usr/` and the boot loader directories (`/boot` and `/efi`) read-only for processes invoked by this unit. If set to `full`, the `/etc/` directory is mounted read-only, too. If set to `strict` the entire file system hierarchy is mounted read-only, except for the API file system subtrees `/dev/`, `/proc/` and `/sys/` (protect these directories using `PrivateDevices=`, `ProtectKernelTunables=`, `ProtectControlGroups=`). This setting ensures that any modification of the vendor-supplied operating system (and optionally its configuration, and local mounts) is prohibited for the service. It is recommended to enable this setting for all long-running services, unless they are involved with system updates or need to modify the operating system in other ways. If this option is used, `ReadWritePaths=` may be used to exclude specific directories from being made read-only. Similar, `StateDirectory=`, `LogsDirectory=`, … and related directory settings (see below) also exclude the specific directories from the effect of `ProtectSystem=`. This setting is implied if `DynamicUser=` is set. This setting cannot ensure protection in all cases. In general it has the same limitations as `ReadOnlyPaths=`, see below. Defaults to off. Note that if `ProtectSystem=` is set to `strict` and `PrivateTmp=` is enabled, then `/tmp/` and `/var/tmp/` will be writable. `ProtectHome=` Takes a boolean argument or the special values `read-only` or `tmpfs`. If true, the directories `/home/`, `/root`, and `/run/user` are made inaccessible and empty for processes invoked by this unit. If set to `read-only`, the three directories are made read-only instead. If set to `tmpfs`, temporary file systems are mounted on the three directories in read-only mode. The value `tmpfs` is useful to hide home directories not relevant to the processes invoked by the unit, while still allowing necessary directories to be made visible when listed in `BindPaths=` or `BindReadOnlyPaths=`. Setting this to `yes` is mostly equivalent to setting the three directories in `InaccessiblePaths=`. Similarly, `read-only` is mostly equivalent to `ReadOnlyPaths=`, and `tmpfs` is mostly equivalent to `TemporaryFileSystem=` with `:ro`. It is recommended to enable this setting for all long-running services (in particular network-facing ones), to ensure they cannot get access to private user data, unless the services actually require access to the user's private data. This setting is implied if `DynamicUser=` is set. This setting cannot ensure protection in all cases. In general it has the same limitations as `ReadOnlyPaths=`, see below. Note that this setting provides no protection if home directories are placed at a non-standard location, i.e. outside of the hierarchies listed above. `RuntimeDirectory=`; `StateDirectory=`; `CacheDirectory=`; `LogsDirectory=`; `ConfigurationDirectory=` These options take a whitespace-separated list of directory names. The specified directory names must be relative, and may not include `..`. If set, when the unit is started, one or more directories by the specified names will be created (including their parents) below the locations defined in the following table. Also, the corresponding environment variable will be defined with the full paths of the directories. If multiple directories are set, then in the environment variable the paths are concatenated with colon (`:`). If `DynamicUser=` is used, and if the kernel version supports [id-mapped mounts](https://lwn.net/Articles/896255/), the specified directories will be owned by "nobody" in the host namespace and will be mapped to (and will be owned by) the service's UID/GID in its own namespace. For backward compatibility, existing directories created without id-mapped mounts will be kept untouched. | Directory | Below path for system units | Below path for user units | Environment variable set | |----|----|----|----| | `RuntimeDirectory=` | `/run/` | `$XDG_RUNTIME_DIR` | `$RUNTIME_DIRECTORY` | | `StateDirectory=` | `/var/lib/` | `$XDG_STATE_HOME` | `$STATE_DIRECTORY` | | `CacheDirectory=` | `/var/cache/` | `$XDG_CACHE_HOME` | `$CACHE_DIRECTORY` | | `LogsDirectory=` | `/var/log/` | `$XDG_STATE_HOME``/log/` | `$LOGS_DIRECTORY` | | `ConfigurationDirectory=` | `/etc/` | `$XDG_CONFIG_HOME` | `$CONFIGURATION_DIRECTORY` | Automatic directory creation and environment variables In case of `RuntimeDirectory=` the innermost subdirectories are removed when the unit is stopped. It is possible to preserve the specified directories in this case if `RuntimeDirectoryPreserve=` is configured to `restart` or `yes` (see below). The directories specified with `StateDirectory=`, `CacheDirectory=`, `LogsDirectory=`, `ConfigurationDirectory=` are not removed when the unit is stopped. Except in case of `ConfigurationDirectory=`, the innermost specified directories will be owned by the user and group specified in `User=` and `Group=`. If the specified directories already exist and their owning user or group do not match the configured ones, all files and directories below the specified directories as well as the directories themselves will have their file ownership recursively changed to match what is configured. As an optimization, if the specified directories are already owned by the right user and group, files and directories below of them are left as-is, even if they do not match what is requested. The innermost specified directories will have their access mode adjusted to the what is specified in `RuntimeDirectoryMode=`, `StateDirectoryMode=`, `CacheDirectoryMode=`, `LogsDirectoryMode=` and `ConfigurationDirectoryMode=`. These options imply `BindPaths=` for the specified paths. When combined with `RootDirectory=` or `RootImage=` these paths always reside on the host and are mounted from there into the unit's file system namespace. If `DynamicUser=` is used, the logic for `CacheDirectory=`, `LogsDirectory=` and `StateDirectory=` is slightly altered: the directories are created below `/var/cache/private`, `/var/log/private` and `/var/lib/private`, respectively, which are host directories made inaccessible to unprivileged users, which ensures that access to these directories cannot be gained through dynamic user ID recycling. Symbolic links are created to hide this difference in behaviour. Both from perspective of the host and from inside the unit, the relevant directories hence always appear directly below `/var/cache`, `/var/log` and `/var/lib`. Use `RuntimeDirectory=` to manage one or more runtime directories for the unit and bind their lifetime to the daemon runtime. This is particularly useful for unprivileged daemons that cannot create runtime directories in `/run/` due to lack of privileges, and to make sure the runtime directory is cleaned up automatically after use. For runtime directories that require more complex or different configuration or lifetime guarantees, please consider using `tmpfiles.d(5)`. `RuntimeDirectory=`, `StateDirectory=`, `CacheDirectory=` and `LogsDirectory=` optionally support two more parameters, separated by `:`. The second parameter will be interpreted as a destination path that will be created as a symlink to the directory. The symlinks will be created after any `BindPaths=` or `TemporaryFileSystem=` options have been set up, to make ephemeral symlinking possible. The same source can have multiple symlinks, by using the same first parameter, but a different second parameter. The third parameter is a flags field, and since v257 can take a value of `ro` to make the directory read only for the service. This is also supported for `ConfigurationDirectory=`. If multiple symlinks are set up, the directory will be read only if at least one is configured to be read only. To pass a flag without a destination symlink, the second parameter can be empty, for example: ConfigurationDirectory=foo::ro Because `:` separates the parameters, a directory name that contains a literal colon must have it escaped as `\:`. Note that when these settings are instead passed over D-Bus to create a transient unit, for example with `systemd-run --property=`, the value is unescaped once more by the client, so a literal colon requires `\\:` in the value received by the client after shell quoting. For example: systemd-run --property='ConfigurationDirectory=foo\\:bar' /usr/bin/true The directories defined by these options are always created under the standard paths used by systemd (`/var/`, `/run/`, `/etc/`, …). If the service needs directories in a different location, a different mechanism has to be used to create them. `tmpfiles.d(5)` provides functionality that overlaps with these options. Using these options is recommended, because the lifetime of the directories is tied directly to the lifetime of the unit, and it is not necessary to ensure that the `tmpfiles.d` configuration is executed before the unit is started. To remove any of the directories created by these settings, use the `systemctl clean …` command on the relevant units, see `systemctl(1)` for details. Example: if a system service unit has the following, RuntimeDirectory=foo/bar baz the service manager creates `/run/foo` (if it does not exist), `/run/foo/bar`, and `/run/baz`. The directories `/run/foo/bar` and `/run/baz` except `/run/foo` are owned by the user and group specified in `User=` and `Group=`, and removed when the service is stopped. Example: if a system service unit has the following, RuntimeDirectory=foo/bar StateDirectory=aaa/bbb ccc then the environment variable `RUNTIME_DIRECTORY` is set with `/run/foo/bar`, and `STATE_DIRECTORY` is set with `/var/lib/aaa/bbb:/var/lib/ccc`. Example: if a system service unit has the following, RuntimeDirectory=foo:bar foo:baz the service manager creates `/run/foo` (if it does not exist), and `/run/bar` plus `/run/baz` as symlinks to `/run/foo`. `RuntimeDirectoryMode=`; `StateDirectoryMode=`; `CacheDirectoryMode=`; `LogsDirectoryMode=`; `ConfigurationDirectoryMode=` Specifies the access mode of the directories specified in `RuntimeDirectory=`, `StateDirectory=`, `CacheDirectory=`, `LogsDirectory=`, or `ConfigurationDirectory=`, respectively, as an octal number. Defaults to `0755`. See "Permissions" in `path_resolution(7)` for a discussion of the meaning of permission bits. `StateDirectoryQuota=`; `CacheDirectoryQuota=`; `LogsDirectoryQuota=` Specifies the storage limits for the directories specified in `StateDirectory=`, `CacheDirectory=`, or `LogsDirectory=` respectively. The storage quota is defined in terms of disk blocks and inodes, as per [quotactl](https://man7.org/linux/man-pages/man2/quotactl.2.html). Takes an absolute size limit in bytes. If the value is suffixed with K, M, G or T, the specified size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If an absolute size limit is specified, only the block quota is set (rounded up to the nearest block). Alternatively, a percentage value may be specified, which applies the same percent quota to both blocks and inodes. Defaults to `off`, in which case no storage limits will be set. Only hard limits are set, not soft limits. If the underlying filesystem for the specified directories does not support project quotas, the specified storage limits will not be set. In addition to enabling per-unit quotas with these settings, it is necessary to enable `prjquota` on the file system level as well (i.e. `tune2fs -Q prjquota`). Quotas must also be turned on with [quotaon.](https://linux.die.net/man/8/quotaon) `StateDirectoryAccounting=`; `CacheDirectoryAccounting=`; `LogsDirectoryAccounting=` Takes a boolean argument. If true, a project ID is assigned to the directories specified in `StateDirectory=`, `CacheDirectory=`, or `LogsDirectory=` respectively, which is used for tracking disk usage when disk quotas are turned on (see [repquota](https://man7.org/linux/man-pages/man8/repquota.8.html)). Defaults to false. To set and enforce disk quotas, `StateDirectoryQuota=`, `CacheDirectoryQuota=`, or `LogsDirectoryQuota=` must be specified. `RuntimeDirectoryPreserve=` Takes a boolean argument or `restart`. If set to `no` (the default), the directories specified in `RuntimeDirectory=` are always removed when the service stops. If set to `restart` the directories are preserved when the service is both automatically and manually restarted. Here, the automatic restart means the operation specified in `Restart=`, and manual restart means the one triggered by `systemctl restart foo.service`. If set to `yes`, then the directories are not removed when the service is stopped. Note that since the runtime directory `/run/` is a mount point of `tmpfs`, then for system services the directories specified in `RuntimeDirectory=` are removed when the system is rebooted. If `DynamicUser=` is used together with `RuntimeDirectoryPreserve=` set to values other than `no`, the logic is slightly altered: the `RuntimeDirectory=` directories are created below `/run/private/`, which is a host directory made inaccessible to unprivileged users, which ensures that access to these directories cannot be gained through dynamic user ID recycling. Symbolic links are created to hide this difference in behaviour. Both from the perspective of the host and from inside the unit, the relevant directories hence always appear directly below `/run/`. `TimeoutCleanSec=` Configures a timeout on the clean-up operation requested through `systemctl clean …`, see `systemctl(1)` for details. Takes the usual time values and defaults to `infinity`, i.e. by default no timeout is applied. If a timeout is configured the clean operation will be aborted forcibly when the timeout is reached, potentially leaving resources on disk. `ReadWritePaths=`; `ReadOnlyPaths=`; `InaccessiblePaths=`; `ExecPaths=`; `NoExecPaths=` Sets up a new file system namespace for executed processes. These options may be used to limit access a process has to the file system. Each setting takes a space-separated list of paths relative to the host's root directory (i.e. the system running the service manager). Note that if paths contain symlinks, they are resolved relative to the root directory set with `RootDirectory=`/`RootImage=`. Paths listed in `ReadWritePaths=` are accessible from within the namespace with the same access modes as from outside of it. Paths listed in `ReadOnlyPaths=` are accessible for reading only, writing will be refused even if the usual file access controls would permit this. Nest `ReadWritePaths=` inside of `ReadOnlyPaths=` in order to provide writable subdirectories within read-only directories. Use `ReadWritePaths=` in order to allow-list specific paths for write access if `ProtectSystem=strict` is used. Note that `ReadWritePaths=` cannot be used to gain write access to a file system whose superblock is mounted read-only. On Linux, for each mount point write access is granted only if the mount point itself *and* the file system superblock backing it are not marked read-only. `ReadWritePaths=` only controls the former, not the latter, hence a read-only file system superblock remains protected. Paths listed in `InaccessiblePaths=` will be made inaccessible for processes inside the namespace along with everything below them in the file system hierarchy. This may be more restrictive than desired, because it is not possible to nest `ReadWritePaths=`, `ReadOnlyPaths=`, `BindPaths=`, or `BindReadOnlyPaths=` inside it. For a more flexible option, see `TemporaryFileSystem=`. Content in paths listed in `NoExecPaths=` are not executable even if the usual file access controls would permit this. Nest `ExecPaths=` inside of `NoExecPaths=` in order to provide executable content within non-executable directories. Non-directory paths may be specified as well. These options may be specified more than once, in which case all paths listed will have limited access from within the namespace. If the empty string is assigned to this option, the specific list is reset, and all prior assignments have no effect. Paths in `ReadWritePaths=`, `ReadOnlyPaths=`, `InaccessiblePaths=`, `ExecPaths=` and `NoExecPaths=` may be prefixed with `-`, in which case they will be ignored when they do not exist. If prefixed with `+` the paths are taken relative to the root directory of the unit, as configured with `RootDirectory=`/`RootImage=`, instead of relative to the root directory of the host (see above). When combining `-` and `+` on the same path make sure to specify `-` first, and `+` second. Note that these settings will disconnect propagation of mounts from the unit's processes to the host. This means that this setting may not be used for services which shall be able to install mount points in the main mount namespace. For `ReadWritePaths=` and `ReadOnlyPaths=`, propagation in the other direction is not affected, i.e. mounts created on the host generally appear in the unit processes' namespace, and mounts removed on the host also disappear there too. In particular, note that mount propagation from host to unit will result in unmodified mounts to be created in the unit's namespace, i.e. writable mounts appearing on the host will be writable in the unit's namespace too, even when propagated below a path marked with `ReadOnlyPaths=`! Restricting access with these options hence does not extend to submounts of a directory that are created later on. This means the lock-down offered by that setting is not complete, and does not offer full protection. Note that the effect of these settings may be undone by privileged processes. In order to set up an effective sandboxed environment for a unit it is thus recommended to combine these settings with either `CapabilityBoundingSet=~CAP_SYS_ADMIN` or `SystemCallFilter=~@mount`. Please be extra careful when applying these options to API file systems (a list of them could be found in `MountAPIVPS=`), since they may be required for basic system functionalities. Moreover, `/run/` needs to be writable for setting up mount namespace and propagation. Simple allow-list example using these directives: [Service] ReadOnlyPaths=/ ReadWritePaths=/var /run InaccessiblePaths=-/lost+found NoExecPaths=/ ExecPaths=/usr/sbin/my_daemon /usr/lib /usr/lib64 `TemporaryFileSystem=` Takes a space-separated list of mount points for temporary file systems (tmpfs). If set, a new file system namespace is set up for executed processes, and a temporary file system is mounted on each mount point. This option may be specified more than once, in which case temporary file systems are mounted on all listed mount points. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect. Each mount point may optionally be suffixed with a colon (`:`) and mount options such as `size=10%` or `ro`. By default, each temporary file system is mounted with `nodev,strictatime,mode=0755`. These can be disabled by explicitly specifying the corresponding mount options, e.g., `dev` or `nostrictatime`. This is useful to hide files or directories not relevant to the processes invoked by the unit, while necessary files or directories can be still accessed by combining with `BindPaths=` or `BindReadOnlyPaths=`: Example: if a unit has the following, TemporaryFileSystem=/var:ro BindReadOnlyPaths=/var/lib/systemd then the invoked processes by the unit cannot see any files or directories under `/var/` except for `/var/lib/systemd` or its contents. `PrivateTmp=` Takes a boolean argument, or `disconnected`. If enabled, a new file system namespace will be set up for the executed processes, and `/tmp/` and `/var/tmp/` directories inside it are not shared with processes outside of the namespace, plus all temporary files created by a service in these directories will be removed after the service is stopped. For this setting, the same restrictions regarding mount propagation and privileges apply as for `ReadOnlyPaths=` and related calls, see above. This setting is useful to secure access to temporary files of the process, but makes sharing between processes via `/tmp/` or `/var/tmp/` impossible. If `DynamicUser=` is enabled, `disconnected` is implied. Otherwise, defaults to false. If `true`, the backing storage of the private temporary directories will remain on the host's `/tmp/` and `/var/tmp/` directories. It is possible to run two or more units within the same private `/tmp/` and `/var/tmp/` namespace by using the `JoinsNamespaceOf=` directive, see `systemd.unit(5)` for details. This has the side effect of adding `Wants=` and `After=` dependencies on all mount units necessary to access `/tmp/` and `/var/tmp/` on the host. Moreover, an implicit `After=` ordering on `systemd-tmpfiles-setup.service(8)` is added. If `disconnected`, the directories will be backed by a completely new tmpfs instance, meaning that the storage is fully disconnected from the host namespace. The tmpfs instance does not shared with other units even if the `JoinsNamespaceOf=` directive is used. If `DefaultDependencies=no` is specified, `RequiresMountsFor=/WantsMountsFor=` for `/var/` is not specified, and `RootDirectory=/RootImage=` is not specified, then a new tmpfs is mounted *only* on `/tmp/`, hence the host's `/var/tmp` is still accessible from the unit. In that case, `$TMPDIR` environment variable is set to `/tmp` to suggest the processes in the unit to use `/tmp/`. This automatically adds `WantsMountsFor=/var/` dependency, unless `DefaultDependencies=no` and/or `RootDirectory=/RootImage=` are specified. | Other Settings | tmpfs on /var/tmp/ | \$TMPVAR | implied dependencies | |----|----|----|----| | (none) | yes | (unset) | `WantsMountsFor=/var/` | | `RootDirectory=/RootImage=` | yes | (unset) | (none) | | `DefaultDependency=no`, `RequiresMountsFor=/var/` | yes | (unset) | (none) | | `DefaultDependency=no`, `WantsMountsFor=/var/` | yes | (unset) | (none) | | `DefaultDependency=no` | no | `$TMPDIR=/tmp` | (none) | Summary for `PrivateTmp=disconnected` Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security. `PrivateDevices=` Takes a boolean argument. If true, sets up a new `/dev/` mount for the executed processes and only adds API pseudo devices such as `/dev/null`, `/dev/zero` or `/dev/random` (as well as the pseudo TTY subsystem) to it, but no physical devices such as `/dev/sda`, system memory `/dev/mem`, system ports `/dev/port` and others. This is useful to turn off physical device access by the executed process. Defaults to false. Enabling this option will install a system call filter to block low-level I/O system calls that are grouped in the `@raw-io` set, remove `CAP_MKNOD` and `CAP_SYS_RAWIO` from the capability bounding set for the unit, and set `DevicePolicy=closed` (see `systemd.resource-control(5)` for details). Note that using this setting will disconnect propagation of mounts from the service to the host (propagation in the opposite direction continues to work). This means that this setting may not be used for services which shall be able to install mount points in the main mount namespace. The new `/dev/` will be mounted read-only and 'noexec'. The latter may break old programs which try to set up executable memory by using `mmap(2)` of `/dev/zero` instead of using `MAP_ANON`. For this setting the same restrictions regarding mount propagation and privileges apply as for `ReadOnlyPaths=` and related calls, see above. Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security. When access to some but not all devices must be possible, the `DeviceAllow=` setting might be used instead. See `systemd.resource-control(5)`. `PrivateNetwork=` Takes a boolean argument. If true, sets up a new network namespace for the executed processes and configures only the loopback network device `lo` inside it. No other network devices will be available to the executed process. This is useful to turn off network access by the executed process. Defaults to false. It is possible to run two or more units within the same private network namespace by using the `JoinsNamespaceOf=` directive, see `systemd.unit(5)` for details. Note that this option will disconnect all socket families from the host, including `AF_NETLINK` and `AF_UNIX`. Effectively, for `AF_NETLINK` this means that device configuration events received from `systemd-udevd.service(8)` are not delivered to the unit's processes. And for `AF_UNIX` this has the effect that `AF_UNIX` sockets in the abstract socket namespace of the host will become unavailable to the unit's processes (however, those located in the file system will continue to be accessible). Note that the implementation of this setting might be impossible (for example if network namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security. When this option is enabled, `PrivateMounts=` is implied unless it is explicitly disabled, and `/sys` will be remounted to associate it with the new network namespace. When this option is used on a socket unit any sockets bound on behalf of this unit will be bound within a private network namespace. This may be combined with `JoinsNamespaceOf=` to listen on sockets inside of network namespaces of other services. `UserNamespacePath=` Takes an absolute file system path referring to a Linux user namespace pseudo-file (i.e. a file like `/proc/$PID/ns/user` or a bind mount or symlink to one). When set the invoked processes are added to the user namespace referenced by that path. The path has to point to a valid namespace file at the moment the processes are forked off. If this option is used `PrivateUsers=` has no effect. This option is only available for system services. `NetworkNamespacePath=` Takes an absolute file system path referring to a Linux network namespace pseudo-file (i.e. a file like `/proc/$PID/ns/net` or a bind mount or symlink to one). When set the invoked processes are added to the network namespace referenced by that path. The path has to point to a valid namespace file at the moment the processes are forked off. If this option is used `PrivateNetwork=` has no effect. If this option is used together with `JoinsNamespaceOf=` then it only has an effect if this unit is started before any of the listed units that have `PrivateNetwork=` or `NetworkNamespacePath=` configured, as otherwise the network namespace of those units is reused. When this option is enabled, `PrivateMounts=` is implied unless it is explicitly disabled, and `/sys` will be remounted to associate it with the new network namespace. When this option is used on a socket unit any sockets bound on behalf of this unit will be bound within the specified network namespace. `PrivateIPC=` Takes a boolean argument. If true, sets up a new IPC namespace for the executed processes. Each IPC namespace has its own set of System V IPC identifiers and its own POSIX message queue file system. This is useful to avoid name clash of IPC identifiers. Defaults to false. It is possible to run two or more units within the same private IPC namespace by using the `JoinsNamespaceOf=` directive, see `systemd.unit(5)` for details. Note that IPC namespacing does not have an effect on `AF_UNIX` sockets, which are the most common form of IPC used on Linux. Instead, `AF_UNIX` sockets in the file system are subject to mount namespacing, and those in the abstract namespace are subject to network namespacing. IPC namespacing only has an effect on SysV IPC (which is mostly legacy) as well as POSIX message queues (for which `AF_UNIX`/`SOCK_SEQPACKET` sockets are typically a better replacement). IPC namespacing also has no effect on POSIX shared memory (which is subject to mount namespacing) either. See `ipc_namespaces(7)` for the details. Note that the implementation of this setting might be impossible (for example if IPC namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security. `IPCNamespacePath=` Takes an absolute file system path referring to a Linux IPC namespace pseudo-file (i.e. a file like `/proc/$PID/ns/ipc` or a bind mount or symlink to one). When set the invoked processes are added to the network namespace referenced by that path. The path has to point to a valid namespace file at the moment the processes are forked off. If this option is used `PrivateIPC=` has no effect. If this option is used together with `JoinsNamespaceOf=` then it only has an effect if this unit is started before any of the listed units that have `PrivateIPC=` or `IPCNamespacePath=` configured, as otherwise the network namespace of those units is reused. `MemoryKSM=` Takes a boolean argument. When set, it enables KSM (kernel samepage merging) for the processes. KSM is a memory-saving de-duplication feature. Anonymous memory pages with identical content can be replaced by a single write-protected page. This feature should only be enabled for jobs that share the same security domain. For details, see [Kernel Samepage Merging](https://docs.kernel.org/admin-guide/mm/ksm.html) in the kernel documentation. Note that this functionality might not be available, for example if KSM is disabled in the kernel, or the kernel does not support controlling KSM at the process level through `prctl(2)`. `MemoryTHP=` Transparent Hugepages (THPs) is a Linux kernel feature that manages memory using larger pages (2MB on x86, compared to the default 4KB). The main goal is to improve memory management efficiency and system performance, especially for memory-intensive applications. However, it can cause drawbacks in some scenarios, such as memory regression and latency spikes. THP policy is governed for the entire system via `/sys/kernel/mm/transparent_hugepage/enabled`. However, it can be overridden for individual workloads via `prctl(2)`. `MemoryTHP=` may be used to disable THPs at process invocation time to stop providing THPs for workloads where the drawbacks outweigh the advantages. When `MemoryTHP=` is set to `inherit` or not set at all, systemd inherits THP settings from the process that starts it and no `prctl(2)` `PR_SET_THP_DISABLE` call is made. When set to `disable`, `MemoryTHP=` disables THPs completely for the process, irrespecitive of global THP controls. When set to `madvise`, `MemoryTHP=` disables THPs for the process except when specifically requested via `madvise(2)` by the process with `MADV_HUGEPAGE` or `MADV_COLLAPSE`. When set to `system`, `MemoryTHP=` resets the THP policy to system wide policy. This can be used when the process that starts systemd has already disabled THPs via `PR_SET_THP_DISABLE`, and we want to restore the system default THP setting at process invocation time. For details, see [Transparent Hugepage Support](https://docs.kernel.org/admin-guide/mm/transhuge.html) in the kernel documentation. Note that this functionality might not be available, for example if THP is disabled in the kernel, or the kernel does not support controlling THP at the process level through `prctl(2)`. `PrivatePIDs=` Takes a boolean argument. Defaults to false. If enabled, sets up a new PID namespace for the executed processes. Each executed process is now PID 1 - the init process - in the new namespace. `/proc/` is mounted such that only processes in the PID namespace are visible. If `PrivatePIDs=` is set, `MountAPIVFS=yes` is implied. `PrivatePIDs=` is only supported for service units. This setting is not supported with `Type=forking` since the kernel will kill all processes in the PID namespace if the init process terminates. This setting will be ignored if the kernel does not support PID namespaces. Note unprivileged user services (i.e. a service run by the per-user instance of the service manager) will fail with `PrivatePIDs=yes` if `/proc/` is masked (i.e. `/proc/kmsg` is over-mounted with `tmpfs` like `systemd-nspawn(1)` does). This is due to a kernel restriction not allowing unprivileged user namespaces to mount a less restrictive instance of `/proc/`. `PrivateUsers=` Takes a boolean argument or one of `self`, `identity`, `full` or `managed`. Defaults to false. If enabled, sets up a new user namespace for the executed processes and configures a user and group mapping. If set to a true value or `self`, a minimal user and group mapping is configured that maps the `root` user and group as well as the unit's own user and group to themselves and everything else to the `nobody` user and group. This is useful to securely detach the user and group databases used by the unit from the rest of the system, and thus to create an effective sandbox environment. All files, directories, processes, IPC objects and other resources owned by users/groups not equaling `root` or the unit's own will stay visible from within the unit but appear owned by the `nobody` user and group. If the parameter is `identity`, user namespacing is set up with an identity mapping for the first 65536 UIDs/GIDs. Any UIDs/GIDs above 65536 will be mapped to the `nobody` user and group, respectively. While this does not provide UID/GID isolation, since all UIDs/GIDs are chosen identically it does provide process capability isolation, and hence is often a good choice if proper user namespacing with distinct UID maps is not appropriate. If the parameter is `full`, user namespacing is set up with an identity mapping for all UIDs/GIDs. In addition, for system services, `full` allows the unit to call `setgroups()` system calls (by setting `/proc/pid/setgroups` to `allow`). Similar to `identity`, this does not provide UID/GID isolation, but it does provide process capability isolation. If this mode is enabled, all unit processes are run without privileges in the host user namespace (regardless of whether the unit's own user/group is `root` or not). Specifically this means that the process will have zero process capabilities on the host's user namespace, but full capabilities within the service's user namespace. Settings such as `CapabilityBoundingSet=` will affect only the latter, and there's no way to acquire additional capabilities in the host's user namespace. If the parameter is `managed` a transient, dynamically allocated range of 65536 UIDs/GIDs is allocated for the unit, and a UID/GID mapping is assigned to the unit's process so the UID/GID 0 from inside the unit maps to the first UID/GID of the allocated mapping. Note that in this mode the UID/GID the service process will run as is different depending if looking from the host side (where it will be a high, dynamically assigned UID) or from inside the unit (where it will be 0). Also note that this mode will enable file system UID mapping for the file systems this service accesses, mapping the "foreign" UID range on disk to the selected dynamic UID range at runtime. When this setting is set up by a per-user instance of the service manager, the mapping of the `root` user and group to itself is omitted (unless the user manager is root). Additionally, in the per-user instance manager case, the user namespace will be set up before most other namespaces. This means that combining `PrivateUsers=``true` with other namespaces will enable use of features not normally supported by the per-user instances of the service manager. This setting is particularly useful in conjunction with `RootDirectory=`/`RootImage=`, as the need to synchronize the user and group databases in the root directory and on the host is reduced, as the only users and groups who need to be matched are `root`, `nobody` and the unit's own user and group. `ProtectHostname=` Takes a boolean argument or `private`. If enabled, sets up a new UTS namespace for the executed processes. If enabled, a hostname can be optionally specified following a colon (e.g. `yes:foo` or `private:host.example.com`), and the hostname is set in the new UTS namespace for the unit. If set to a true value, changing hostname or domainname via `sethostname()` and `setdomainname()` system calls is prevented. If set to `private`, changing hostname or domainname is allowed but only affects the unit's UTS namespace. Defaults to off. Note that the implementation of this setting might be impossible (for example if UTS namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security. Note that when this option is enabled for a service hostname changes no longer propagate from the system into the service, it is hence not suitable for services that need to take notice of system hostname changes dynamically. Note that this option does not prevent changing system hostname via `hostnamectl`. However, `User=` and `Group=` may be used to run as an unprivileged user to disallow changing system hostname. See `SetHostname()` in `org.freedesktop.hostname1(5)` for more details. `ProtectClock=` Takes a boolean argument. If set, writes to the hardware clock or system clock will be denied. Defaults to off. Enabling this option removes `CAP_SYS_TIME` and `CAP_WAKE_ALARM` from the capability bounding set for this unit, installs a system call filter to block calls that can set the clock, and `DeviceAllow=char-rtc r` is implied. Note that the system calls are blocked altogether, the filter does not take into account that some of the calls can be used to read the clock state with some parameter combinations. Effectively, `/dev/rtc0`, `/dev/rtc1`, etc. are made read-only to the service. See `systemd.resource-control(5)` for the details about `DeviceAllow=`. It is recommended to turn this on for most services that do not need modify the clock or check its state. `ProtectKernelTunables=` Takes a boolean argument. If true, kernel variables accessible through `/proc/sys/`, `/sys/`, `/proc/sysrq-trigger`, `/proc/latency_stats`, `/proc/acpi`, `/proc/timer_stats`, `/proc/fs` and `/proc/irq` will be made read-only and `/proc/kallsyms` as well as `/proc/kcore` will be inaccessible to all processes of the unit. Usually, tunable kernel variables should be initialized only at boot-time, for example with the `sysctl.d(5)` mechanism. Few services need to write to these at runtime; it is hence recommended to turn this on for most services. For this setting the same restrictions regarding mount propagation and privileges apply as for `ReadOnlyPaths=` and related calls, see above. Defaults to off. Note that this option does not prevent indirect changes to kernel tunables affected by IPC calls to other processes. However, `InaccessiblePaths=` may be used to make relevant IPC file system objects inaccessible. If `ProtectKernelTunables=` is set, `MountAPIVFS=yes` is implied. `ProtectKernelModules=` Takes a boolean argument. If true, explicit module loading will be denied. This allows module load and unload operations to be turned off on modular kernels. It is recommended to turn this on for most services that do not need special file systems or extra kernel modules to work. Defaults to off. Enabling this option removes `CAP_SYS_MODULE` from the capability bounding set for the unit, and installs a system call filter to block module system calls, also `/usr/lib/modules` is made inaccessible. For this setting the same restrictions regarding mount propagation and privileges apply as for `ReadOnlyPaths=` and related calls, see above. Note that limited automatic module loading due to user configuration or kernel mapping tables might still happen as side effect of requested user operations, both privileged and unprivileged. To disable module auto-load feature please see `sysctl.d(5)` `kernel.modules_disabled` mechanism and `/proc/sys/kernel/modules_disabled` documentation. `ProtectKernelLogs=` Takes a boolean argument. If true, access to the kernel log ring buffer will be denied. It is recommended to turn this on for most services that do not need to read from or write to the kernel log ring buffer. Enabling this option removes `CAP_SYSLOG` from the capability bounding set for this unit, and installs a system call filter to block the `syslog(2)` system call (not to be confused with the libc API `syslog(3)` for userspace logging). The kernel exposes its log buffer to userspace via `/dev/kmsg` and `/proc/kmsg`. If enabled, these are made inaccessible to all the processes in the unit. `ProtectControlGroups=` Takes a boolean argument or the special values `private` or `strict`. If true, the Linux Control Groups (`cgroups(7)`) hierarchies accessible through `/sys/fs/cgroup/` will be made read-only to all processes of the unit. If set to `private`, the unit will run in a cgroup namespace with a private writable mount of `/sys/fs/cgroup/`. If set to `strict`, the unit will run in a cgroup namespace with a private read-only mount of `/sys/fs/cgroup/`. Defaults to off. If `ProtectControlGroups=` is set, `MountAPIVFS=yes` is implied. Note `private` and `strict` are downgraded to false and true respectively unless the system is using the unified control group hierarchy and the kernel supports cgroup namespaces. Except for container managers no services should require write access to the control groups hierarchies; it is hence recommended to set `ProtectControlGroups=` to true or `strict` for most services. For this setting the same restrictions regarding mount propagation and privileges apply as for `ReadOnlyPaths=` and related settings, see above. `RestrictAddressFamilies=` Restricts the set of socket address families accessible to the processes of this unit. Takes `none`, or a comma- or space-separated list of address family names to allow-list, such as `AF_UNIX`, `AF_INET` or `AF_INET6`, see `address_families(7)` for all possible options. The names can be specified with or without the `AF_` prefix. When `none` is specified, then all address families will be denied. When prefixed with `~` the listed address families will be applied as deny list, otherwise as allow list. By default, no restrictions apply, all address families are accessible to processes. If assigned the empty string, any previous address family restriction changes are undone. This setting does not affect commands prefixed with `+`. Use this option to limit exposure of processes to remote access, in particular via exotic and sensitive network protocols, such as `AF_PACKET`. Note that in most cases, the local `AF_UNIX` address family should be included in the configured allow list as it is frequently used for local communication, including for `syslog(2)` logging. Note that this restricts access to the `socket(2)` system call only. Sockets passed into the process by other means (for example, by using socket activation with socket units, see `systemd.socket(5)`) are unaffected. Also, sockets created with `socketpair()` (which creates connected AF_UNIX sockets) or the `io_uring(7)` functions, are not affected. Thus, it is recommended to combined this setting with `SystemCallFilter=@service`, to only allow a limited subset of system calls. Note that this option is limited to some ABIs, in particular x86-64, but currently has no effect on 32-bit x86, s390, s390x, mips, mips-le, ppc, ppc-le, ppc64, or ppc64-le, and is ignored. On systems supporting multiple ABIs (such as x86/x86-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option. Specifically, it is recommended to combine this option with `SystemCallArchitectures=native` or similar. `RestrictFileSystems=` Restricts the set of filesystems processes of this unit can open files on. Takes a comma- or space-separated list of filesystem names. Any filesystem listed is made accessible to the unit's processes, access to filesystem types not listed is prohibited (allow-listing). If the first character of the list is `~`, the effect is inverted: access to the filesystems listed is prohibited (deny-listing). If the empty string is assigned, access to filesystems is not restricted. If you specify both types of this option (i.e. allow-listing and deny-listing), the first encountered will take precedence and will dictate the default action (allow access to the filesystem or deny it). Then the next occurrences of this option will add or delete the listed filesystems from the set of the restricted filesystems, depending on its type and the default action. Example: if a unit has the following, RestrictFileSystems=ext4 tmpfs RestrictFileSystems=ext2 ext4 then access to `ext4`, `tmpfs`, and `ext2` is allowed and access to other filesystems is denied. Example: if a unit has the following, RestrictFileSystems=ext4 tmpfs RestrictFileSystems=~ext4 then only access `tmpfs` is allowed. Example: if a unit has the following, RestrictFileSystems=~ext4 tmpfs RestrictFileSystems=ext4 then only access to `tmpfs` is denied. As the number of possible filesystems is large, predefined sets of filesystems are provided. A set starts with `@` character, followed by name of the set. | Set | Description | |----|----| | @basic-api | Basic filesystem API. | | @auxiliary-api | Auxiliary filesystem API. | | @common-block | Common block device filesystems. | | @historical-block | Historical block device filesystems. | | @network | Well-known network filesystems. | | @privileged-api | Privileged filesystem API. | | @temporary | Temporary filesystems: tmpfs, ramfs. | | @known | All known filesystems defined by the kernel. This list is defined statically in systemd based on a kernel version that was available when this systemd version was released. It will become progressively more out-of-date as the kernel is updated. | Currently predefined filesystem sets Use `systemd-analyze(1)`'s `filesystems` command to retrieve a list of filesystems defined on the local system. Note that this setting might not be supported on some systems (for example if the LSM eBPF hook is not enabled in the underlying kernel or if not using the unified control group hierarchy). In that case this setting has no effect. `RestrictNamespaces=` Restricts access to Linux namespace functionality for the processes of this unit. For details about Linux namespaces, see `namespaces(7)`. Either takes a boolean argument, or a space-separated list of namespace type identifiers. If false (the default), no restrictions on namespace creation and switching are made. If true, access to any kind of namespacing is prohibited. Otherwise, a space-separated list of namespace type identifiers must be specified, consisting of any combination of: `cgroup`, `ipc`, `net`, `mnt`, `pid`, `user`, `uts`, and `time`. Any namespace type listed is made accessible to the unit's processes, access to namespace types not listed is prohibited (allow-listing). By prepending the list with a single tilde character (`~`) the effect may be inverted: only the listed namespace types will be made inaccessible, all unlisted ones are permitted (deny-listing). If the empty string is assigned, the default namespace restrictions are applied, which is equivalent to false. This option may appear more than once, in which case the namespace types are merged by `OR`, or by `AND` if the lines are prefixed with `~` (see examples below). Internally, this setting limits access to the `unshare(2)`, `clone(2)` and `setns(2)` system calls, taking the specified flags parameters into account. Note that — if this option is used — in addition to restricting creation and switching of the specified types of namespaces (or all of them, if true) access to the `setns()` system call with a zero flags parameter is prohibited. This setting is only supported on x86, x86-64, mips, mips-le, mips64, mips64-le, mips64-n32, mips64-le-n32, ppc64, ppc64-le, s390 and s390x, and enforces no restrictions on other architectures. Example: if a unit has the following, RestrictNamespaces=cgroup ipc RestrictNamespaces=cgroup net then `cgroup`, `ipc`, and `net` are set. If the second line is prefixed with `~`, e.g., RestrictNamespaces=cgroup ipc RestrictNamespaces=~cgroup net then, only `ipc` is set. `DelegateNamespaces=` Delegates ownership of the given namespace types to the user namespace of the processes of this unit. For details about Linux namespaces, see `namespaces(7)`. Either takes a boolean argument, or a space-separated list of namespace type identifiers. If false (the default), the unit's processes' user namespace will not have ownership over any namespaces created during setup of the unit's sandboxed environment. If true, ownership of all namespace types (except for user namespaces, where the concept doesn't apply) created during setup of the unit's sandboxed environment is delegated to the unit's processes' user namespace. Otherwise, a space-separated list of namespace type identifiers must be specified, consisting of any combination of: `cgroup`, `ipc`, `net`, `mnt`, `pid`, and `uts`. All namespaces of the listed types will be owned by the unit's processes' user namespace if they are created during setup of the unit's sandboxed environment (allow-listing). By prepending the list with a single tilde character (`~`) the effect may be inverted: all namespaces of types not listed and created during setup of the unit's sandboxed environment will be owned by the unit's processes' user namespace (deny-listing). If the empty string is assigned, the default namespace ownership is applied, which is equivalent to false. This option may appear more than once, in which case the namespace types are merged by `OR`, or by `AND` if the lines are prefixed with `~` (see examples below). Internally, this setting controls the order in which namespaces are unshared by systemd. Namespace types that should be owned by the unit's processes' user namespace will be unshared after unsharing the user namespace. Internally, this setting controls the order in which namespaces are unshared. Delegated namespaces will be unshared after the user namespace is unshared. Other namespaces will be unshared before the user namespace is unshared. Delegating any namespace with `DelegateNamespaces=` implies `PrivateUsers=self` unless `PrivateUsers=` is explicitly enabled already by the unit. Delegating a namespace does not imply that the namespace is unshared, that is done with the namespace specific unit setting such as `PrivateNetwork=` or `PrivateMounts=`. Note that some namespace sandboxing options might entail mount namespace for private API VFS instances, such as `PrivatePIDs=`, `ProtectControlGroups=private/strict`, or `PrivateNetwork=`. If any of the mentioned options are enabled, mount namespace is implicitly delegated. `PrivateBPF=` Takes a boolean argument. If set, mount a private instance of the BPF filesystem on `/sys/fs/bpf/`, effectively hiding the host bpffs which contains information about loaded programs and maps. Otherwise, if `ProtectKernelTunables=` is set, the instance from the host is inherited but mounted read-only. Defaults to false. This can be used together with the bpffs delegate feature to choose what BPF functions are available to the unit's processes. When mounting the BPF filesystem with the fsopen() API, four mount options can be specified to set a list of BPF commands, maps, programs and attachment types that are allowed to be used. Processes needs to get a file descriptor for the bpffs mountpoint and use that to get a token which will enable for that user namespace the BPF functionalities chosen upon bpffs mount. A more detailed explanation of the feature can be found in this [LWN post](https://lwn.net/Articles/947173/). `BPFDelegateCommands=` Accepts a list of BPF commands to allow or `any` to allow everything. Defaults to none. The accepted values are: This will set the `delegate_cmds` bpffs mount option. Requires `PrivateBPF=yes` to be effective, see `PrivateBPF=` more details. `BPFDelegateMaps=` Accepts a list of BPF maps to allow or `any` to allow everything. Defaults to none. The accepted values are: This will set the `delegate_maps` bpffs mount option. Requires `PrivateBPF=yes` to be effective, see `PrivateBPF=` more details. `BPFDelegatePrograms=` Accepts a list of BPF programs to allow or `any` to allow everything. Defaults to none. The accepted values are: This will set the `delegate_progs` bpffs mount option. Requires `PrivateBPF=yes` to be effective, see `PrivateBPF=` more details. `BPFDelegateAttachments=` Accepts a list of BPF attach points to allow or `any` to allow everything. Defaults to none. The accepted values are: This will set the `delegate_attachs` bpffs mount option. Requires `PrivateBPF=yes` to be effective, see `PrivateBPF=` more details. `LockPersonality=` Takes a boolean argument. If set, locks down the `personality(2)` system call so that the kernel execution domain may not be changed from the default or the personality selected with `Personality=` directive. This may be useful to improve security, because odd personality emulations may be poorly tested and source of vulnerabilities. The current personality may still be queried. `MemoryDenyWriteExecute=` Takes a boolean argument. If set, attempts to create memory mappings that are writable and executable at the same time, or to change existing memory mappings to become executable, or mapping shared memory segments as executable, are prohibited. Specifically, a system call filter is added (or preferably, an equivalent kernel check is enabled with `prctl(2)`) that rejects `mmap(2)` system calls with both `PROT_EXEC` and `PROT_WRITE` set, `mprotect(2)` or `pkey_mprotect(2)` system calls with `PROT_EXEC` set and `shmat(2)` system calls with `SHM_EXEC` set. Note that this option is incompatible with programs and libraries that generate program code dynamically at runtime, including JIT execution engines, executable stacks, and code "trampoline" feature of various C compilers. This option improves service security, as it makes harder for software exploits to change running code dynamically. However, the protection can be circumvented, if the service can write to a filesystem, which is not mounted with `noexec` (such as `/dev/shm`), or it can use `memfd_create()`. This can be prevented by making such file systems inaccessible to the service (e.g. `InaccessiblePaths=/dev/shm`) and installing further system call filters (`SystemCallFilter=~memfd_create`). Note that this feature is fully available on x86-64, and partially on x86. Specifically, the `shmat()` protection is not available on x86. Note that on systems supporting multiple ABIs (such as x86/x86-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option. Specifically, it is recommended to combine this option with `SystemCallArchitectures=native` or similar. `RestrictRealtime=` Takes a boolean argument. If set, any attempts to enable realtime scheduling in a process of the unit are refused. This restricts access to realtime task scheduling policies such as `SCHED_FIFO`, `SCHED_RR` or `SCHED_DEADLINE`. See `sched(7)` for details about these scheduling policies. Realtime scheduling policies may be used to monopolize CPU time for longer periods of time, and may hence be used to lock up or otherwise trigger Denial-of-Service situations on the system. It is hence recommended to restrict access to realtime scheduling to the few programs that actually require them. Note that the scheduling policy passed to `sched_setattr(2)` cannot be inspected by the system call filter, hence that system call is refused altogether, including for non-realtime uses. Defaults to off. `RestrictSUIDSGID=` Takes a boolean argument. If set, any attempts to set the set-user-ID (SUID) or set-group-ID (SGID) bits on files or directories will be denied (for details on these bits see `inode(7)`). As the SUID/SGID bits are mechanisms to elevate privileges, and allow users to acquire the identity of other users, it is recommended to restrict creation of SUID/SGID files to the few programs that actually require them. Note that this restricts marking of any type of file system object with these bits, including both regular files and directories (where the SGID is a different meaning than for files, see documentation). This option is implied if `DynamicUser=` is enabled. In other cases, this setting defaults to the value set with `DefaultRestrictSUIDSGID=` in `systemd-system.conf(5)`, which defaults to off. This setting is implemented using seccomp filtering. For system calls where the mode bits are passed directly as arguments, the call is denied only when the SUID or SGID bits are set. For system calls where those bits are passed indirectly and cannot be inspected by the filter, such as `openat2()`, the call is blocked entirely, regardless of the requested mode. `RemoveIPC=` Takes a boolean parameter. If set, all System V and POSIX IPC objects owned by the user and group the processes of this unit are run as are removed when the unit is stopped. This setting only has an effect if at least one of `User=`, `Group=` and `DynamicUser=` are used. It has no effect on IPC objects owned by the root user. Specifically, this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues. If multiple units use the same user or group the IPC objects are removed when the last of these units is stopped. This setting is implied if `DynamicUser=` is set. `PrivateMounts=` Takes a boolean parameter. If set, the processes of this unit will be run in their own private file system (mount) namespace with all mount propagation from the processes towards the host's main file system namespace turned off. This means any file system mount points established or removed by the unit's processes will be private to them and not be visible to the host. However, file system mount points established or removed on the host will be propagated to the unit's processes. See `mount_namespaces(7)` for details on file system namespaces. Defaults to off. When turned on, this executes three operations for each invoked process: a new `CLONE_NEWNS` namespace is created, after which all existing mounts are remounted to `MS_SLAVE` to disable propagation from the unit's processes to the host (but leaving propagation in the opposite direction in effect). Finally, the mounts are remounted again to the propagation mode configured with `MountFlags=`, see below. File system namespaces are set up individually for each process forked off by the service manager. Mounts established in the namespace of the process created by `ExecStartPre=` will hence be cleaned up automatically as soon as that process exits and will not be available to subsequent processes forked off for `ExecStart=` (and similar applies to the various other commands configured for units). Similarly, `JoinsNamespaceOf=` does not permit sharing kernel mount namespaces between units, it only enables sharing of the `/tmp/` and `/var/tmp/` directories. Other file system namespace unit settings — `PrivateTmp=`, `PrivateDevices=`, `ProtectSystem=`, `ProtectHome=`, `ReadOnlyPaths=`, `InaccessiblePaths=`, `ReadWritePaths=`, `BindPaths=`, `BindReadOnlyPaths=`, … — also enable file system namespacing in a fashion equivalent to this option. Hence it is primarily useful to explicitly request this behaviour if none of the other settings are used. `MountFlags=` Takes a mount propagation setting: `shared`, `slave` or `private`, which controls whether file system mount points in the file system namespaces set up for this unit's processes will receive or propagate mounts and unmounts from other file system namespaces. See `mount(2)` for details on mount propagation, and the three propagation flags in particular. This setting only controls the *final* propagation setting in effect on all mount points of the file system namespace created for each process of this unit. Other file system namespacing unit settings (see the discussion in `PrivateMounts=` above) will implicitly disable mount and unmount propagation from the unit's processes towards the host by changing the propagation setting of all mount points in the unit's file system namespace to `slave` first. Setting this option to `shared` does not reestablish propagation in that case. If not set – but file system namespaces are enabled through another file system namespace unit setting – `shared` mount propagation is used, but — as mentioned — as `slave` is applied first, propagation from the unit's processes to the host is still turned off. It is not recommended to use `private` mount propagation for units, as this means temporary mounts (such as removable media) of the host will stay mounted and thus indefinitely busy in forked off processes, as unmount propagation events will not be received by the file system namespace of the unit. Usually, it is best to leave this setting unmodified, and use higher level file system namespacing options instead, in particular `PrivateMounts=`, see above. # System Call Filtering `SystemCallFilter=` Takes a comma- or space-separated list of system call names or system call groups. If this setting is used, system calls executed by the unit processes except for the listed ones will result in the system call being denied (allow-listing). If the first character of the list is `~`, the effect is inverted: only the listed system calls will be denied (deny-listing). This option may be specified more than once, in which case the filter masks are merged. If the empty string is assigned, the filter is reset, all prior assignments will have no effect. Commands prefixed with `+` are not subject to filtering. The `execve()`, `exit()`, `exit_group()`, `getrlimit()`, `rt_sigreturn()`, `sigreturn()` system calls and the system calls for querying time and sleeping are implicitly allow-listed and do not need to be listed explicitly. The default action when a system call is denied is to terminate the processes with a `SIGSYS` signal. This can changed using `SystemCallErrorNumber=`, see below. In addition, deny-listed system calls and system call groups may optionally be suffixed with a colon (`:`) and an argument in the same format as `SystemCallErrorNumber=`, to take this action when the matching system call is made. This takes precedence over the action specified in `SystemCallErrorNumber=`. This feature makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') and is useful for enforcing a minimal sandboxing environment. Note that on systems supporting multiple ABIs (such as x86/x86-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option. Specifically, it is recommended to combine this option with `SystemCallArchitectures=native` or similar. Note that strict system call filters may impact execution and error handling code paths of the service invocation. Specifically, access to the `execve()` system call is required for the execution of the service binary — if it is blocked service invocation will necessarily fail. Also, if execution of the service binary fails for some reason (for example: missing service executable), the error handling logic might require access to an additional set of system calls in order to process and log this failure correctly. It might be necessary to temporarily disable system call filters in order to allow debugging of such failures. If you specify both types of this option (i.e. allow-listing and deny-listing), the first encountered will take precedence and will dictate the default action (termination or approval of a system call). Then the next occurrences of this option will add or delete the listed system calls from the set of the filtered system calls, depending of its type and the default action. (For example, if you have started with an allow list rule for `read()` and `write()`, and right after it add a deny list rule for `write()`, then `write()` will be removed from the set.) As the number of possible system calls is large, predefined groups of system calls are provided. A group starts with `@` character, followed by name of the set. | Set | Description | |----|----| | @aio | Asynchronous I/O (`io_setup(2)`, `io_submit(2)`, and related calls) | | @basic-io | System calls for basic I/O: reading, writing, seeking, file descriptor duplication and closing (`read(2)`, `write(2)`, and related calls) | | @chown | Changing file ownership (`chown(2)`, `fchownat(2)`, and related calls) | | @clock | System calls for changing the system clock (`adjtimex(2)`, `settimeofday(2)`, and related calls) | | @cpu-emulation | System calls for CPU emulation functionality (`vm86(2)` and related calls) | | @debug | Debugging, performance monitoring and tracing functionality (`ptrace(2)`, `perf_event_open(2)` and related calls) | | @file-system | File system operations: opening, creating files and directories for read and write, renaming and removing them, reading file properties, or creating hard and symbolic links | | @io-event | Event loop system calls (`poll(2)`, `select(2)`, `epoll(7)`, `eventfd(2)` and related calls) | | @ipc | Pipes, SysV IPC, POSIX Message Queues and other IPC (`mq_overview(7)`, `svipc(7)`) | | @keyring | Kernel keyring access (`keyctl(2)` and related calls) | | @memlock | Locking of memory in RAM (`mlock(2)`, `mlockall(2)` and related calls) | | @module | Loading and unloading of kernel modules (`init_module(2)`, `delete_module(2)` and related calls) | | @mount | Mounting and unmounting of file systems (`mount(2)`, `chroot(2)`, and related calls) | | @network-io | Socket I/O (including local AF_UNIX): `socket(7)`, `unix(7)` | | @obsolete | Unusual, obsolete or unimplemented (`create_module(2)`, `gtty(2)`, …) | | @pkey | System calls that deal with memory protection keys (`pkeys(7)`) | | @privileged | All system calls which need super-user capabilities (`capabilities(7)`) | | @process | Process control, execution, namespacing operations (`clone(2)`, `kill(2)`, `namespaces(7)`, …) | | @raw-io | Raw I/O port access (`ioperm(2)`, `iopl(2)`, `pciconfig_read()`, …) | | @reboot | System calls for rebooting and reboot preparation (`reboot(2)`, `kexec()`, …) | | @resources | System calls for changing resource limits, memory and scheduling parameters (`setrlimit(2)`, `setpriority(2)`, …) | | @sandbox | System calls for sandboxing programs (`seccomp(2)`, Landlock system calls, …) | | @setuid | System calls for changing user ID and group ID credentials, (`setuid(2)`, `setgid(2)`, `setresuid(2)`, …) | | @signal | System calls for manipulating and handling process signals (`signal(2)`, `sigprocmask(2)`, …) | | @swap | System calls for enabling/disabling swap devices (`swapon(2)`, `swapoff(2)`) | | @sync | Synchronizing files and memory to disk (`fsync(2)`, `msync(2)`, and related calls) | | @system-service | A reasonable set of system calls used by common system services, excluding any special purpose calls. This is the recommended starting point for allow-listing system calls for system services, as it contains what is typically needed by system services, but excludes overly specific interfaces. For example, the following APIs are excluded: `@clock`, `@mount`, `@swap`, `@reboot`. | | @timer | System calls for scheduling operations by time (`alarm(2)`, `timer_create(2)`, …) | | @known | All system calls defined by the kernel. This list is defined statically in systemd based on a kernel version that was available when this systemd version was released. It will become progressively more out-of-date as the kernel is updated. | Currently predefined system call sets Note, that as new system calls are added to the kernel, additional system calls might be added to the groups above. Contents of the sets may also change between systemd versions. In addition, the list of system calls depends on the kernel version and architecture for which systemd was compiled. Use `systemd-analyze syscall-filter` to list the actual list of system calls in each filter. Generally, allow-listing system calls (rather than deny-listing) is the safer mode of operation. It is recommended to enforce system call allow lists for all long-running system services. Specifically, the following lines are a relatively safe basic choice for the majority of system services: [Service] SystemCallFilter=@system-service SystemCallErrorNumber=EPERM Note that various kernel system calls are defined redundantly: there are multiple system calls for executing the same operation. For example, the `pidfd_send_signal()` system call may be used to execute operations similar to what can be done with the older `kill()` system call, hence blocking the latter without the former only provides weak protection. Since new system calls are added regularly to the kernel as development progresses, keeping system call deny lists comprehensive requires constant work. It is thus recommended to use allow-listing instead, which offers the benefit that new system calls are by default implicitly blocked until the allow list is updated. Also note that a number of system calls are required to be accessible for the dynamic linker to work. The dynamic linker is required for running most regular programs (specifically: all dynamic ELF binaries, which is how most distributions build packaged programs). This means that blocking these system calls (which include `open()`, `openat()` or `mmap()`) will make most programs typically shipped with generic distributions unusable. It is recommended to combine the file system namespacing related options with `SystemCallFilter=~@mount`, in order to prohibit the unit's processes to undo the mappings. Specifically these are the options `PrivateTmp=`, `PrivateDevices=`, `ProtectSystem=`, `ProtectHome=`, `ProtectKernelTunables=`, `ProtectControlGroups=`, `ProtectKernelLogs=`, `ProtectClock=`, `ReadOnlyPaths=`, `InaccessiblePaths=` and `ReadWritePaths=`. `SystemCallErrorNumber=` Takes an `errno` error number (between 1 and 4095) or errno name such as `EPERM`, `EACCES` or `EUCLEAN`, to return when the system call filter configured with `SystemCallFilter=` is triggered, instead of terminating the process immediately. See `errno(3)` for a full list of error codes. When this setting is not used, or when the empty string or the special setting `kill` is assigned, the process will be terminated immediately when the filter is triggered. `SystemCallArchitectures=` Takes a space-separated list of architecture identifiers to include in the system call filter. The known architecture identifiers are the same as for `ConditionArchitecture=` described in `systemd.unit(5)`, as well as `x32`, `mips64-n32`, `mips64-le-n32`, and the special identifier `native`. The special identifier `native` implicitly maps to the native architecture of the system (or more precisely: to the architecture the system manager is compiled for). By default, this option is set to the empty list, i.e. no filtering is applied. If this setting is used, processes of this unit will only be permitted to call native system calls, and system calls of the specified architectures. For the purposes of this option, the x32 architecture is treated as including x86-64 system calls. However, this setting still fulfills its purpose, as explained below, on x32. System call filtering is not equally effective on all architectures. For example, on x86 filtering of network socket-related calls is not possible, due to ABI limitations — a limitation that x86-64 does not have, however. On systems supporting multiple ABIs at the same time — such as x86/x86-64 — it is hence recommended to limit the set of permitted system call architectures so that secondary ABIs may not be used to circumvent the restrictions applied to the native ABI of the system. In particular, setting `SystemCallArchitectures=native` is a good choice for disabling non-native ABIs. System call architectures may also be restricted system-wide via the `SystemCallArchitectures=` option in the global configuration. See `systemd-system.conf(5)` for details. `SystemCallLog=` Takes a comma- or space-separated list of system call names. If this setting is used, all system calls executed by the unit processes for the listed ones will be logged. If the first character of the list is `~`, the effect is inverted: all system calls except the listed system calls will be logged. This feature makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') and is useful for auditing or setting up a minimal sandboxing environment. This option may be specified more than once, in which case the filter masks are merged. If the empty string is assigned, the filter is reset, all prior assignments will have no effect. This does not affect commands prefixed with `+`. # Environment `Environment=` Sets environment variables for executed processes. Each line is unquoted using the rules described in "Quoting" section in `systemd.syntax(7)` and becomes a list of variable assignments. If you need to assign a value containing spaces or the equals sign to a variable, put quotes around the whole assignment. Variable expansion is not performed inside the strings and the `$` character has no special meaning. Specifier expansion is performed, see the "Specifiers" section in `systemd.unit(5)`. This option may be specified more than once, in which case all listed variables will be set. If the same variable is listed twice, the later setting will override the earlier setting. If the empty string is assigned to this option, the list of environment variables is reset, all prior assignments have no effect. The names of the variables can contain ASCII letters, digits, and the underscore character. Variable names cannot be empty or start with a digit. In variable values, most characters are allowed, but non-printable characters are currently rejected. Example: Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6" gives three variables `VAR1`, `VAR2`, `VAR3` with the values `word1 word2`, `word3`, `$word 5 6`. See `environ(7)` for details about environment variables. Note that environment variables are not suitable for passing secrets (such as passwords, key material, …) to service processes. Environment variables set for a unit are exposed to unprivileged clients via D-Bus IPC, and generally not understood as being data that requires protection. Moreover, environment variables are propagated down the process tree, including across security boundaries (such as setuid/setgid executables), and hence might leak to processes that should not have access to the secret data. Use `LoadCredential=`, `LoadCredentialEncrypted=` or `SetCredentialEncrypted=` (see below) to pass data to unit processes securely. `EnvironmentFile=` Similar to `Environment=`, but reads the environment variables from a text file. The text file should contain newline-separated variable assignments. Empty lines, lines without an `=` separator, or lines starting with `;` or `#` will be ignored, which may be used for commenting. The file must be encoded with UTF-8. Valid characters are [unicode scalar values](https://www.unicode.org/glossary/#unicode_scalar_value) other than [unicode noncharacters](https://www.unicode.org/glossary/#noncharacter), `U+0000` `NUL`, and `U+FEFF` [unicode byte order mark](https://www.unicode.org/glossary/#byte_order_mark). Control codes other than `NUL` are allowed. In the file, an unquoted value after the `=` is parsed with the same backslash-escape rules as [POSIX shell unquoted text](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01), but unlike in a shell, interior whitespace is preserved and quotes after the first non-whitespace character are preserved. Leading and trailing whitespace (space, tab, carriage return) is discarded, but interior whitespace within the line is preserved verbatim. A line ending with a backslash will be continued to the following one, with the newline itself discarded. A backslash `\` followed by any character other than newline will preserve the following character, so that `\\` will become the value `\`. In the file, a `'`-quoted value after the `=` can span multiple lines and contain any character verbatim other than single quote, like [POSIX shell single-quoted text](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02). No backslash-escape sequences are recognized. Leading and trailing whitespace outside of the single quotes is discarded. In the file, a `"`-quoted value after the `=` can span multiple lines, and the same escape sequences are recognized as in [POSIX shell double-quoted text](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03). Backslash (`\`) followed by any of `` "\`$ `` will preserve that character. A backslash followed by newline is a line continuation, and the newline itself is discarded. A backslash followed by any other character is ignored; both the backslash and the following character are preserved verbatim. Leading and trailing whitespace outside of the double quotes is discarded. The argument passed should be an absolute filename or wildcard expression. If the file does not exist, cannot be read, or contains invalid content, the service will fail to start. To make the file optional, prefix the path with `-`, which causes all errors related to the file to be silently ignored. This option may be specified more than once in which case all specified files are read. If the empty string is assigned to this option, the list of files to read is reset, all prior assignments have no effect. Note that shell variables such as `$HOME` are not expanded in this path. Use `%`-specifiers instead; for example, `%h` expands to the user's home directory. The files listed with this directive will be read shortly before the process is executed (more specifically, after all processes from a previous unit state terminated. This means you can generate these files in one unit state, and read it with this option in the next. The files are read from the file system of the service manager, before any file system changes like bind mounts take place). Settings from these files override settings made with `Environment=`. If the same variable is set twice from these files, the files will be read in the order they are specified and the later setting will override the earlier setting. `PassEnvironment=` Pass environment variables set for the system service manager to executed processes. Takes a space-separated list of variable names. This option may be specified more than once, in which case all listed variables will be passed. If the empty string is assigned to this option, the list of environment variables to pass is reset, all prior assignments have no effect. Variables specified that are not set for the system manager will not be passed and will be silently ignored. Note that this option is only relevant for the system service manager, as system services by default do not automatically inherit any environment variables set for the service manager itself. However, in case of the user service manager all environment variables are passed to the executed processes anyway, hence this option is without effect for the user service manager. Variables set for invoked processes due to this setting are subject to being overridden by those configured with `Environment=` or `EnvironmentFile=`. Example: PassEnvironment=VAR1 VAR2 VAR3 passes three variables `VAR1`, `VAR2`, `VAR3` with the values set for those variables in PID1. See `environ(7)` for details about environment variables. `UnsetEnvironment=` Explicitly unset environment variable assignments that would normally be passed from the service manager to invoked processes of this unit. Takes a space-separated list of variable names or variable assignments. This option may be specified more than once, in which case all listed variables/assignments will be unset. If the empty string is assigned to this option, the list of environment variables/assignments to unset is reset. If a variable assignment is specified (that is: a variable name, followed by `=`, followed by its value), then any environment variable matching this precise assignment is removed. If a variable name is specified (that is a variable name without any following `=` or value), then any assignment matching the variable name, regardless of its value is removed. Note that the effect of `UnsetEnvironment=` is applied as final step when the environment list passed to executed processes is compiled. That means it may undo assignments from any configuration source, including assignments made through `Environment=` or `EnvironmentFile=`, inherited from the system manager's global set of environment variables, inherited via `PassEnvironment=`, set by the service manager itself (such as `$NOTIFY_SOCKET` and such), or set by a PAM module (in case `PAMName=` is used). Note that variable expansion in the command lines of `ExecStart=` and friends is not affected by this option, as it happens before the unsetting is applied. See "Environment Variables in Spawned Processes" below for a description of how those settings combine to form the inherited environment. See `environ(7)` for general information about environment variables. # Logging and Standard Input/Output `StandardInput=` Controls where file descriptor 0 (STDIN) of the executed processes is connected to. Takes one of `null`, `tty`, `tty-force`, `tty-fail`, `data`, `file:path`, `socket`, `fd:name`, `broker` or `broker-log`. If `null` is selected, standard input will be connected to `/dev/null`, i.e. all read attempts by the process will result in immediate EOF. If `tty` is selected, standard input is connected to a TTY (as configured by `TTYPath=`, see below) and the executed process becomes the controlling process of the terminal. If the terminal is already being controlled by another process, the executed process waits until the current controlling process releases the terminal. `tty-force` is similar to `tty`, but the executed process is forcefully and immediately made the controlling process of the terminal, potentially removing previous controlling processes from the terminal. `tty-fail` is similar to `tty`, but if the terminal already has a controlling process start-up of the executed process fails. The `data` option may be used to configure arbitrary textual or binary data to pass via standard input to the executed process. The data to pass is configured via `StandardInputText=`/`StandardInputData=` (see below). Note that the actual file descriptor type passed (memory file, regular file, UNIX pipe, …) might depend on the kernel and available privileges. In any case, the file descriptor is read-only, and when read returns the specified data followed by EOF. The `file:path` option may be used to connect a specific file system object to standard input. An absolute path following the `:` character is expected, which may refer to a regular file, a FIFO or special file. If an `AF_UNIX` socket in the file system is specified, a stream socket is connected to it. The latter is useful for connecting standard input of processes to arbitrary system services. Note that the file system object is opened by the service manager before the executable is invoked; see the note on the security context this happens in for `StandardOutput=` below. The `socket` option is valid in socket-activated services only, and requires the relevant socket unit file (see `systemd.socket(5)` for details) to have `Accept=yes` set, or to specify a single socket only. If this option is set, standard input will be connected to the socket the service was activated from, which is primarily useful for compatibility with daemons designed for use with the traditional `inetd(8)` socket activation daemon (`$LISTEN_FDS` (and related) environment variables are not passed when `socket` value is configured). The `fd:name` option connects standard input to a specific, named file descriptor provided by a socket unit. The name may be specified as part of this option, following a `:` character (e.g. `fd:foobar`). If no name is specified, the name `stdin` is implied (i.e. `fd` is equivalent to `fd:stdin`). At least one socket unit defining the specified name must be provided via the `Sockets=` option, and the file descriptor name may differ from the name of its containing socket unit. If multiple matches are found, the first one will be used. See `FileDescriptorName=` in `systemd.socket(5)` for more details about named file descriptors and their ordering. The `broker` and `broker-log` options connect standard input to a pseudo TTY allocated on the fly by `systemd-ptybrokerd.service(8)`. The broker allocates the pseudo TTY pair and retains its frontend (i.e. the "master" side), while the backend (i.e. the "slave" side) is installed as the executed process' standard input, and the process becomes the controlling process of the terminal. Unlike `tty` this does not require a physical terminal device to be configured via `TTYPath=`, and hence works even in contexts where no console is available, for example fully headless systems. With `broker` anything the process writes to the terminal is discarded, while with `broker-log` the output is additionally forwarded to the logs. The terminal type and dimensions of the allocated pseudo TTY (as exposed via `$TERM`, `$COLORTERM`, `$NO_COLOR` and the terminal window size) are derived from the unit's `Environment=` and `TTYColumns=`/`TTYRows=` settings. When one of these options is used the unit gains implicit `After=` and `Wants=` dependencies on `systemd-ptybrokerd.socket`. This setting defaults to `null`, unless `StandardInputText=`/`StandardInputData=` are set, in which case it defaults to `data`. `StandardOutput=` Controls where file descriptor 1 (stdout) of the executed processes is connected to. Takes one of `inherit`, `null`, `tty`, `journal`, `kmsg`, `journal+console`, `kmsg+console`, `file:path`, `append:path`, `truncate:path`, `socket`, `fd:name`, `broker` or `broker-log`. `inherit` duplicates the file descriptor of standard input for standard output. `null` connects standard output to `/dev/null`, i.e. everything written to it will be lost. `tty` connects standard output to a tty (as configured via `TTYPath=`, see below). If the TTY is used for output only, the executed process will not become the controlling process of the terminal, and will not fail or wait for other processes to release the terminal. Note: if a unit tries to print multiple lines to a TTY during bootup or shutdown, then there's a chance that those lines will be broken up by status messages. `SetShowStatus()` can be used to prevent this problem. See `org.freedesktop.systemd1(5)` for details. `journal` connects standard output with the journal, which is accessible via `journalctl(1)`. Note that everything that is written to kmsg (see below) is implicitly stored in the journal as well, the specific option listed below is hence a superset of this one. (Also note that any external, additional syslog daemons receive their log data from the journal, too, hence this is the option to use when logging shall be processed with such a daemon.) `kmsg` connects standard output with the kernel log buffer which is accessible via `dmesg(1)`, in addition to the journal. The journal daemon might be configured to send all logs to kmsg anyway, in which case this option is no different from `journal`. `journal+console` and `kmsg+console` work in a similar way as the two options above but copy the output to the system console as well. The `file:path` option may be used to connect a specific file system object to standard output. The semantics are similar to the same option of `StandardInput=`, see above. If \ refers to a regular file on the filesystem, it is opened (created if it does not exist yet using privileges of the user executing the systemd process) for writing at the beginning of the file, but without truncating it. If standard input and output are directed to the same file path, it is opened only once — for reading as well as writing — and duplicated. This is particularly useful when the specified path refers to an `AF_UNIX` socket in the file system, as in that case only a single stream connection is created for both input and output. `append:path` is similar to `file:path` above, but it opens the file in append mode. `truncate:path` is similar to `file:path` above, but it truncates the file when opening it. For units with multiple command lines, e.g. `Type=oneshot` services with multiple `ExecStart=`, or services with `ExecCondition=`, `ExecStartPre=` or `ExecStartPost=`, the output file is reopened and therefore re-truncated for each command line. If the output file is truncated while another process still has the file open, e.g. by an `ExecReload=` running concurrently with an `ExecStart=`, and the other process continues writing to the file without adjusting its offset, then the space between the file pointers of the two processes may be filled with `NUL` bytes, producing a sparse file. Thus, `truncate:path` is typically only useful for units where only one process runs at a time, such as services with a single `ExecStart=` and no `ExecStartPost=`, `ExecReload=`, `ExecStop=` or similar. Note that for `file:path`, `append:path` and `truncate:path` of `StandardOutput=`, `StandardError=` or `StandardInput=`, the target path is opened by the service manager before the executable is invoked — and hence before `SELinuxContext=` or any policy-defined transition takes effect. The resulting descriptor is then inherited across that transition into the unit's own domain. `socket` connects standard output to a socket acquired via socket activation. The semantics are similar to the same option of `StandardInput=`, see above. The `fd:name` option connects standard output to a specific, named file descriptor provided by a socket unit. A name may be specified as part of this option, following a `:` character (e.g. `fd:foobar`). If no name is specified, the name `stdout` is implied (i.e. `fd` is equivalent to `fd:stdout`). At least one socket unit defining the specified name must be provided via the `Sockets=` option, and the file descriptor name may differ from the name of its containing socket unit. If multiple matches are found, the first one will be used. See `FileDescriptorName=` in `systemd.socket(5)` for more details about named descriptors and their ordering. The `broker` and `broker-log` options connect standard output to a pseudo TTY allocated on the fly by `systemd-ptybrokerd.service(8)`, with the same semantics as described for `StandardInput=` above. (Note however that the process becomes the controlling process of the allocated terminal only if standard *input* is connected to it, too.) With `broker` the terminal output is discarded, with `broker-log` it is forwarded to the logs. This is useful to provide a process with a fully featured terminal on its standard output even on systems that have no physical console, without having to allocate and manage the pseudo TTY manually. When one of these options is used the unit gains implicit `After=` and `Wants=` dependencies on `systemd-ptybrokerd.socket`. If the standard output (or error output, see below) of a unit is connected to the journal or the kernel log buffer, the unit will implicitly gain a dependency of type `After=` on `systemd-journald.socket` (also see the "Implicit Dependencies" section above). Also note that, in this case, stdout (or stderr, see below) will be an `AF_UNIX` stream socket, and not a pipe or FIFO that can be reopened. This means when executing shell scripts the construct `echo "hello" > /dev/stderr` for writing text to stderr will not work. To mitigate this use the construct `echo "hello" >&2` instead, which is mostly equivalent and avoids this pitfall. If `StandardInput=` is set to one of `tty`, `tty-force`, `tty-fail`, `socket`, `fd:name`, `broker`, or `broker-log`, this setting defaults to `inherit`. In other cases, this setting defaults to the value set with `DefaultStandardOutput=` in `systemd-system.conf(5)`, which defaults to `journal`. Note that setting this parameter might result in additional dependencies to be added to the unit (see above). `StandardError=` Controls where file descriptor 2 (stderr) of the executed processes is connected to. The available options are identical to those of `StandardOutput=`, with some exceptions: if set to `inherit` the file descriptor used for standard output is duplicated for standard error, while `fd:name` will use a default file descriptor name of `stderr`. This setting defaults to the value set with `DefaultStandardError=` in `systemd-system.conf(5)`, which defaults to `inherit`. Note that setting this parameter might result in additional dependencies to be added to the unit (see above). `StandardInputText=`; `StandardInputData=` Configures arbitrary textual or binary data to pass via file descriptor 0 (STDIN) to the executed processes. These settings have no effect unless `StandardInput=` is set to `data` (which is the default if `StandardInput=` is not set otherwise, but `StandardInputText=`/`StandardInputData=` is). Use this option to embed process input data directly in the unit file. `StandardInputText=` accepts arbitrary textual data. C-style escapes for special characters as well as the usual `%`-specifiers are resolved. Each time this setting is used the specified text is appended to the per-unit data buffer, followed by a newline character (thus every use appends a new line to the end of the buffer). Note that leading and trailing whitespace of lines configured with this option is removed. If an empty line is specified the buffer is cleared (hence, in order to insert an empty line, add an additional `\n` to the end or beginning of a line). `StandardInputData=` accepts arbitrary binary data, encoded in [Base64](https://tools.ietf.org/html/rfc2045#section-6.8). No escape sequences or specifiers are resolved. Any whitespace in the encoded version is ignored during decoding. Note that `StandardInputText=` and `StandardInputData=` operate on the same data buffer, and may be mixed in order to configure both binary and textual data for the same input stream. The textual or binary data is joined strictly in the order the settings appear in the unit file. Assigning an empty string to either will reset the data buffer. Please keep in mind that in order to maintain readability long unit file settings may be split into multiple lines, by suffixing each line (except for the last) with a `\` character (see `systemd.unit(5)` for details). This is particularly useful for large data configured with these two options. Example: … StandardInput=data StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZXMgYW5kIHNvIGRv \ IEkKQSBmdWxsIGNvbW1pdG1lbnQncyB3aGF0IEnigLJtIHRoaW5raW5nIG9mCllvdSB3b3VsZG4n \ dCBnZXQgdGhpcyBmcm9tIGFueSBvdGhlciBndXkKSSBqdXN0IHdhbm5hIHRlbGwgeW91IGhvdyBJ \ J20gZmVlbGluZwpHb3R0YSBtYWtlIHlvdSB1bmRlcnN0YW5kCgpOZXZlciBnb25uYSBnaXZlIHlv \ dSB1cApOZXZlciBnb25uYSBsZXQgeW91IGRvd24KTmV2ZXIgZ29ubmEgcnVuIGFyb3VuZCBhbmQg \ ZGVzZXJ0IHlvdQpOZXZlciBnb25uYSBtYWtlIHlvdSBjcnkKTmV2ZXIgZ29ubmEgc2F5IGdvb2Ri \ eWUKTmV2ZXIgZ29ubmEgdGVsbCBhIGxpZSBhbmQgaHVydCB5b3UK … `LogLevelMax=` Sets the maximum log level for log messages generated by this unit. Takes a `syslog` log level, one of `emerg` (lowest log level, only highest priority messages), `alert`, `crit`, `err`, `warning`, `notice`, `info`, `debug` (highest log level, also lowest priority messages). See `syslog(3)` for details. By default, the maximum log level is not overridden. This option can be used to configure the logging system to drop log messages of a specific service above the specified level. For example, set `LogLevelMax=``info` in order to turn off debug logging of a particularly chatty unit. Alternatively, this option can be used to enable extra logging about a specific unit by the system or user manager processes without changing the global log level for the system or user manager processes by setting `LogLevelMax=``debug`. Note that the configured level is applied to any log messages written by any of the processes belonging to this unit, as well as any log messages written by the system or user manager processes in reference to this unit, sent via any supported logging protocol. The override is applied early in the logging pipeline, before any kind of further processing is done. Moreover, messages which pass through this filter successfully might still be dropped by filters applied at a later stage in the logging subsystem. For example, `MaxLevelStore=` configured in `journald.conf(5)` might prohibit messages of higher log levels to be stored on disk, even though the per-unit `LogLevelMax=` permitted it to be processed. `LogExtraFields=` Configures additional log metadata fields to include in all log records generated by processes associated with this unit, including systemd. This setting takes one or more journal field assignments in the format `FIELD=VALUE` separated by whitespace. See `systemd.journal-fields(7)` for details on the journal field concept. Even though the underlying journal implementation permits binary field values, this setting accepts only valid UTF-8 values. To include space characters in a journal field value, enclose the assignment in double quotes ("). The usual specifiers are expanded in all assignments (see below). Note that this setting is not only useful for attaching additional metadata to log records of a unit, but given that all fields and values are indexed may also be used to implement cross-unit log record matching. Assign an empty string to reset the list. Note that this functionality is currently only available in system services, not in per-user services. `LogRateLimitIntervalSec=`; `LogRateLimitBurst=` Configures the rate limiting that is applied to log messages generated by this unit. If, in the time interval defined by `LogRateLimitIntervalSec=`, more messages than specified in `LogRateLimitBurst=` are logged by a service, all further messages within the interval are dropped until the interval is over. A message about the number of dropped messages is generated. The time specification for `LogRateLimitIntervalSec=` may be specified in the following units: "s", "min", "h", "ms", "us". See `systemd.time(7)` for details. The default settings are set by `RateLimitIntervalSec=` and `RateLimitBurst=` configured in `journald.conf(5)`. Note that this only applies to log messages that are processed by the logging subsystem, i.e. by `systemd-journald.service(8)`. This means that if you connect a service's stderr directly to a file via `StandardOutput=file:…` or a similar setting, the rate limiting will not be applied to messages written that way (but it will be enforced for messages generated via `syslog(3)` and similar functions). `LogFilterPatterns=` Define an extended regular expression to filter log messages based on the `MESSAGE=` field of the structured message. If the first character of the pattern is `~`, log entries matching the pattern should be discarded. This option takes a single pattern as an argument but can be used multiple times to create a list of allowed and denied patterns. If the empty string is assigned, the filter is reset, and all prior assignments will have no effect. Because the `~` character is used to define denied patterns, it must be replaced with `\x7e` to allow a message starting with `~`. For example, `~foobar` would add a pattern matching `foobar` to the deny list, while `\x7efoobar` would add a pattern matching `~foobar` to the allow list. Log messages are tested against denied patterns (if any), then against allowed patterns (if any). If a log message matches any of the denied patterns, it is discarded immediately without considering allowed patterns. Remaining log messages are tested against allowed patterns. Messages matching against none of the allowed pattern are discarded. If no allowed patterns are defined, then all messages are processed directly after going through denied filters. Filtering is based on the unit for which `LogFilterPatterns=` is defined, meaning log messages coming from `systemd(1)` about the unit are not taken into account. Filtered log messages will not be forwarded to traditional syslog daemons, the kernel log buffer (kmsg), the systemd console, or sent as wall messages to all logged-in users. Note that this functionality is currently only available in system services, not in per-user services. `LogNamespace=` Run the unit's processes in the specified journal namespace. Expects a short user-defined string identifying the namespace. If not used the processes of the service are run in the default journal namespace, i.e. their log stream is collected and processed by `systemd-journald.service`. If this option is used any log data generated by processes of this unit (regardless of whether via the `syslog()`, journal native logging or stdout/stderr logging) is collected and processed by an instance of the `systemd-journald@.service` template unit, which manages the specified namespace. The log data is stored in a data store independent from the default log namespace's data store. See `systemd-journald.service(8)` for details about journal namespaces. Internally, journal namespaces are implemented through Linux mount namespacing and over-mounting the directory that contains the relevant `AF_UNIX` sockets used for logging in the unit's mount namespace. Since mount namespaces are used this setting disconnects propagation of mounts from the unit's processes to the host, similarly to how `ReadOnlyPaths=` and similar settings describe above work. Journal namespaces may hence not be used for services that need to establish mount points on the host. When this option is used the unit will automatically gain ordering and requirement dependencies on the two socket units associated with the `systemd-journald@.service` instance so that they are automatically established prior to the unit starting up. Note that when this option is used log output of this service does not appear in the regular `journalctl(1)` output, unless the `--namespace=` option is used. `SyslogIdentifier=` Sets the process name ("`syslog` tag") to prefix log lines sent to the logging system or the kernel log buffer with. If not set, defaults to the process name of the executed process. This option is only useful when `StandardOutput=` or `StandardError=` are set to `journal` or `kmsg` (or to the same settings in combination with `+console`) and only applies to log messages written to stdout or stderr. `SyslogFacility=` Sets the `syslog` facility identifier to use when logging. One of `kern`, `user`, `mail`, `daemon`, `auth`, `syslog`, `lpr`, `news`, `uucp`, `cron`, `authpriv`, `ftp`, `local0`, `local1`, `local2`, `local3`, `local4`, `local5`, `local6` or `local7`. See `syslog(3)` for details. This option is only useful when `StandardOutput=` or `StandardError=` are set to `journal` or `kmsg` (or to the same settings in combination with `+console`), and only applies to log messages written to stdout or stderr. Defaults to `daemon`. `SyslogLevel=` The default `syslog` log level to use when logging to the logging system or the kernel log buffer. One of `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, `debug`. See `syslog(3)` for details. This option is only useful when `StandardOutput=` or `StandardError=` are set to `journal` or `kmsg` (or to the same settings in combination with `+console`), and only applies to log messages written to stdout or stderr. Note that individual lines output by executed processes may be prefixed with a different log level which can be used to override the default log level specified here. The interpretation of these prefixes may be disabled with `SyslogLevelPrefix=`, see below. For details, see `sd-daemon(3)`. Defaults to `info`. `SyslogLevelPrefix=` Takes a boolean argument. If true and `StandardOutput=` or `StandardError=` are set to `journal` or `kmsg` (or to the same settings in combination with `+console`), log lines written by the executed process that are prefixed with a log level will be processed with this log level set but the prefix removed. If set to false, the interpretation of these prefixes is disabled and the logged lines are passed on as-is. This only applies to log messages written to stdout or stderr. For details about this prefixing see `sd-daemon(3)`. Defaults to true. `TTYPath=` Sets the terminal device node to use if standard input, output, or error are connected to a TTY (see above). Defaults to `/dev/console`. `TTYReset=` Reset the terminal device specified with `TTYPath=` before and after execution. This does not erase the screen (see `TTYVTDisallocate=` below for that). Defaults to `no`. `TTYVHangup=` Disconnect all clients which have opened the terminal device specified with `TTYPath=` before and after execution. Defaults to `no`. `TTYColumns=`; `TTYRows=` Configure the size of the TTY specified with `TTYPath=`. If unset or set to the empty string, it is attempted to retrieve the dimensions of the terminal screen via ANSI sequences, and if that fails the kernel defaults (typically 80x24) are used. `TTYVTDisallocate=` If the terminal device specified with `TTYPath=` is a virtual console terminal, try to deallocate the TTY before and after execution. This ensures that the screen and scrollback buffer is cleared. If the terminal device is of any other type of TTY an attempt is made to clear the screen via ANSI sequences. Defaults to `no`. # Credentials `LoadCredential=`\\[:\\]; `LoadCredentialEncrypted=`\\[:\\] Pass a credential to the unit. Credentials are limited-size binary or textual objects that may be passed to unit processes. They are primarily intended for passing cryptographic keys (both public and private) or certificates, user account information or identity information from host to services, but can be freely used to pass any kind of limited-size information to a service. The data is accessible from the unit's processes via the file system, at a read-only location that (if possible and permitted) is backed by non-swappable memory. The data is only accessible to the user associated with the unit, via the `User=`/`DynamicUser=` settings (as well as the superuser). When available, the location of credentials is exported as the `$CREDENTIALS_DIRECTORY` environment variable to the unit's processes. The `LoadCredential=` setting takes a textual ID to use as name for a credential plus a file system path, separated by a colon. The ID must be a short ASCII string suitable as filename in the filesystem, and may be chosen freely by the user. If the specified path is absolute it is opened as regular file and the credential data is read from it. If the absolute path refers to an `AF_UNIX` stream socket in the file system a connection is made to it (once at process invocation) and the credential data read from the connection, providing an easy IPC integration point for dynamically transferring credentials from other services. If the specified path is not absolute and itself qualifies as valid credential identifier it is attempted to find a credential that the service manager itself received under the specified name — which may be used to propagate credentials from an invoking environment (e.g. a container manager that invoked the service manager) into a service. If no matching passed credential is found, the system service manager will search the directories `/etc/credstore/`, `/run/credstore/` and `/usr/lib/credstore/` for files under the credential's name — which hence are recommended locations for credential data on disk. If `LoadCredentialEncrypted=` is used `/run/credstore.encrypted/`, `/etc/credstore.encrypted/`, and `/usr/lib/credstore.encrypted/` are searched as well. The per-user service manager will search `$XDG_CONFIG_HOME/credstore/`, `$XDG_RUNTIME_DIR/credstore/`, `$HOME/.local/lib/credstore/` (and the counterparts ending with `…/credstore.encrypted/`) instead. The `systemd-path(1)` tool may be used to query the precise credential store search path. If the file system path is omitted it is chosen identical to the credential name, i.e. this is a terse way to declare credentials to inherit from the service manager or credstore directories into a service. This option may be used multiple times, each time defining an additional credential to pass to the unit. Note that if the path is not specified or a valid credential identifier is given, i.e. in the above two cases, a missing credential is not considered fatal. If an absolute path referring to a directory is specified, every file in that directory (recursively) will be loaded as a separate credential. The ID for each credential will be the provided ID suffixed with `_$FILENAME` (e.g., `Key_file1`). When loading from a directory, symlinks will be ignored. The contents of the file/socket may be arbitrary binary or textual data, including newline characters and `NUL` bytes. The `LoadCredentialEncrypted=` setting is identical to `LoadCredential=`, except that the credential data is decrypted and authenticated before being passed on to the executed processes. Specifically, the referenced path should refer to a file or socket with an encrypted credential, as implemented by `systemd-creds(1)`. This credential is loaded, decrypted, authenticated and then passed to the application in plaintext form, in the same way a regular credential specified via `LoadCredential=` would be. A credential configured this way may be symmetrically encrypted/authenticated with a secret key derived from the system's TPM2 security chip, or with a secret key stored in `/var/lib/systemd/credential.secret`, or with both. Using encrypted and authenticated credentials improves security as credentials are not stored in plaintext and only authenticated and decrypted into plaintext the moment a service requiring them is started. Moreover, credentials may be bound to the local hardware and installations, so that they cannot easily be analyzed offline, or be generated externally. See `systemd.resource-control(5)` for the details about `DevicePolicy=` or `DeviceAllow=`. Note that encrypted credentials targeted for services of the per-user service manager must be encrypted with `systemd-creds encrypt --user`, and those for the system service manager without the `--user` switch. Encrypted credentials are always targeted to a specific user or the system as a whole, and it is ensured that per-user service managers cannot decrypt secrets intended for the system or for other users. The credential files/IPC sockets must be accessible to the service manager, but do not have to be directly accessible to the unit's processes: the credential data is read and copied into separate, read-only copies for the unit that are accessible to appropriately privileged processes. This is particularly useful in combination with `DynamicUser=` as this way privileged data can be made available to processes running under a dynamic UID (i.e. not a previously known one) without having to open up access to all users. In order to reference the path a credential may be read from within a `ExecStart=` command line use `${CREDENTIALS_DIRECTORY}/mycred`, e.g. `ExecStart=cat ${CREDENTIALS_DIRECTORY}/mycred`. In order to reference the path a credential may be read from within a `Environment=` line use `%d/mycred`, e.g. `Environment=MYCREDPATH=%d/mycred`. For system services the path may also be referenced as `/run/credentials/UNITNAME` in cases where no interpolation is possible, e.g. configuration files of software that does not yet support credentials natively. `$CREDENTIALS_DIRECTORY` is considered the primary interface to look for credentials, though, since it also works for user services. Currently, an accumulated credential size limit of 1 MB per unit is enforced. The service manager itself may receive system credentials that can be propagated to services from a hosting container manager or VM hypervisor. See the [Container Interface](https://systemd.io/CONTAINER_INTERFACE) documentation for details about the former. For the latter, pass [DMI/SMBIOS](https://www.dmtf.org/standards/smbios) OEM string table entries (field type 11) with a prefix of `io.systemd.credential:` or `io.systemd.credential.binary:`. In both cases a key/value pair separated by `=` is expected. In the latter case, the right-hand side is Base64 decoded when parsed (thus permitting binary data to be passed in). Example [qemu](https://www.qemu.org/docs/master/system/index.html) switch: `-smbios type=11,value=io.systemd.credential:xx=yy`, or `-smbios type=11,value=io.systemd.credential.binary:rick=TmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXA=`. Alternatively, use the `qemu` `fw_cfg` node `opt/io.systemd.credentials/`. Example `qemu` switch: `-fw_cfg name=opt/io.systemd.credentials/mycred,string=supersecret`. They may also be passed from the UEFI firmware environment via `systemd-stub(7)`, from the initrd (see `systemd(1)`), or be specified on the kernel command line using the `systemd.set_credential=` and `systemd.set_credential_binary=` switches (see `systemd(1)` – this is not recommended since unprivileged userspace can read the kernel command line). If referencing an `AF_UNIX` stream socket to connect to, the connection will originate from an abstract namespace socket, that includes information about the unit and the credential ID in its socket name. Use `getpeername(2)` to query this information. The returned socket name is formatted as `NUL` \ `/unit/` \ `/` \, i.e. a `NUL` byte (as required for abstract namespace socket names), followed by a random string (consisting of alphadecimal characters), followed by the literal string `/unit/`, followed by the requesting unit name, followed by the literal character `/`, followed by the textual credential ID requested. Example: `\0adf9d86b6eda275e/unit/foobar.service/credx` in case the credential `credx` is requested for a unit `foobar.service`. This functionality is useful for using a single listening socket to serve credentials to multiple consumers. For further information see [System and Service Credentials](https://systemd.io/CREDENTIALS) documentation. `ImportCredential=`\ Pass one or more credentials to the unit. Takes a credential name for which we will attempt to find a credential that the service manager itself received under the specified name — which may be used to propagate credentials from an invoking environment (e.g. a container manager that invoked the service manager) into a service. If the credential name is a glob, all credentials matching the glob are passed to the unit. Matching credentials are searched for in the system credentials, the encrypted system credentials, and under `/etc/credstore/`, `/run/credstore/`, `/usr/lib/credstore/`, `/run/credstore.encrypted/`, `/etc/credstore.encrypted/`, and `/usr/lib/credstore.encrypted/` in that order. When multiple credentials of the same name are found, the first one found is used. The globbing expression implements a restrictive subset of `glob(7)`: only a single trailing `*` wildcard may be specified. Both `?` and `[]` wildcards are not permitted, nor are `*` wildcards anywhere except at the end of the glob expression. Optionally, the credential name or glob may be followed by a colon followed by a rename pattern. If specified, all credentials matching the credential name or glob are renamed according to the given pattern. For example, if `ImportCredential=my.original.cred:my.renamed.cred` is specified, the service manager will read the `my.original.cred` credential and make it available as the `my.renamed.cred` credential to the service. Similarly, if `ImportCredential=my.original.*:my.renamed.` is specified, the service manager will read all credentials starting with `my.original.` and make them available as `my.renamed.xxx` to the service. If `ImportCredential=` is specified multiple times and multiple credentials end up with the same name after renaming, the first one is kept and later ones are dropped. When multiple credentials of the same name are found, credentials found by `LoadCredential=` and `LoadCredentialEncrypted=` take priority over credentials found by `ImportCredential=`. Note that if decryption or authentication of a credential picked up as result of `ImportCredential=` fails it will be skipped gracefully (a warning is generated, but the credential will not be made available to the invoked service). This is different for those configured via `SetCredentialEncrypted=`/`LoadCredentialEncrypted=`, where failed decryption/authentication will result in service failure. `SetCredential=`\:\; `SetCredentialEncrypted=`\:\ The `SetCredential=` setting is similar to `LoadCredential=` but accepts a literal value to use as data for the credential, instead of a file system path to read the data from. Do not use this option for data that is supposed to be secret, as it is accessible to unprivileged processes via IPC. It's only safe to use this for user IDs, public key material and similar non-sensitive data. For everything else use `LoadCredential=`. In order to embed binary data into the credential data use C-style escaping (i.e. `\n` to embed a newline, or `\x00` to embed a `NUL` byte). The `SetCredentialEncrypted=` setting is identical to `SetCredential=` but expects an encrypted credential in literal form as value. This allows embedding confidential credentials securely directly in unit files. Use `systemd-creds(1)`' `-p` switch to generate suitable `SetCredentialEncrypted=` lines directly from plaintext credentials. For further details see `LoadCredentialEncrypted=` above. When multiple credentials of the same name are found, credentials found by `LoadCredential=`, `LoadCredentialEncrypted=` and `ImportCredential=` take priority over credentials found by `SetCredential=`. As such, `SetCredential=` will act as default if no credentials are found by any of the former. In this case, not being able to retrieve the credential from the path specified in `LoadCredential=` or `LoadCredentialEncrypted=` is not considered fatal. # System V Compatibility `UtmpIdentifier=` Takes a four character identifier string for an `utmp(5)` and wtmp entry for this service. This should only be set for services such as `getty` implementations (such as `agetty(8)`) where utmp/wtmp entries must be created and cleared before and after execution, or for services that shall be executed as if they were run by a `getty` process (see below). If the configured string is longer than four characters, it is truncated and the terminal four characters are used. This setting interprets %I style string replacements. This setting is unset by default, i.e. no utmp/wtmp entries are created or cleaned up for this service. `UtmpMode=` Takes one of `init`, `login` or `user`. If `UtmpIdentifier=` is set, controls which type of `utmp(5)`/wtmp entries for this service are generated. This setting has no effect unless `UtmpIdentifier=` is set too. If `init` is set, only an `INIT_PROCESS` entry is generated and the invoked process must implement a `getty`-compatible utmp/wtmp logic. If `login` is set, first an `INIT_PROCESS` entry, followed by a `LOGIN_PROCESS` entry is generated. In this case, the invoked process must implement a `login(1)`-compatible utmp/wtmp logic. If `user` is set, first an `INIT_PROCESS` entry, then a `LOGIN_PROCESS` entry and finally a `USER_PROCESS` entry is generated. In this case, the invoked process may be any process that is suitable to be run as session leader. Defaults to `init`. # Environment Variables in Spawned Processes Processes started by the service manager are executed with an environment variable block assembled from multiple sources. Processes started by the system service manager generally do not inherit environment variables set for the service manager itself (but this may be altered via `PassEnvironment=`), but processes started by the user service manager instances generally do inherit all environment variables set for the service manager itself. For each invoked process the list of environment variables set is compiled from the following sources: - Variables globally configured for the service manager, using the `DefaultEnvironment=` setting in `systemd-system.conf(5)`, the kernel command line option `systemd.setenv=` understood by `systemd(1)`, or via `systemctl(1)` `set-environment` verb. - Variables defined by the service manager itself (see the list below). - Variables set in the service manager's own environment variable block (subject to `PassEnvironment=` for the system service manager). - Variables set via `Environment=` in the unit file. - Variables read from files specified via `EnvironmentFile=` in the unit file. - Variables set by any PAM modules in case `PAMName=` is in effect, cf. `pam_env(8)`. If the same environment variable is set by multiple of these sources, the later source — according to the order of the list above — wins. Note that as the final step all variables listed in `UnsetEnvironment=` are removed from the compiled environment variable list, immediately before it is passed to the executed process. This unsetting happens after variable expansion in the command lines of `ExecStart=` and friends is performed, hence command line expansion is not affected by `UnsetEnvironment=`. The general philosophy is to expose a small curated list of environment variables to processes. Services started by the system manager (PID 1) will be started, without additional service-specific configuration, with just a few environment variables. The user manager inherits environment variables as any other system service, but in addition may receive additional environment variables from PAM, and, typically, additional imported variables when the user starts a graphical session. It is recommended to keep the environment blocks in both the system and user managers lean. Importing all variables inherited by the graphical session or by one of the user shells is strongly discouraged. Hint: `systemd-run -P env` and `systemd-run --user -P env` print the effective system and user service environment blocks. ## Environment Variables Set or Propagated by the Service Manager The following environment variables are propagated by the service manager or generated internally for each invoked process: `$PATH` Colon-separated list of directories to use when launching executables. `systemd` uses a built-in value of `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin` in the system manager. In case of the user manager, a different path may be configured by the distribution. The distribution may also add other paths to the end of this list for both the system and the user manager. It is recommended to not rely on the order of entries, and have only one program with a given name in `$PATH`. `$LANG` Locale. Can be set in `locale.conf(5)` or on the kernel command line (see `systemd(1)` and `kernel-command-line(7)`). `$USER`; `$LOGNAME`; `$HOME`; `$SHELL` User name (twice), home directory, and the login shell. `$USER` is set unconditionally, while `$HOME`, `$LOGNAME`, and `$SHELL` are only set for the units that have `User=` set and `SetLoginEnvironment=` unset or set to true. For user services, these variables are typically inherited from the user manager itself. See `passwd(5)`. `$INVOCATION_ID` Contains a randomized, unique 128-bit ID identifying each runtime cycle of the unit, formatted as 32 character hexadecimal string. A new ID is assigned each time the unit changes from an inactive state into an activating or active state, and may be used to identify this specific runtime cycle, in particular in data stored offline, such as the journal. The same ID is passed to all processes run as part of the unit. `$XDG_RUNTIME_DIR` The directory to use for runtime objects (such as IPC objects) and volatile state. Set for all services run by the user `systemd` instance, as well as any system services that use `PAMName=` with a PAM stack that includes `pam_systemd`. See below and `pam_systemd(8)` for more information. `$RUNTIME_DIRECTORY`; `$STATE_DIRECTORY`; `$CACHE_DIRECTORY`; `$LOGS_DIRECTORY`; `$CONFIGURATION_DIRECTORY` Absolute paths to the directories defined with `RuntimeDirectory=`, `StateDirectory=`, `CacheDirectory=`, `LogsDirectory=`, and `ConfigurationDirectory=` when those settings are used. `$CREDENTIALS_DIRECTORY` An absolute path to the per-unit directory with credentials configured via `ImportCredential=`/`LoadCredential=`/`SetCredential=`. The directory is marked read-only and is placed in unswappable memory (if supported and permitted), and is only accessible to the UID associated with the unit via `User=` or `DynamicUser=` (and the superuser). `$TMPDIR` The environment variable is set to `/tmp` when `PrivateTmp=disconnected` specified with `DefaultDependencies=no` and without `RootDirectory=/RootImage=` and `RequiresMountsFor=/WantsMountsFor=` for `/var/`. See explanation for `PrivateTmp=` above. `$MAINPID` The UNIX process ID (PID) of the unit's main process if it is known. This is only set for control processes as invoked by `ExecReload=` and similar. `$MAINPIDFDID` The 64bit inode ID of the file descriptor returned by `pidfd_open(3)` for the main process (if supported). This is only set for control processes as invoked by `ExecReload=` and similar. `$MANAGERPID` The PID of the per-user `systemd` service manager instance, set for processes spawned by it. `$MANAGERPIDFDID` The `pidfd_open()` inode ID (see above) of the per-user `systemd` service manager instance, set for processes spawned by it. `$LISTEN_FDS`; `$LISTEN_PID`; `$LISTEN_PIDFDID`; `$LISTEN_FDNAMES` Information about file descriptors passed to a service for socket activation. See `sd_listen_fds(3)`. `$NOTIFY_SOCKET` The socket `sd_notify()` talks to. See `sd_notify(3)`. `$WATCHDOG_PID`; `$WATCHDOG_USEC` Information about watchdog keep-alive notifications. See `sd_watchdog_enabled(3)`. `$SYSTEMD_EXEC_PID` The PID of the unit process (e.g. process invoked by `ExecStart=`). The child process can use this information to determine whether the process is directly invoked by the service manager or indirectly as a child of another process by comparing this value with the current PID (similarly to the scheme used in `sd_listen_fds(3)` with `$LISTEN_PID` and `$LISTEN_FDS`). `$TERM` Terminal type, set only for units connected to a terminal (`StandardInput=tty`, `StandardOutput=tty`, or `StandardError=tty`). See `termcap(5)`. `$LOG_NAMESPACE` Contains the name of the selected logging namespace when the `LogNamespace=` service setting is used. `$JOURNAL_STREAM` If the standard output or standard error output of the executed processes are connected to the journal (for example, by setting `StandardError=journal`) `$JOURNAL_STREAM` contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a colon (`:`). This permits invoked processes to safely detect whether their standard output or standard error output are connected to the journal. The device and inode numbers of the file descriptors should be compared with the values set in the environment variable to determine whether the process output is still connected to the journal. Note that it is generally not sufficient to only check whether `$JOURNAL_STREAM` is set at all as services might invoke external processes replacing their standard output or standard error output, without unsetting the environment variable. If both standard output and standard error of the executed processes are connected to the journal via a stream socket, this environment variable will contain information about the standard error stream, as that's usually the preferred destination for log data. (Note that typically the same stream is used for both standard output and standard error, hence very likely the environment variable contains device and inode information matching both stream file descriptors.) This environment variable is primarily useful to allow services to optionally upgrade their used log protocol to the native journal protocol (using `sd_journal_print(3)` and other functions) if their standard output or standard error output is connected to the journal anyway, thus enabling delivery of structured metadata along with logged messages. `$SERVICE_RESULT` Only used for the service unit type. This environment variable is passed to all `ExecStop=` and `ExecStopPost=` processes, and encodes the service "result". Currently, the following values are defined: | Value | Meaning | |----|----| | `success` | The service ran successfully and exited cleanly. | | `protocol` | A protocol violation occurred: the service did not take the steps required by its unit configuration (specifically what is configured in its `Type=` setting). | | `timeout` | One of the steps timed out. | | `exit-code` | Service process exited with a non-zero exit code; see `$EXIT_CODE` below for the actual exit code returned. | | `signal` | A service process was terminated abnormally by a signal, without dumping core. See `$EXIT_CODE` below for the actual signal causing the termination. | | `core-dump` | A service process terminated abnormally with a signal and dumped core. See `$EXIT_CODE` below for the signal causing the termination. | | `watchdog` | Watchdog keep-alive ping was enabled for the service, but the deadline was missed. | | `exec-condition` | Service did not run because `ExecCondition=` failed (that is its command exited with an exit status of 1 through 254 (inclusive)). | | `oom-kill` | A service process was terminated by the Out-Of-Memory (OOM) killer. | | `start-limit-hit` | A start limit was defined for the unit and it was hit, causing the unit to fail to start. See `systemd.unit(5)`'s `StartLimitIntervalSec=` and `StartLimitBurst=` for details. | | `resources` | A catch-all condition in case a system operation failed. | Defined `$SERVICE_RESULT` values This environment variable is useful to monitor failure or successful termination of a service. Even though this variable is available in both `ExecStop=` and `ExecStopPost=`, it is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services that managed to start up correctly, and the latter covers both services that failed during their start-up and those which failed during their runtime. `$EXIT_CODE`; `$EXIT_STATUS` Only defined for the service unit type. These environment variables are passed to all `ExecStop=`, `ExecStopPost=` processes and contain exit status/code information of the main process of the service. For the precise definition of the exit code and status, see `wait(2)`. `$EXIT_CODE` is one of `exited`, `killed`, `dumped`. `$EXIT_STATUS` contains the numeric exit code formatted as string if `$EXIT_CODE` is `exited`, and the signal name in all other cases. Note that these environment variables are only set if the service manager succeeded to start and identify the main process of the service.
Summary of possible service result variable values
$SERVICE_RESULT $EXIT_CODE $EXIT_STATUS
success killed HUP, INT, TERM, PIPE
exited 0
protocol not set not set
exited 0
timeout killed TERM, KILL
exited 0, 1, 2, 3, …, 255
exit-code exited 1, 2, 3, …, 255
signal killed HUP, INT, KILL, …
core-dump dumped ABRT, SEGV, QUIT, …
watchdog dumped ABRT
killed TERM, KILL
exited 0, 1, 2, 3, …, 255
exec-condition exited 1, 2, 3, 4, …, 254
oom-kill killed TERM, KILL
start-limit-hit not set not set
resources any of the above any of the above
Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the timeout and watchdog rows above only the signals that systemd sends have been included. Moreover, using SuccessExitStatus= additional exit statuses may be declared to indicate clean termination, which is not reflected by this table.
`$MONITOR_SERVICE_RESULT`; `$MONITOR_EXIT_CODE`; `$MONITOR_EXIT_STATUS`; `$MONITOR_INVOCATION_ID`; `$MONITOR_UNIT` Only defined for the service unit type. Those environment variables are passed to all `ExecStart=` and `ExecStartPre=` processes which run in services triggered by `OnFailure=` or `OnSuccess=` dependencies. Variables `$MONITOR_SERVICE_RESULT`, `$MONITOR_EXIT_CODE` and `$MONITOR_EXIT_STATUS` take the same values as for `ExecStop=` and `ExecStopPost=` processes. Variables `$MONITOR_INVOCATION_ID` and `$MONITOR_UNIT` are set to the invocation id and unit name of the service which triggered the dependency. Note that when multiple services specify the same unit as their `OnFailure=` or `OnSuccess=` handler, those variables will *not* be passed. Consider using a template handler unit for that case instead: `OnFailure=handler@%n.service` for non-templated units, or `OnFailure=handler@%p-%i.service` for templated units. `$PIDFILE` The path to the configured PID file, in case the process is forked off on behalf of a service that uses the `PIDFile=` setting, see `systemd.service(5)` for details. Service code may use this environment variable to automatically generate a PID file at the location configured in the unit file. This field is set to an absolute path in the file system. `$REMOTE_ADDR`; `$REMOTE_PORT` If this is a unit started via per-connection socket activation (i.e. via a socket unit with `Accept=yes`), these environment variables contain information about the remote peer of the socket connection. For IPv4 and IPv6 connections, `$REMOTE_ADDR` contains the IP address, and `$REMOTE_PORT` contains the port number of the remote peer. For `AF_UNIX` socket connections, `$REMOTE_ADDR` contains either the remote socket's file system path starting with a slash (`/`), its address in the abstract namespace starting with an at symbol (`@`), or is unset in case of an unnamed socket. `$REMOTE_PORT` is not set for `AF_UNIX` sockets. `$SO_COOKIE` If this is a unit started via per-connection socket activation (i.e. via a socket unit with `Accept=yes`), this environment variable contains the Linux socket cookie, formatted as decimal integer. The socket cookie can otherwise be acquired via `getsockopt(7)`. `$TRIGGER_UNIT`; `$TRIGGER_PATH`; `$TRIGGER_TIMER_REALTIME_USEC`; `$TRIGGER_TIMER_MONOTONIC_USEC` If the unit was activated dynamically (e.g.: a corresponding path unit or timer unit), the unit that triggered it and other type-dependent information will be passed via these variables. Note that this information is provided in a best-effort way. For example, multiple triggers happening one after another will be coalesced and only one will be reported, with no guarantee as to which one it will be. Because of this, in most cases this variable will be primarily informational, i.e. useful for debugging purposes, is lossy, and should not be relied upon to propagate a comprehensive reason for activation. `$MEMORY_PRESSURE_WATCH`; `$MEMORY_PRESSURE_WRITE` If memory pressure monitoring is enabled for this service unit, the path to watch and the data to write into it. See [Resource Pressure Handling](https://systemd.io/PRESSURE) for details about these variables and the service protocol data they convey. `$CPU_PRESSURE_WATCH`; `$CPU_PRESSURE_WRITE` If CPU pressure monitoring is enabled for this service unit, the path to watch and the data to write into it. See [Resource Pressure Handling](https://systemd.io/PRESSURE) for details about these variables and the service protocol data they convey. `$IO_PRESSURE_WATCH`; `$IO_PRESSURE_WRITE` If IO pressure monitoring is enabled for this service unit, the path to watch and the data to write into it. See [Resource Pressure Handling](https://systemd.io/PRESSURE) for details about these variables and the service protocol data they convey. `$FDSTORE` The maximum number of file descriptors that may be stored in the manager for the service. This variable is set when the file descriptor store is enabled for the service, i.e. `FileDescriptorStoreMax=` is set to a non-zero value (see `systemd.service(5)` for details). Applications may check this environment variable before sending file descriptors to the service manager via `sd_pid_notify_with_fds(3)`. `$DEBUG_INVOCATION` If `RestartMode=debug` is set, and a previous attempt at starting the unit failed, this variable will be passed to the service to indicate that additional logging should be enabled at startup. See `systemd.service(5)` for more details. For system services, when `PAMName=` is enabled and `pam_systemd` is part of the selected PAM stack, additional environment variables defined by systemd may be set for services. Specifically, these are `$XDG_SEAT`, `$XDG_VTNR`, see `pam_systemd(8)` for details. # Process Exit Codes When invoking a unit process the service manager possibly fails to apply the execution parameters configured with the settings above. In that case the already created service process will exit with a non-zero exit code before the configured command line is executed. (Or in other words, the child process possibly exits with these error codes, after having been created by the `fork(2)` system call, but before the matching `execve(2)` system call is called.) Specifically, exit codes defined by the C library, by the LSB specification and by the systemd service manager itself are used. The following basic service exit codes are defined by the C library. | Exit Code | Symbolic Name | Description | |-----------|----------------|---------------------------------------| | 0 | `EXIT_SUCCESS` | Generic success code. | | 1 | `EXIT_FAILURE` | Generic failure or unspecified error. | Basic C library exit codes The following service exit codes are defined by the [LSB specification](https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html). | Exit Code | Symbolic Name | Description | |-----------|------------------------|---------------------------------------| | 2 | `EXIT_INVALIDARGUMENT` | Invalid or excess arguments. | | 3 | `EXIT_NOTIMPLEMENTED` | Unimplemented feature. | | 4 | `EXIT_NOPERMISSION` | The user has insufficient privileges. | | 5 | `EXIT_NOTINSTALLED` | The program is not installed. | | 6 | `EXIT_NOTCONFIGURED` | The program is not configured. | | 7 | `EXIT_NOTRUNNING` | The program is not running. | LSB service exit codes The LSB specification suggests that error codes 200 and above are reserved for implementations. Some of them are used by the service manager to indicate problems during process invocation: | Exit Code | Symbolic Name | Description | |----|----|----| | 200 | `EXIT_CHDIR` | Changing to the requested working directory failed. See `WorkingDirectory=` above. | | 201 | `EXIT_NICE` | Failed to set up process scheduling priority (nice level). See `Nice=` above. | | 202 | `EXIT_FDS` | Failed to close unwanted file descriptors, or to adjust passed file descriptors. | | 203 | `EXIT_EXEC` | The actual process execution failed (specifically, the `execve(2)` system call). Most likely this is caused by a missing or non-accessible executable file. | | 204 | `EXIT_MEMORY` | Failed to perform an action due to memory shortage. | | 205 | `EXIT_LIMITS` | Failed to adjust resource limits. See `LimitCPU=` and related settings above. | | 206 | `EXIT_OOM_ADJUST` | Failed to adjust the OOM setting. See `OOMScoreAdjust=` above. | | 207 | `EXIT_SIGNAL_MASK` | Failed to set process signal mask. | | 208 | `EXIT_STDIN` | Failed to set up standard input. See `StandardInput=` above. | | 209 | `EXIT_STDOUT` | Failed to set up standard output. See `StandardOutput=` above. | | 210 | `EXIT_CHROOT` | Failed to change root directory (`chroot(2)`). See `RootDirectory=`/`RootImage=` above. | | 211 | `EXIT_IOPRIO` | Failed to set up IO scheduling priority. See `IOSchedulingClass=`/`IOSchedulingPriority=` above. | | 212 | `EXIT_TIMERSLACK` | Failed to set up timer slack. See `TimerSlackNSec=` above. | | 213 | `EXIT_SECUREBITS` | Failed to set process secure bits. See `SecureBits=` above. | | 214 | `EXIT_SETSCHEDULER` | Failed to set up CPU scheduling. See `CPUSchedulingPolicy=`/`CPUSchedulingPriority=` above. | | 215 | `EXIT_CPUAFFINITY` | Failed to set up CPU affinity. See `CPUAffinity=` above. | | 216 | `EXIT_GROUP` | Failed to determine or change group credentials. See `Group=`/`SupplementaryGroups=` above. | | 217 | `EXIT_USER` | Failed to determine or change user credentials, or to set up user namespacing. See `User=`/`PrivateUsers=` above. | | 218 | `EXIT_CAPABILITIES` | Failed to drop capabilities, or apply ambient capabilities. See `CapabilityBoundingSet=`/`AmbientCapabilities=` above. | | 219 | `EXIT_CGROUP` | Setting up the service control group failed. | | 220 | `EXIT_SETSID` | Failed to create new process session. | | 221 | `EXIT_CONFIRM` | Execution has been cancelled by the user. See the `systemd.confirm_spawn=` kernel command line setting on `kernel-command-line(7)` for details. | | 222 | `EXIT_STDERR` | Failed to set up standard error output. See `StandardError=` above. | | 224 | `EXIT_PAM` | Failed to set up PAM session. See `PAMName=` above. | | 225 | `EXIT_NETWORK` | Failed to set up network namespacing. See `PrivateNetwork=` above. | | 226 | `EXIT_NAMESPACE` | Failed to set up mount, UTS, or IPC namespacing. See `ReadOnlyPaths=`, `ProtectHostname=`, `PrivateIPC=`, and related settings above. | | 227 | `EXIT_NO_NEW_PRIVILEGES` | Failed to disable new privileges. See `NoNewPrivileges=yes` above. | | 228 | `EXIT_SECCOMP` | Failed to apply system call filters. See `SystemCallFilter=` and related settings above. | | 229 | `EXIT_SELINUX_CONTEXT` | Determining or changing SELinux context failed. See `SELinuxContext=` above. | | 230 | `EXIT_PERSONALITY` | Failed to set up an execution domain (personality). See `Personality=` above. | | 231 | `EXIT_APPARMOR_PROFILE` | Failed to prepare changing AppArmor profile. See `AppArmorProfile=` above. | | 232 | `EXIT_ADDRESS_FAMILIES` | Failed to restrict address families. See `RestrictAddressFamilies=` above. | | 233 | `EXIT_RUNTIME_DIRECTORY` | Setting up runtime directory failed. See `RuntimeDirectory=` and related settings above. | | 235 | `EXIT_CHOWN` | Failed to adjust socket ownership. Used for socket units only. | | 236 | `EXIT_SMACK_PROCESS_LABEL` | Failed to set SMACK label. See `SmackProcessLabel=` above. | | 237 | `EXIT_KEYRING` | Failed to set up kernel keyring. | | 238 | `EXIT_STATE_DIRECTORY` | Failed to set up unit's state directory. See `StateDirectory=` above. | | 239 | `EXIT_CACHE_DIRECTORY` | Failed to set up unit's cache directory. See `CacheDirectory=` above. | | 240 | `EXIT_LOGS_DIRECTORY` | Failed to set up unit's logging directory. See `LogsDirectory=` above. | | 241 | `EXIT_CONFIGURATION_DIRECTORY` | Failed to set up unit's configuration directory. See `ConfigurationDirectory=` above. | | 242 | `EXIT_NUMA_POLICY` | Failed to set up unit's NUMA memory policy. See `NUMAPolicy=` and `NUMAMask=` above. | | 243 | `EXIT_CREDENTIALS` | Failed to set up unit's credentials. See `ImportCredential=`, `LoadCredential=` and `SetCredential=` above. | | 245 | `EXIT_BPF` | Failed to apply BPF restrictions. See `RestrictFileSystems=` above. | systemd-specific exit codes Finally, the BSD operating systems define a set of exit codes, typically defined on Linux systems too: | Exit Code | Symbolic Name | Description | |-----------|------------------|---------------------------------------------| | 64 | `EX_USAGE` | Command line usage error | | 65 | `EX_DATAERR` | Data format error | | 66 | `EX_NOINPUT` | Cannot open input | | 67 | `EX_NOUSER` | Addressee unknown | | 68 | `EX_NOHOST` | Host name unknown | | 69 | `EX_UNAVAILABLE` | Service unavailable | | 70 | `EX_SOFTWARE` | internal software error | | 71 | `EX_OSERR` | System error (e.g., cannot fork) | | 72 | `EX_OSFILE` | Critical OS file missing | | 73 | `EX_CANTCREAT` | Cannot create (user) output file | | 74 | `EX_IOERR` | Input/output error | | 75 | `EX_TEMPFAIL` | Temporary failure; user is invited to retry | | 76 | `EX_PROTOCOL` | Remote error in protocol | | 77 | `EX_NOPERM` | Permission denied | | 78 | `EX_CONFIG` | Configuration error | BSD exit codes # Examples
`$MONITOR_*` usage
A service `myfailer.service` which can trigger an `OnFailure=` dependency. [Unit] Description=Service which can trigger an OnFailure= dependency OnFailure=myhandler.service [Service] ExecStart=/bin/myprogram A service `mysuccess.service` which can trigger an `OnSuccess=` dependency. [Unit] Description=Service which can trigger an OnSuccess= dependency OnSuccess=myhandler.service [Service] ExecStart=/bin/mysecondprogram A service `myhandler.service` which can be triggered by any of the above services. [Unit] Description=Acts on service failing or succeeding [Service] ExecStart=/bin/bash -c "echo $MONITOR_SERVICE_RESULT $MONITOR_EXIT_CODE $MONITOR_EXIT_STATUS $MONITOR_INVOCATION_ID $MONITOR_UNIT" If `myfailer.service` were to run and exit in failure, then `myhandler.service` would be triggered and the monitor variables would be set as follows: MONITOR_SERVICE_RESULT=exit-code MONITOR_EXIT_CODE=exited MONITOR_EXIT_STATUS=1 MONITOR_INVOCATION_ID=cc8fdc149b2b4ca698d4f259f4054236 MONITOR_UNIT=myfailer.service If `mysuccess.service` were to run and exit in success, then `myhandler.service` would be triggered and the monitor variables would be set as follows: MONITOR_SERVICE_RESULT=success MONITOR_EXIT_CODE=exited MONITOR_EXIT_STATUS=0 MONITOR_INVOCATION_ID=6ab9af147b8c4a3ebe36e7a5f8611697 MONITOR_UNIT=mysuccess.service
# See Also `systemd(1)`, `systemctl(1)`, `systemd-analyze(1)`, `journalctl(1)`, `systemd-system.conf(5)`, `systemd.unit(5)`, `systemd.service(5)`, `systemd.socket(5)`, `systemd.swap(5)`, `systemd.mount(5)`, `systemd.kill(5)`, `systemd.resource-control(5)`, `systemd.time(7)`, `systemd.directives(7)`, `tmpfiles.d(5)`, `exec(3)`, `fork(2)` # systemd.image-filter systemd systemd.image-filter 7 systemd.image-filter Disk Image Dissection Filter # Description In systemd, whenever a disk image (DDI) implementing the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification) is activated, a filter may be specified controlling which partitions to consider for mounting. Such a disk image dissection filter is a string that contains per-partition-type patterns, separated by colons (`:`). The individual rules consist of a partition identifier, an equal sign (`=`), and a shell globbing pattern applied to the GPT label string of the partition. See `glob(7)` for details on shell globbing. The partition identifiers currently defined are: `root`, `usr`, `home`, `srv`, `esp`, `xbootldr`, `swap`, `root-verity`, `root-verity-sig`, `usr-verity`, `usr-verity-sig`, `tmp`, `var`. You can abbreviate the `-verity` and `-verity-sig` suffixes as `-vty` and `-vsig`, for example `usr-vsig`. These identifiers match the relevant partition types in the Discoverable Partitions Specification, but are agnostic to CPU architectures. # Use Various systemd components that support operating with disk images support a `--image-filter=` command line option to specify the image filter to use. If no filter is specified all partitions in partition table are considered and no per-label filtering is applied (except that partitions with the `_empty` label are always ignored). For the host root file system image itself `systemd-gpt-auto-generator(8)` is responsible for processing the GPT partition table and making use of the included discoverable partitions. It accepts an image filter via the kernel command line option `systemd.image_filter=`. # Examples The following image filter string dictates that for the root file system partition only partitions shall be considered whose label begins with `ParticleOS-`. For the `/usr/` partition the precise label `ParticleOS_47110815` is required. root=ParticleOS-*:usr=ParticleOS_47110815 # See Also `systemd(1)`, `systemd-dissect(1)`, `systemd-gpt-auto-generator(8)`, `systemd.image-policy(7)` # systemd.image-policy systemd systemd.image-policy 7 systemd.image-policy Disk Image Dissection Policy # Description In systemd, whenever a disk image (DDI) implementing the [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification) is activated, a policy may be specified controlling which partitions to mount and what kind of cryptographic protection to require, and which type of filesystem is allowed. Such a disk image dissection policy is a string that contains per-partition-type rules, separated by colons (`:`). The individual rules consist of a partition identifier, an equal sign (`=`), and one or more flags which may be set per partition. If multiple flags are specified per partition they are separated by a plus sign (`+`). The partition identifiers currently defined are: `root`, `usr`, `home`, `srv`, `esp`, `xbootldr`, `swap`, `root-verity`, `root-verity-sig`, `usr-verity`, `usr-verity-sig`, `tmp`, `var`. You can abbreviate the `-verity` and `-verity-sig` suffixes as `-vty` and `-vsig`, for example `usr-vsig`. These identifiers match the relevant partition types in the Discoverable Partitions Specification, but are agnostic to CPU architectures. If the partition identifier is left empty it defines the *default* policy for partitions defined in the Discoverable Partitions Specification for which no policy flags are explicitly listed in the policy string. The following partition policy flags are defined that dictate the existence/absence, the use, and the protection level of partitions: - `unprotected` for partitions that shall exist and be used, but shall come without cryptographic protection, lacking both Verity authentication and LUKS encryption. - `verity` for partitions that shall exist and be used, with Verity authentication. (Note: if a DDI image carries a data partition, along with a Verity partition and a signature partition for it, and only the `verity` flag is set (`signed` is not), then the image will be set up with Verity, but the signature data will not be used. Or in other words: any DDI with a set of partitions that qualify for `signature` also implicitly qualifies for `verity`, and in fact also `unprotected`). - `signed` for partitions that shall exist and be used, with Verity authentication, which are also accompanied by a PKCS#7 signature of the Verity root hash. The signature must be valid for a key in the kernel keyring or a certificate in `/etc/verity.d/` (and related directories). If `verity` is set as well, a partition with a missing or invalid signature is set up with Verity authentication alone. To require a valid signature, set `signed` without `verity`. - `encrypted` for partitions which shall exist and be used and are encrypted with LUKS. - `unused` for partitions that shall exist but shall not be used. - `absent` for partitions that shall not exist on the image. The following filesystem policy flags are defined that dictate which filesystem types are allowed for which partition: | Filesystem flag | |-----------------| | `btrfs` | | `erofs` | | `ext4` | | `f2fs` | | `squashfs` | | `vfat` | | `xfs` | Filesystems types supported by the policy By setting a combination of the flags above, alternatives can be declared. For example the combination `unused+absent` means: the partition may exist (in which case it shall not be used) or may be absent. The combination of `unprotected+verity+signed+encrypted+unused+absent` may be specified via the special shortcut `open`, and indicates that the partition may exist or may be absent, but if it exists is used, regardless of the protection level. As special rule: if none of the flags above are set for a listed partition identifier, the default policy of `open` is implied, i.e. setting none of these flags listed above means effectively all flags listed above will be set. The following partition policy flags are defined that dictate the state of specific GPT partition flags: - `read-only-off`, `read-only-on` to require that the partitions have the read-only partition flag off or on. - `growfs-off`, `growfs-on` to require that the partitions have the growfs partition flag off or on. If both `read-only-off` and `read-only-on` are set for a partition, then the state of the read-only flag on the partition is not dictated by the policy. Setting neither flag is equivalent to setting both, i.e. setting neither of these two flags means effectively both will be set. A similar logic applies to `growfs-off`/`growfs-on`. If partitions are not listed within an image policy string, the default policy flags are applied (configurable via an empty partition identifier, see above). If no default policy flags are configured in the policy string, it is implied to be `absent+unused`, except for the Verity partition and their signature partitions where the policy is automatically derived from minimal protection level of the data partition they protect, as encoded in the policy. # Special Policies The special image policy string `*` is short for "use everything", i.e. is equivalent to: =verity+signed+encrypted+unprotected+unused+absent The special image policy string `-` is short for "use nothing", i.e. is equivalent to: =unused+absent The special image policy string `~` is short for "everything must be absent", i.e. is equivalent to: =absent # Use Most systemd components that support operating with disk images support a `--image-policy=` command line option to specify the image policy to use, and default to relatively open policies (typically the `*` policy, as described above), under the assumption that trust in disk images is established before the images are passed to the program in question. For the host image itself `systemd-gpt-auto-generator(8)` is responsible for processing the GPT partition table and making use of the included discoverable partitions. It accepts an image policy via the kernel command line option `systemd.image_policy=`. Note that image policies do not dictate how the components will mount and use disk images — they only dictate which parts to avoid and which protection level and arrangement to require while mounting/using them. For example, `systemd-sysext(8)` only cares for the `/usr/` and `/opt/` trees inside a disk image, and thus ignores any `/home/` partitions (and similar) in all cases, which might be included in the image, regardless whether the configured image policy would allow access to it or not. Similar, `systemd-nspawn(1)` is not going to make use of any discovered swap device, regardless of whether the policy would allow that or not. Use the `image-policy` command of the `systemd-analyze(1)` tool to analyze image policy strings, and determine what a specific policy string means for a specific partition. # Examples The following image policy string dictates one read-only Verity-enabled `/usr/` partition must exist, plus encrypted root and swap partitions. All other partitions are ignored: usr=verity+read-only-on:root=encrypted:swap=encrypted The following image policy string dictates an encrypted, writable root file system, and optional `/srv/` file system that must be encrypted if it exists and no swap partition may exist: root=encrypted+read-only-off:srv=encrypted+absent:swap=absent The following image policy string dictates a single root partition that may be encrypted, but does not have to be, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption. root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent The following image policy string dictates a single root partition that can only be erofs or squashfs, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption. root=erofs+squashfs:swap=absent+unused:=unprotected+encrypted+absent # See Also `systemd(1)`, `systemd-dissect(1)`, `systemd-gpt-auto-generator(8)`, `systemd-sysext(8)`, `systemd-analyze(1)` # systemd.journal-fields systemd systemd.journal-fields 7 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. `INVOCATION_ID=`; `USER_INVOCATION_ID=` A randomized, unique 128-bit ID identifying each runtime cycle of the unit. This is different from `_SYSTEMD_INVOCATION_ID` in that it is only used for messages coming from systemd code (e.g. logs from the system/user manager or from forked processes performing systemd-related setup). `SYSLOG_FACILITY=`; `SYSLOG_IDENTIFIER=`; `SYSLOG_PID=`; `SYSLOG_TIMESTAMP=` Syslog compatibility fields containing the facility (formatted as decimal string), the identifier string (i.e. "tag"), the client PID, and the timestamp as specified in the original datagram. (Note that the tag is usually derived from glibc's `program_invocation_short_name` variable, see `program_invocation_short_name(3)`.) Note that the journal service does not validate the values of any structured journal fields whose name is not prefixed with an underscore, and this includes any syslog related fields such as these. Hence, applications that supply a facility, PID, or log level are expected to do so properly formatted, i.e. as 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=`. `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. `TID=` The numeric thread ID (TID) the log message originates from. `UNIT=`; `USER_UNIT=` The name of a unit. Used by the system and user managers when logging about specific units. When `--unit=name` or `--user-unit=name` are used with `journalctl(1)`, a match pattern that includes `UNIT=name.service` or `USER_UNIT=name.service` will be generated. # Trusted Journal Fields Fields prefixed with an underscore are trusted fields, i.e. fields that are implicitly added by the journal and cannot be altered by client code. `_PID=`; `_UID=`; `_GID=` The process 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. `_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=`. `_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)`). `_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 `driver` for internally generated messages `syslog` for those received via the local syslog socket with the syslog protocol `journal` for those received via the native journal protocol `stdout` for those read from a service's standard output or error output `kernel` for those read from the kernel `_STREAM_ID=` Only applies to `_TRANSPORT=stdout` records: specifies a randomized 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. `_LINE_BREAK=` Only applies to `_TRANSPORT=stdout` records: indicates that the log message in the standard output/error stream was not terminated with a normal newline character (`\n`, i.e. ASCII 10). Specifically, when set this field is one of `nul` (in case the line was terminated by a `NUL` byte), `line-max` (in case the maximum log line length was reached, as configured with `LineMax=` in `journald.conf(5)`), `eof` (if this was the last log record of a stream and the stream ended without a final newline character), or `pid-change` (if the process which generated the log output changed in the middle of a line). Note that this record is not generated when a normal newline character was used for marking the log line end. `_NAMESPACE=` If this file was written by a `systemd-journald` instance managing a journal namespace that is not the default, this field contains the namespace identifier. See `systemd-journald.service(8)` for details about journal namespaces. `_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. `_REMOTE_CERTIFICATE_SUBJECT=` The full distinguished name of the verified HTTPS uploader's certificate. Added by `systemd-journal-remote` with `AddClientCertificateSubject=yes`; see `journal-remote.conf(5)`. Trust this field only from a receiver with this setting enabled. It identifies the immediate uploader, not the original producer of forwarded entries, and does not authenticate other entry fields. # Kernel Journal Fields Kernel fields are fields that are used by messages originating in the kernel and stored in the journal. `_KERNEL_DEVICE=` The kernel device name. If the entry is associated to a block device, contains the major and minor numbers of the device node, separated by `:` and prefixed by `b`. Similarly for character devices, but prefixed by `c`. For network devices, this is the interface index prefixed by `n`. For all other devices, this is the subsystem name prefixed by `+`, followed by `:`, followed by the kernel device name. `_KERNEL_SUBSYSTEM=` The kernel subsystem name. `_UDEV_SYSNAME=` The kernel device name as it shows up in the device tree below `/sys/`. `_UDEV_DEVNODE=` The device node path of this device in `/dev/`. `_UDEV_DEVLINK=` Additional symlink names pointing to the device node in `/dev/`. This field is frequently set more than once per entry. # Fields to log on behalf of a different program Fields in this section are used by programs to specify that they are logging on behalf of another program or unit. Fields used by the `systemd-coredump` coredump kernel helper: `COREDUMP_UNIT=`; `COREDUMP_USER_UNIT=` Used to annotate messages containing coredumps from system and session units. See `coredumpctl(1)`. Privileged programs (currently UID 0) may attach `OBJECT_PID=` to a message. This will instruct `systemd-journald` to attach additional fields on behalf of the caller: `OBJECT_PID=PID` PID of the program that this message pertains to. `OBJECT_UID=`; `OBJECT_GID=`; `OBJECT_COMM=`; `OBJECT_EXE=`; `OBJECT_CMDLINE=`; `OBJECT_AUDIT_SESSION=`; `OBJECT_AUDIT_LOGINUID=`; `OBJECT_SYSTEMD_CGROUP=`; `OBJECT_SYSTEMD_SESSION=`; `OBJECT_SYSTEMD_OWNER_UID=`; `OBJECT_SYSTEMD_UNIT=`; `OBJECT_SYSTEMD_USER_UNIT=` These are additional fields added automatically by `systemd-journald`. Their meaning is the same as `_UID=`, `_GID=`, `_COMM=`, `_EXE=`, `_CMDLINE=`, `_AUDIT_SESSION=`, `_AUDIT_LOGINUID=`, `_SYSTEMD_CGROUP=`, `_SYSTEMD_SESSION=`, `_SYSTEMD_UNIT=`, `_SYSTEMD_USER_UNIT=`, and `_SYSTEMD_OWNER_UID=` as described above, except that the process identified by \ is described, instead of the process which logged the message. `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. # Address Fields During serialization into external formats, such as the [Journal Export Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format) or the [Journal JSON Format](https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format), 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. # See Also `systemd(1)`, `systemd-journald.service(8)`, `journalctl(1)`, `journald.conf(5)`, `sd-journal(3)`, `coredumpctl(1)`, `systemd.directives(7)` # systemd.kill systemd systemd.kill 5 systemd.kill Process killing procedure configuration `service.service`, `socket.socket`, `mount.mount`, `swap.swap`, `scope.scope` # Description Unit configuration files for services, sockets, mount points, swap devices and scopes share a subset of configuration options which define the killing procedure of processes belonging to the unit. This man page lists the configuration options shared by these five unit types. See `systemd.unit(5)` for the common options shared by all unit configuration files, and `systemd.service(5)`, `systemd.socket(5)`, `systemd.swap(5)`, `systemd.mount(5)` and `systemd.scope(5)` for more information on the configuration file options specific to each unit type. The kill procedure configuration options are configured in the \[Service\], \[Socket\], \[Mount\] or \[Swap\] section, depending on the unit type. # Options `KillMode=` Specifies how processes of this unit shall be killed. One of `control-group`, `mixed`, `process`, `none`. If set to `control-group`, all remaining processes in the control group of this unit will be killed on unit stop (for services: after the stop command is executed, as configured with `ExecStop=`). If set to `mixed`, the `SIGTERM` signal (see below) is sent to the main process while the subsequent `SIGKILL` signal (see below) is sent to all remaining processes of the unit's control group. If set to `process`, only the main process itself is killed (not recommended!). If set to `none`, no process is killed (strongly recommended against!). In this case, only the stop command will be executed on unit stop, but no process will be killed otherwise. Processes remaining alive after stop are left in their control group and the control group continues to exist after stop unless empty. Note that it is not recommended to set `KillMode=` to `process` or even `none`, as this allows processes to escape the service manager's lifecycle and resource management, and to remain running even while their service is considered stopped and is assumed to not consume any resources. Processes will first be terminated via `SIGTERM` (unless the signal to send is changed via `KillSignal=` or `RestartKillSignal=`). Optionally, this is immediately followed by a `SIGHUP` (if enabled with `SendSIGHUP=`). If processes still remain after: - the main process of a unit has exited (applies to `KillMode=`: `mixed`) - the delay configured via the `TimeoutStopSec=` has passed (applies to `KillMode=`: `control-group`, `mixed`, `process`) the termination request is repeated with the `SIGKILL` signal or the signal specified via `FinalKillSignal=` (unless this is disabled via the `SendSIGKILL=` option). See `kill(2)` for more information. Defaults to `control-group`. `KillSignal=` Specifies which signal to use when stopping a service. This controls the signal that is sent as first step of shutting down a unit (see above), and is usually followed by `SIGKILL` (see above and below). For a list of valid signals, see `signal(7)`. Defaults to `SIGTERM`. Note that, right after sending the signal specified in this setting, systemd will always send `SIGCONT`, to ensure that even suspended tasks can be terminated cleanly. `RestartKillSignal=` Specifies which signal to use when restarting a service. The same as `KillSignal=` described above, with the exception that this setting is used in a restart job. Not set by default, and the value of `KillSignal=` is used. `SendSIGHUP=` Specifies whether to send `SIGHUP` to remaining processes immediately after sending the signal configured with `KillSignal=`. This is useful to indicate to shells and shell-like programs that their connection has been severed. Takes a boolean value. Defaults to `no`. `SendSIGKILL=` Specifies whether to send `SIGKILL` (or the signal specified by `FinalKillSignal=`) to remaining processes after a timeout, if the normal shutdown procedure left processes of the service around. When disabled, a `KillMode=` of `control-group` or `mixed` service will not restart if processes from prior services exist within the control group. Takes a boolean value. Defaults to `yes`. `FinalKillSignal=` Specifies which signal to send to remaining processes after a timeout if `SendSIGKILL=` is enabled. The signal configured here should be one that is not typically caught and processed by services (`SIGTERM` is not suitable). Developers can find it useful to use this to generate a coredump to troubleshoot why a service did not terminate upon receiving the initial `SIGTERM` signal. This can be achieved by configuring `LimitCORE=` and setting `FinalKillSignal=` to either `SIGQUIT` or `SIGABRT`. Defaults to `SIGKILL`. `WatchdogSignal=` Specifies which signal to use to terminate the service when the watchdog timeout expires (enabled through `WatchdogSec=`). Defaults to `SIGABRT`. # See Also `systemd(1)`, `systemctl(1)`, `journalctl(1)`, `systemd.unit(5)`, `systemd.service(5)`, `systemd.socket(5)`, `systemd.swap(5)`, `systemd.mount(5)`, `systemd.exec(5)`, `systemd.directives(7)`, `kill(2)`, `signal(7)` # systemd.link systemd systemd.link 5 systemd.link Network device configuration `link.link` # Description A plain ini-style text file that encodes configuration for matching network devices, used by `systemd-udevd(8)` and in particular its `net_setup_link` builtin. See `systemd.syntax(7)` for a general description of the syntax. Note that some distributions may incorporate `.link` files in their early boot facilities (e.g. by including copies of the `.link` files in initramfs). As such it may be necessary to take manual steps to ensure that any local changes are consistent with early-boot storage facilities. The relevant distribution-specific documentation should be consulted. The `.link` files are read from the files located in the system network directory `/usr/lib/systemd/network` and `/usr/local/lib/systemd/network` , the volatile runtime network directory `/run/systemd/network`, and the local administration network directory `/etc/systemd/network`. All configuration files are collectively sorted and processed in alphanumeric order, regardless of the directories in which they live. However, files with identical filenames replace each other. It is recommended that each filename is prefixed with a number smaller than `70` (e.g. `10-eth0.link`). Otherwise, the default `.link` files or those generated by `systemd-network-generator.service(8)` may take precedence over user configured files. Files in `/etc/` have the highest priority, files in `/run/` take precedence over files with the same name in `/usr/lib/`. This can be used to override a system-supplied link file with a local file if needed. As a special case, an empty file (file size 0) or symlink with the same name pointing to `/dev/null` disables the configuration file entirely (it is "masked"). Along with the link file `foo.link`, a "drop-in" directory `foo.link.d/` may exist. All files with the suffix `.conf` from this directory will be merged in the alphanumeric order and parsed after the main file itself has been parsed. This is useful to alter or add configuration settings, without having to modify the main configuration file. Each drop-in file must have appropriate section headers. In addition to `/etc/systemd/network`, drop-in `.d` directories can be placed in `/usr/lib/systemd/network` or `/run/systemd/network` directories. Drop-in files in `/etc/` take precedence over those in `/run/` which in turn take precedence over those in `/usr/lib/`. Drop-in files under any of these directories take precedence over the main link file wherever located. The link file contains a \[Match\] section, which determines if a given link file may be applied to a given device, as well as a \[Link\] section specifying how the device should be configured. The first (in lexicographic order) of the link files that matches a given device is applied. Note that a default file `99-default.link` is shipped by the system. Any user-supplied `.link` should hence have a lexicographically earlier name to be considered at all. See `udevadm(8)` for diagnosing problems with `.link` files. # \[Match\] Section Options A link file is said to match an interface if all matches specified by the \[Match\] section are satisfied. When a link file does not contain valid settings in \[Match\] section, then the file will match all interfaces and `systemd-udevd` warns about that. Hint: to avoid the warning and to make it clear that all interfaces shall be matched, add the following: OriginalName=* The first (in alphanumeric order) of the link files that matches a given interface is applied, all later files are ignored, even if they match as well. The following keys are accepted: `MACAddress=` A whitespace-separated list of hardware addresses. The acceptable formats are: `colon-delimited hexadecimal` Each field must be one byte. E.g. `12:34:56:78:90:ab` or `AA:BB:CC:DD:EE:FF`. `hyphen-delimited hexadecimal` Each field must be one byte. E.g. `12-34-56-78-90-ab` or `AA-BB-CC-DD-EE-FF`. `dot-delimited hexadecimal` Each field must be two bytes. E.g. `1234.5678.90ab` or `AABB.CCDD.EEFF`. `IPv4 address format` E.g. `127.0.0.1` or `192.168.0.1`. `IPv6 address format` E.g. `2001:0db8:85a3::8a2e:0370:7334` or `::1`. The total length of each MAC address must be 4 (for IPv4 tunnel), 6 (for Ethernet), 16 (for IPv6 tunnel), or 20 (for InfiniBand). This option may appear more than once, in which case the lists are merged. If the empty string is assigned to this option, the list of hardware addresses defined prior to this is reset. Defaults to unset. `PermanentMACAddress=` A whitespace-separated list of hardware's permanent addresses. While `MACAddress=` matches the device's current MAC address, this matches the device's permanent MAC address, which may be different from the current one. Use full colon-, hyphen- or dot-delimited hexadecimal, or IPv4 or IPv6 address format. This option may appear more than once, in which case the lists are merged. If the empty string is assigned to this option, the list of hardware addresses defined prior to this is reset. Defaults to unset. `Path=` A whitespace-separated list of shell-style globs matching the persistent path, as exposed by the udev property `ID_PATH`. `Driver=` A whitespace-separated list of shell-style globs matching the driver currently bound to the device, as exposed by the udev property `ID_NET_DRIVER` of its parent device, or if that is not set, the driver as exposed by `ethtool -i` of the device itself. If the list is prefixed with a "!", the test is inverted. `Type=` A whitespace-separated list of shell-style globs matching the device type, as exposed by `networkctl list`. If the list is prefixed with a "!", the test is inverted. Some valid values are `ether`, `loopback`, `wlan`, `wwan`. Valid types are named either from the udev `DEVTYPE` attribute, or `ARPHRD_` macros in `linux/if_arp.h`, so this is not comprehensive. `Kind=` A whitespace-separated list of shell-style globs matching the device kind, as exposed by `networkctl status INTERFACE` or `ip -d link show INTERFACE`. If the list is prefixed with a "!", the test is inverted. Some valid values are `bond`, `bridge`, `gre`, `tun`, `veth`. Valid kinds are given by netlink's `IFLA_INFO_KIND` attribute, so this is not comprehensive. `Property=` A whitespace-separated list of udev property names with their values after equals sign (`=`). If multiple properties are specified, the test results are ANDed. If the list is prefixed with a "!", the test is inverted. If a value contains white spaces, then please quote whole key and value pair. If a value contains quotation, then please escape the quotation with `\`. Example: if a .link file has the following: Property=ID_MODEL_ID=9999 "ID_VENDOR_FROM_DATABASE=vendor name" "KEY=with \"quotation\"" then, the .link file matches only when an interface has all the above three properties. `OriginalName=` A whitespace-separated list of shell-style globs matching the device name, as exposed by the udev property "INTERFACE". This cannot be used to match on names that have already been changed from userspace. Caution is advised when matching on kernel-assigned names, as they are known to be unstable between reboots. `Host=` Matches against the hostname or machine ID of the host. See `ConditionHost=` in `systemd.unit(5)` for details. When prefixed with an exclamation mark (`!`), the result is negated. If an empty string is assigned, the previously assigned value is cleared. `Virtualization=` Checks whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation. See `ConditionVirtualization=` in `systemd.unit(5)` for details. When prefixed with an exclamation mark (`!`), the result is negated. If an empty string is assigned, the previously assigned value is cleared. `KernelCommandLine=` Checks whether a specific kernel command line option is set. See `ConditionKernelCommandLine=` in `systemd.unit(5)` for details. When prefixed with an exclamation mark (`!`), the result is negated. If an empty string is assigned, the previously assigned value is cleared. `KernelVersion=` Checks whether the kernel version (as reported by `uname -r`) matches a certain expression. See `ConditionKernelVersion=` in `systemd.unit(5)` for details. When prefixed with an exclamation mark (`!`), the result is negated. If an empty string is assigned, the previously assigned value is cleared. `Version=` Checks whether a software version matches a certain expression. See `ConditionVersion=` in `systemd.unit(5)` for details. When prefixed with an exclamation mark (`!`), the result is negated. If an empty string is assigned, the previously assigned value is cleared. `Credential=` Checks whether the specified credential was passed to the `systemd-udevd.service` service. See [System and Service Credentials](https://systemd.io/CREDENTIALS) for details. When prefixed with an exclamation mark (`!`), the result is negated. If an empty string is assigned, the previously assigned value is cleared. `Architecture=` Checks whether the system is running on a specific architecture. See `ConditionArchitecture=` in `systemd.unit(5)` for details. When prefixed with an exclamation mark (`!`), the result is negated. If an empty string is assigned, the previously assigned value is cleared. `Firmware=` Checks whether the system is running on a machine with the specified firmware. See `ConditionFirmware=` in `systemd.unit(5)` for details. When prefixed with an exclamation mark (`!`), the result is negated. If an empty string is assigned, the previously assigned value is cleared. `MachineTag=` Matches against the tags assigned to the local machine. See `ConditionMachineTag=` in `systemd.unit(5)` for details. When prefixed with an exclamation mark (`!`), the result is negated. If an empty string is assigned, the previously assigned value is cleared. # \[Link\] Section Options The \[Link\] section accepts the following keys: `Description=` A description of the device. `Property=` Set specified udev properties. This takes space separated list of key-value pairs concatenated with equal sign (`=`). Example: Property=HOGE=foo BAR=baz This option supports simple specifier expansion, see the Specifiers section below. This option can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. This setting is useful to configure the `ID_NET_MANAGED_BY=` property which declares which network management service shall manage the interface, which is respected by `systemd-networkd(8)` and others. Use Property=ID_NET_MANAGED_BY=io.systemd.Network to declare explicitly that `systemd-networkd` shall manage the interface, or set the property to something else to declare explicitly it shall not do so. See `systemd.network(5)` for details how this property is used to match interface names. `ImportProperty=` Import specified udev properties from the saved database. This takes space separated list of property names. Example: ImportProperty=HOGE BAR This option supports simple specifier expansion, see the Specifiers section below. This option can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. If the same property is also set in `Property=` in the above, then the imported property value will be overridden by the value specified in `Property=`. `UnsetProperty=` Unset specified udev properties. This takes space separated list of property names. Example: UnsetProperty=HOGE BAR This option supports simple specifier expansion, see the Specifiers section below. This option can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. This setting is applied after `ImportProperty=` and `Property=` are applied. Hence, if the same property is specified in `ImportProperty=` or `Property=`, then the imported or specified property value will be ignored, and the property will be unset. `Alias=` The `ifalias` interface property is set to this value. `MACAddressPolicy=` The policy by which the MAC address should be set. The available policies are: `persistent` If the hardware has a persistent MAC address, as most hardware should, and if it is used by the kernel, nothing is done. Otherwise, a new MAC address is generated which is guaranteed to be the same on every boot for the given machine and the given device, but which is otherwise random. This feature depends on ID_NET_NAME\_\* properties to exist for the link. On hardware where these properties are not set, the generation of a persistent MAC address will fail. `random` If the kernel is using a random MAC address, nothing is done. Otherwise, a new address is randomly generated each time the device appears, typically at boot. Either way, the random address will have the `unicast` and `locally administered` bits set. `none` Keeps the MAC address assigned by the kernel. Or use the MAC address specified in `MACAddress=`. An empty string assignment is equivalent to setting `none`. `MACAddress=` The interface MAC address to use. For this setting to take effect, `MACAddressPolicy=` must either be unset, empty, or `none`. `NamePolicy=` An ordered, space-separated list of policies by which the interface name should be set. `NamePolicy=` may be disabled by specifying `net.ifnames=0` on the kernel command line. Each of the policies may fail, and the first successful one is used. The name is not set directly, but is exported to udev as the property `ID_NET_NAME`, which is, by default, used by a `udev(7)`, rule to set `NAME`. The available policies are: `kernel` If the kernel claims that the name it has set for a device is predictable, then no renaming is performed. `database` The name is set based on entries in the udev's Hardware Database with the key `ID_NET_NAME_FROM_DATABASE`. `onboard` The name is set based on information given by the firmware for on-board devices, as exported by the udev property `ID_NET_NAME_ONBOARD`. See `systemd.net-naming-scheme(7)`. `slot` The name is set based on information given by the firmware for hot-plug devices, as exported by the udev property `ID_NET_NAME_SLOT`. See `systemd.net-naming-scheme(7)`. `path` The name is set based on the device's physical location, as exported by the udev property `ID_NET_NAME_PATH`. See `systemd.net-naming-scheme(7)`. `mac` The name is set based on the device's persistent MAC address, as exported by the udev property `ID_NET_NAME_MAC`. See `systemd.net-naming-scheme(7)`. `keep` If the device already had a name given by userspace (as part of creation of the device or a rename), keep it. `Name=` The interface name to use. This option has lower precedence than `NamePolicy=`, so for this setting to take effect, `NamePolicy=` must either be unset, empty, disabled, or all policies configured there must fail. Also see the example below with `Name=dmz0`. Note that specifying a name that the kernel might use for another interface (for example `eth0`) is dangerous because the name assignment done by udev will race with the assignment done by the kernel, and only one interface may use the name. Depending on the order of operations, either udev or the kernel will win, making the naming unpredictable. It is best to use some different prefix, for example `internal0`/`external0` or `lan0`/`lan1`/`lan3`. Interface names must have a minimum length of 1 character and a maximum length of 15 characters, and may contain any 7bit ASCII character, with the exception of control characters, `:`, `/` and `%`. While `.` is an allowed character, it is recommended to avoid it when naming interfaces as various tools (such as `resolvconf(1)`) use it as separator character. Also, fully numeric interface names are not allowed (in order to avoid ambiguity with interface specification by numeric indexes), nor are the special strings `.`, `..`, `all` and `default`. `AlternativeNamesPolicy=` A space-separated list of policies by which the interface's alternative names should be set. Each of the policies may fail, and all successful policies are used. The available policies are `database`, `onboard`, `slot`, `path`, and `mac`. If the kernel does not support the alternative names, then this setting will be ignored. `AlternativeName=` The alternative interface name to use. This option can be specified multiple times. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect. If the kernel does not support the alternative names, then this setting will be ignored. Alternative interface names may be used to identify interfaces in various tools. In contrast to the primary name (as configured with `Name=` above) there may be multiple alternative names referring to the same interface. Alternative names may have a maximum length of 127 characters, in contrast to the 15 allowed for the primary interface name, but otherwise are subject to the same naming constraints. `TransmitQueues=` Specifies the device's number of transmit queues. An integer in the range 1…16384. When unset, the kernel's default will be used. `ReceiveQueues=` Specifies the device's number of receive queues. An integer in the range 1…16384. When unset, the kernel's default will be used. `TransmitQueueLength=` Specifies the transmit queue length of the device in number of packets. An unsigned integer in the range 0…4294967294. When unset, the kernel's default will be used. `MTUBytes=` The maximum transmission unit in bytes to set for the device. The usual suffixes K, M, G are supported and are understood to the base of 1024. `BitsPerSecond=` The speed to set for the device, the value is rounded down to the nearest Mbps. The usual suffixes K, M, G are supported and are understood to the base of 1000. `Duplex=` The duplex mode to set for the device. The accepted values are `half` and `full`. `AutoNegotiation=` Takes a boolean. If set to yes, automatic negotiation of transmission parameters is enabled. Autonegotiation is a procedure by which two connected ethernet devices choose common transmission parameters, such as speed, duplex mode, and flow control. When unset, the kernel's default will be used. Note that if autonegotiation is enabled, speed and duplex settings are read-only. If autonegotiation is disabled, speed and duplex settings are writable if the driver supports multiple link modes. `WakeOnLan=` The Wake-on-LAN policy to set for the device. Takes the special value `off` which disables Wake-on-LAN, or space separated list of the following words: `phy` Wake on PHY activity. `unicast` Wake on unicast messages. `multicast` Wake on multicast messages. `broadcast` Wake on broadcast messages. `arp` Wake on ARP. `magic` Wake on receipt of a magic packet. `secureon` Enable SecureOn password for MagicPacket. Implied when `WakeOnLanPassword=` is specified. If specified without `WakeOnLanPassword=` option, then the password is read from the credential `LINK.link.wol.password` (e.g., `60-foo.link.wol.password`), and if the credential not found, then read from `wol.password`. See `ImportCredential=`/`LoadCredential=`/`SetCredential=` in `systemd.exec(5)` for details. The password in the credential, must be 6 bytes in hex format with each byte separated by a colon (`:`) like an Ethernet MAC address, e.g., `aa:bb:cc:dd:ee:ff`. Defaults to unset, and the device's default will be used. This setting can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. `WakeOnLanPassword=` Specifies the SecureOn password for MagicPacket. Takes an absolute path to a regular file or an `AF_UNIX` stream socket, or the plain password. When a path to a regular file is specified, the password is read from it. When an `AF_UNIX` stream socket is specified, a connection is made to it and the password is read from it. The password must be 6 bytes in hex format with each byte separated by a colon (`:`) like an Ethernet MAC address, e.g., `aa:bb:cc:dd:ee:ff`. This implies `WakeOnLan=secureon`. Defaults to unset, and the current value will not be changed. `Port=` The port option is used to select the device port. The supported values are: `tp` An Ethernet interface using Twisted-Pair cable as the medium. `aui` Attachment Unit Interface (AUI). Normally used with hubs. `bnc` An Ethernet interface using BNC connectors and co-axial cable. `mii` An Ethernet interface using a Media Independent Interface (MII). `fibre` An Ethernet interface using Optical Fibre as the medium. `Advertise=` This sets what speeds and duplex modes of operation are advertised for auto-negotiation. This implies `AutoNegotiation=yes`. The supported values are: | Advertise | Speed (Mbps) | Duplex Mode | |-----------|--------------|-------------| Supported advertise values By default, this is unset, i.e. all possible modes will be advertised. This option may be specified more than once, in which case all specified speeds and modes are advertised. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect. `ReceiveChecksumOffload=` Takes a boolean. If set to true, hardware offload for checksumming of ingress network packets is enabled. When unset, the kernel's default will be used. `TransmitChecksumOffload=` Takes a boolean. If set to true, hardware offload for checksumming of egress network packets is enabled. When unset, the kernel's default will be used. `ScatterGather=` Takes a boolean. If set to true, enables offload feature where the hardware builds a network packet from multiple non-contiguous memory buffers. When unset, the kernel's default will be used. This corresponds to the command `ethtool -K INTERFACE tx-scatter-gather on|off`. `ScatterGatherFragmentList=` Takes a boolean. If set to true, enables offload feature where the hardware builds a network packet from a chained list of socket buffers. When unset, the kernel's default will be used. This corresponds to the command `ethtool -K INTERFACE tx-scatter-gather-fraglist on|off`. `TCPSegmentationOffload=` Takes a boolean. If set to true, TCP Segmentation Offload (TSO) is enabled. When unset, the kernel's default will be used. `TCPECNSegmentationOffload=` Takes a boolean. If set to true, TCP Segmentation Offload (TSO) is performed even when ECN (Explicit Congestion Notification) flags are active in the TCP stream. When unset, the kernel's default will be used. This corresponds to the command `ethtool -K INTERFACE tx-tcp-ecn-segmentation on|off`. `TCPMangleIdSegmentationOffload=` Takes a boolean. If set to true, TCP Segmentation Offload (TSO) is performed even if the hardware is incapable of correctly incrementing the IPv4 Identification (ID) field for each resulting packet. When unset, the kernel's default will be used. This corresponds to the command `ethtool -K INTERFACE tx-tcp-mangleid-segmentation on|off`. `TCP6SegmentationOffload=` Takes a boolean. If set to true, TCP6 Segmentation Offload (tx-tcp6-segmentation) is enabled. When unset, the kernel's default will be used. `GenericSegmentationOffload=` Takes a boolean. If set to true, Generic Segmentation Offload (GSO) is enabled. When unset, the kernel's default will be used. `PartialGenericSegmentationOffload=` Takes a boolean. If set to true, Partial Generic Segmentation Offload (GSO_Partial) is enabled. See [ Partial Generic Segmentation Offload](https://docs.kernel.org/networking/segmentation-offloads.html#partial-generic-segmentation-offload) for more details. When unset, the kernel's default will be used. `GenericReceiveOffload=` Takes a boolean. If set to true, Generic Receive Offload (GRO) is enabled. When unset, the kernel's default will be used. `GenericReceiveOffloadHardware=` Takes a boolean. If set to true, hardware accelerated Generic Receive Offload (GRO) is enabled. When unset, the kernel's default will be used. `GenericReceiveOffloadList=` Takes a boolean. If set to true, Generic Receive Offload (GRO) List for UDP is enabled. When unset, the kernel's default will be used. This corresponds to the command `ethtool -K INTERFACE rx-gro-list on|off`. `GenericReceiveOffloadUDPForwarding=` Takes a boolean. If set to true, Generic Receive Offload (GRO) for aggregating incoming UDP packets is enabled. When unset, the kernel's default will be used. This corresponds to the command `ethtool -K INTERFACE rx-udp-gro-forwarding on|off`. `LargeReceiveOffload=` Takes a boolean. If set to true, Large Receive Offload (LRO) is enabled. When unset, the kernel's default will be used. `ReceivePacketSteeringCPUMask=` Configures Receive Packet Steering (RPS) list of CPUs to which RPS may forward traffic. Takes a list of CPU indices or ranges separated by either whitespace or commas. Alternatively, takes the special value `all`, which will include all available CPUs in the mask. CPU ranges are specified by the lower and upper CPU indices separated by a dash (e.g. `2-6`). This option may be specified more than once, in which case the specified list of CPU ranges are merged. If an empty string is assigned, the list is reset, all assignments prior to this will have no effect. Defaults to unset and RPS CPU list is unchanged. To disable RPS when it was previously enabled, use the special value `disable`. `IRQAffinityPolicy=` Specifies the IRQ distribution strategy for network interface MSI/MSI-X interrupts. Takes one of `spread` or `single`. When set to `spread`, queue IRQs are distributed across CPUs using a topology-aware maximum distance algorithm that prefers CPUs on different NUMA nodes, then different physical cores, then different hyperthreads. When set to `single`, all IRQs are pinned to a single CPU (CPU 0 by default, or the first CPU in the set specified by `IRQAffinity=`). When there are more IRQs than available CPUs, queues wrap around using round-robin assignment. When unset, no affinity management is performed. Setting this to an empty string explicitly disables affinity management. This option only applies to devices with MSI/MSI-X interrupts discoverable via `/sys/class/net/iface/device/msi_irqs/`. Virtual devices (veth, tap) and legacy INTx devices are skipped with a notice logged. Note that if `irqbalance(1)` or similar IRQ management daemons are running, they may override the configured affinity. Consider disabling such daemons or configuring them to exclude managed interfaces. `IRQAffinity=` Filters the set of CPUs eligible for IRQ placement. Takes a list of CPU indices or ranges separated by either whitespace or commas (e.g., `0-3`, `0,2,4,6`, `0-3,8-11`). This option works in conjunction with `IRQAffinityPolicy=` and `IRQAffinityNUMA=` to constrain which CPUs receive network IRQs. When specified with `spread` policy, only the listed CPUs are considered for IRQ distribution. When specified with `single` policy, IRQs are pinned to the first CPU in the allowed set instead of CPU 0. Has no effect if `IRQAffinityPolicy=` is not set. `IRQAffinityNUMA=` Filters CPUs to those belonging to the specified NUMA node. Takes either `local` or an explicit NUMA node number (0, 1, 2, ...). When set to `local`, the NUMA node local to the NIC's PCIe slot is used (determined from `/sys/class/net/iface/device/numa_node`). If the device's NUMA node cannot be determined (e.g., non-NUMA system), a warning is logged and IRQ affinity configuration is skipped. When both `IRQAffinity=` and `IRQAffinityNUMA=` are specified, their intersection is used. If the intersection results in an empty set, an error is logged and no affinity is applied. Has no effect if `IRQAffinityPolicy=` is not set. `ReceiveVLANCTAGHardwareAcceleration=` Takes a boolean. If set to true, receive VLAN CTAG hardware acceleration is enabled. When unset, the kernel's default will be used. `TransmitVLANCTAGHardwareAcceleration=` Takes a boolean. If set to true, transmit VLAN CTAG hardware acceleration is enabled. When unset, the kernel's default will be used. `ReceiveVLANCTAGFilter=` Takes a boolean. If set to true, receive filtering on VLAN CTAGs is enabled. When unset, the kernel's default will be used. `TransmitVLANSTAGHardwareAcceleration=` Takes a boolean. If set to true, transmit VLAN STAG hardware acceleration is enabled. When unset, the kernel's default will be used. `NTupleFilter=` Takes a boolean. If set to true, receive N-tuple filters and actions are enabled. When unset, the kernel's default will be used. `ReceiveFCS=` Takes a boolean. If set to true, pass the Frame Check Sequence (FCS) value up the stack without trimming it, and allow userspace to calculate error rate or link health. When unset, the kernel's default will be used. `ReceiveAll=` Takes a boolean. If set to true, allow the interface to also receive damaged ethernet frames. When unset, the kernel's default will be used. `RxChannels=`; `TxChannels=`; `OtherChannels=`; `CombinedChannels=` Specifies the number of receive, transmit, other, or combined channels, respectively. Takes an unsigned integer in the range 1…4294967295 or `max`. If set to `max`, the advertised maximum value of the hardware will be used. When unset, the number will not be changed. Defaults to unset. `RxBufferSize=`; `RxMiniBufferSize=`; `RxJumboBufferSize=`; `TxBufferSize=` Specifies the maximum number of pending packets in the NIC receive buffer, mini receive buffer, jumbo receive buffer, or transmit buffer, respectively. Takes an unsigned integer in the range 1…4294967295 or `max`. If set to `max`, the advertised maximum value of the hardware will be used. When unset, the number will not be changed. Defaults to unset. `RxFlowControl=` Takes a boolean. When set, enables receive flow control, also known as the ethernet receive PAUSE message (generate and send ethernet PAUSE frames). When unset, the kernel's default will be used. `TxFlowControl=` Takes a boolean. When set, enables transmit flow control, also known as the ethernet transmit PAUSE message (respond to received ethernet PAUSE frames). When unset, the kernel's default will be used. `AutoNegotiationFlowControl=` Takes a boolean. When set, auto negotiation enables the interface to exchange state advertisements with the connected peer so that the two devices can agree on the ethernet PAUSE configuration. When unset, the kernel's default will be used. `GenericSegmentOffloadMaxBytes=` Specifies the maximum size of a Generic Segment Offload (GSO) packet the device should accept. The usual suffixes K, M, G are supported and are understood to the base of 1024. An unsigned integer in the range 1…65536. Defaults to unset. `GenericSegmentOffloadMaxSegments=` Specifies the maximum number of Generic Segment Offload (GSO) segments the device should accept. An unsigned integer in the range 1…65535. Defaults to unset. `UseAdaptiveRxCoalesce=`; `UseAdaptiveTxCoalesce=` Boolean properties that, when set, enable/disable adaptive Rx/Tx coalescing if the hardware supports it. When unset, the kernel's default will be used. `RxCoalesceSec=`; `RxCoalesceIrqSec=`; `RxCoalesceLowSec=`; `RxCoalesceHighSec=`; `TxCoalesceSec=`; `TxCoalesceIrqSec=`; `TxCoalesceLowSec=`; `TxCoalesceHighSec=` These properties configure the delay before Rx/Tx interrupts are generated after a packet is sent/received. The `Irq` properties come into effect when the host is servicing an IRQ. The `Low` and `High` properties come into effect when the packet rate drops below the low packet rate threshold or exceeds the high packet rate threshold respectively if adaptive Rx/Tx coalescing is enabled. When unset, the kernel's defaults will be used. `RxMaxCoalescedFrames=`; `RxMaxCoalescedIrqFrames=`; `RxMaxCoalescedLowFrames=`; `RxMaxCoalescedHighFrames=`; `TxMaxCoalescedFrames=`; `TxMaxCoalescedIrqFrames=`; `TxMaxCoalescedLowFrames=`; `TxMaxCoalescedHighFrames=` These properties configure the maximum number of frames that are sent/received before a Rx/Tx interrupt is generated. The `Irq` properties come into effect when the host is servicing an IRQ. The `Low` and `High` properties come into effect when the packet rate drops below the low packet rate threshold or exceeds the high packet rate threshold respectively if adaptive Rx/Tx coalescing is enabled. When unset, the kernel's defaults will be used. `CoalescePacketRateLow=`; `CoalescePacketRateHigh=` These properties configure the low and high packet rate (expressed in packets per second) threshold respectively and are used to determine when the corresponding coalescing settings for low and high packet rates come into effect if adaptive Rx/Tx coalescing is enabled. If unset, the kernel's defaults will be used. `CoalescePacketRateSampleIntervalSec=` Configures how often to sample the packet rate used for adaptive Rx/Tx coalescing. This property cannot be zero. This lowest time granularity supported by this property is seconds. Partial seconds will be rounded up before being passed to the kernel. If unset, the kernel's default will be used. `StatisticsBlockCoalesceSec=` How long to delay driver in-memory statistics block updates. If the driver does not have an in-memory statistic block, this property is ignored. This property cannot be zero. If unset, the kernel's default will be used. `RxMaxCoalescedCQEFrames=` Configures the maximum number of received frames that can be coalesced into a single Completion Queue Entry (CQE) or descriptor writeback. An unsigned integer in the range 0…4294967295. When unset, the kernel's default will be used. `RxCoalesceCQENSec=` Takes a timespan. If no unit is specified, the value is parsed as nanoseconds. The value must not exceed 4294967295 ns (about 4.29 seconds). This configures the maximum time a coalesced CQE or writeback can be delayed after the first packet arrives. If unset, the kernel's default will be used. `MDI=` Specifies the medium dependent interface (MDI) mode for the interface. A MDI describes the interface from a physical layer implementation to the physical medium used to carry the transmission. Takes one of the following words: `straight` (or equivalently: `mdi`), `crossover` (or equivalently: `mdi-x`, `mdix`), and `auto`. When `straight`, the MDI straight through mode will be used. When `crossover`, the MDI crossover (MDI-X) mode will be used. When `auto`, the MDI status is automatically detected. Defaults to unset, and the kernel's default will be used. `SR-IOVVirtualFunctions=` Specifies the number of SR-IOV virtual functions. Takes an integer in the range 0…2147483647. Defaults to unset, and automatically determined from the values specified in the `VirtualFunction=` settings in the \[SR-IOV\] sections. # \[SR-IOV\] Section Options SR-IOV provides the ability to partition a single physical PCI resource into virtual PCI functions which can then be e.g. injected into a VM. In the case of network VFs, SR-IOV reduces latency and CPU utilisation for north-south network traffic (that is, traffic with endpoints outside the host machine), by allowing traffic to bypass the host machine’s network stack. The presence of an \[SR-IOV\] section in a .link file will cause the creation and configuration of the specified virtual function. Within a .network file, the specified virtual function will be configured, but must already exist. Specify several \[SR-IOV\] sections to configure several SR-IOVs. The \[SR-IOV\] section accepts the following keys. `VirtualFunction=` Specifies a Virtual Function (VF), lightweight PCIe function designed solely to move data in and out. Takes an integer in the range 0…2147483646. This option is compulsory. `VLANId=` Specifies VLAN ID of the virtual function. Takes an integer in the range 1…4095. `QualityOfService=` Specifies quality of service of the virtual function. Takes an integer in the range 1…4294967294. `VLANProtocol=` Specifies VLAN protocol of the virtual function. Takes `802.1Q` or `802.1ad`. `MACSpoofCheck=` Takes a boolean. Controls the MAC spoof checking. When unset, the kernel's default will be used. `QueryReceiveSideScaling=` Takes a boolean. Toggle the ability of querying the receive side scaling (RSS) configuration of the virtual function (VF). The VF RSS information like RSS hash key may be considered sensitive on some devices where this information is shared between VF and the physical function (PF). When unset, the kernel's default will be used. `Trust=` Takes a boolean. Allows one to set trust mode of the virtual function (VF). When set, VF users can set a specific feature which may impact security and/or performance. When unset, the kernel's default will be used. `LinkState=` Allows one to set the link state of the virtual function (VF). Takes a boolean or a special value `auto`. Setting to `auto` means a reflection of the physical function (PF) link state, `yes` lets the VF to communicate with other VFs on this host even if the PF link state is down, `no` causes the hardware to drop any packets sent by the VF. When unset, the kernel's default will be used. `MACAddress=` Specifies the MAC address for the virtual function. # \[EnergyEfficientEthernet\] Section Options The \[EnergyEfficientEthernet\] section controls the Energy Efficient Ethernet (EEE) feature of the interface, and accepts the following keys. `Enable=` Takes a boolean argument. When true, the Energy Efficient Ethernet (EEE) feature will be enabled on the interface. Defaults to unset, and the enablement of EEE will be unchanged. `TxLowPowerIdle=` Takes a boolean argument. When true, the transmit Low Power Idle (Tx-LPI) mode of the Energy Efficient Ethernet feature will be enabled on the interface. Defaults to unset, and the enablement of the mode will be unchanged. `TxLowPowerIdleSec=` Takes a timespan. This configures how long the interface should not enter the Low Power Idle mode after transmission. If it is too short, may decrease performance. If it is too long, may not gain energy saving. Defaults to unset, and the timespan will be unchanged. `LinkMode=` Takes a list of link modes, e.g. `1000baset-full`. See the table for `Advertise=` setting in \[Link\] section in the above for possible values. This configures the Energy Efficient Ethernet capable connection modes to be advertised. Defaults to unset, and the advertised modes will be unchanged. # Specifiers Some settings resolve specifiers which may be used to write generic unit files referring to runtime or unit parameters that are replaced when the unit files are loaded. Specifiers must be known and resolvable for the setting to be valid. The following specifiers are understood: | Specifier | Meaning | Details | |-----------|---------|---------| Specifiers available in unit files {.specifiers} # Examples
/usr/lib/systemd/network/99-default.link
The link file `99-default.link` that is shipped with systemd defines the default policies for the interface name, alternative names, and MAC address of links. [Match] OriginalName=* [Link] NamePolicy=keep kernel database onboard slot path AlternativeNamesPolicy=database onboard slot path MACAddressPolicy=persistent
/etc/systemd/network/10-dmz.link
This example assigns the fixed name `dmz0` to the interface with the MAC address 00:a0:de:63:7a:e6: [Match] MACAddress=00:a0:de:63:7a:e6 [Link] Name=dmz0 `NamePolicy=` is not set, so `Name=` takes effect. We use the `10-` prefix to order this file early in the list. Note that it needs to be before `99-default.link`, i.e. it needs a numerical prefix, to have any effect at all.
(Re-)applying a .link file to an interface
After a new .link file has been created, or an existing .link file modified, the new settings may be applied to the matching interface with the following commands: $ sudo udevadm control --reload $ sudo ip link set eth0 down $ sudo udevadm trigger --verbose --settle --action add /sys/class/net/eth0 You may also need to stop the service that manages the network interface, e.g. `systemd-networkd.service(8)` or `NetworkManager.service` before the above operation, and then restart the service after that. For more details about `udevadm` command, see `udevadm(8)`.
Debugging `NamePolicy=` assignments
$ sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/hub0 … Parsed configuration file /usr/lib/systemd/network/99-default.link Parsed configuration file /etc/systemd/network/10-eth0.link ID_NET_DRIVER=cdc_ether Config file /etc/systemd/network/10-eth0.link applies to device hub0 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable. hub0: Device has name_assign_type=4 Using default interface naming scheme 'v240'. hub0: Policies did not yield a name, using specified Name=hub0. ID_NET_LINK_FILE=/etc/systemd/network/10-eth0.link ID_NET_NAME=hub0 … Explicit `Name=` configuration wins in this case. sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/enp0s31f6 … Parsed configuration file /usr/lib/systemd/network/99-default.link Parsed configuration file /etc/systemd/network/10-eth0.link Created link configuration context. ID_NET_DRIVER=e1000e Config file /usr/lib/systemd/network/99-default.link applies to device enp0s31f6 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable. enp0s31f6: Device has name_assign_type=4 Using default interface naming scheme 'v240'. enp0s31f6: Policy *keep*: keeping existing userspace name enp0s31f6: Device has addr_assign_type=0 enp0s31f6: MAC on the device already matches policy *persistent* ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link … In this case, the interface was already renamed, so the `keep` policy specified as the first option in `99-default.link` means that the existing name is preserved. If `keep` was removed, or if were in boot before the renaming has happened, we might get the following instead: enp0s31f6: Policy *path* yields "enp0s31f6". enp0s31f6: Device has addr_assign_type=0 enp0s31f6: MAC on the device already matches policy *persistent* ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link ID_NET_NAME=enp0s31f6 … Please note that the details of output are subject to change.
/etc/systemd/network/10-internet.link
This example assigns the fixed name `internet0` to the interface with the device path `pci-0000:00:1a.0-*`: [Match] Path=pci-0000:00:1a.0-* [Link] Name=internet0
/etc/systemd/network/25-wireless.link
Here's an overly complex example that shows the use of a large number of \[Match\] and \[Link\] settings. [Match] MACAddress=12:34:56:78:9a:bc Driver=brcmsmac Path=pci-0000:02:00.0-* Type=wlan Virtualization=no Host=my-laptop Architecture=x86-64 [Link] Name=wireless0 MTUBytes=1450 BitsPerSecond=10M WakeOnLan=magic MACAddress=cb:a9:87:65:43:21
# See Also `systemd-udevd.service(8)`, `udevadm(8)`, `systemd.netdev(5)`, `systemd.network(5)`, `systemd-network-generator.service(8)` # systemd systemd systemd 1 systemd init systemd system and service manager /usr/lib/systemd/systemd OPTIONS init OPTIONS # Description systemd is a system and service manager for Linux operating systems. When run as first process on boot (as PID 1), it acts as init system that brings up and maintains userspace services. Separate instances are started for logged-in users to start their services. `systemd` is usually not invoked directly by the user, but is installed as the `/sbin/init` symlink and started during early boot. The user manager instances are started automatically through the `user@.service(5)` service. When run as a system instance, systemd interprets the configuration file `system.conf` and the files in `system.conf.d` directories; when run as a user instance, systemd interprets the configuration file `user.conf` and the files in `user.conf.d` directories. See `systemd-system.conf(5)` for more information. `systemd` contains native implementations of various tasks that need to be executed as part of the boot process. For example, it sets the hostname or configures the loopback network device. It also sets up and mounts various API file systems, such as `/sys/`, `/proc/`, and `/dev/`. `systemd` will also reset the system clock during early boot if it appears to be set incorrectly. See "System clock epoch" section below. Note that some but not all interfaces provided by systemd are covered by the [Interface Portability and Stability Promise](https://systemd.io/PORTABILITY_AND_STABILITY/). The D-Bus API of `systemd` is described in `org.freedesktop.systemd1(5)` and `org.freedesktop.LogControl1(5)`. Systems which invoke systemd in a container or initrd environment should implement the [Container Interface](https://systemd.io/CONTAINER_INTERFACE) or [initrd Interface](https://systemd.io/INITRD_INTERFACE/) specifications, respectively. # Units systemd provides a dependency system between various entities called "units" of 11 different types. Units encapsulate various objects that are relevant for system boot-up and maintenance. The majority of units are configured in unit configuration files, whose syntax and basic set of options is described in `systemd.unit(5)`, however some are created automatically from other configuration files, dynamically from system state or programmatically at runtime. Units may be in a number of states, described in the following table. Note that the various unit types may have a number of additional substates, which are mapped to the generalized unit states described here. The following unit types are available: 1. Service units, which start and control daemons and the processes they consist of. For details, see `systemd.service(5)`. 2. Socket units, which encapsulate local IPC or network sockets in the system, useful for socket-based activation. For details about socket units, see `systemd.socket(5)`, for details on socket-based activation and other forms of activation, see `daemon(7)`. 3. Target units are useful to group units, or provide well-known synchronization points during boot-up, see `systemd.target(5)`. 4. Device units expose kernel devices in systemd and may be used to implement device-based activation. For details, see `systemd.device(5)`. 5. Mount units control mount points in the file system, for details see `systemd.mount(5)`. 6. Automount units provide automount capabilities, for on-demand mounting of file systems as well as parallelized boot-up. See `systemd.automount(5)`. 7. Timer units are useful for triggering activation of other units based on timers. You may find details in `systemd.timer(5)`. 8. Swap units are very similar to mount units and encapsulate memory swap partitions or files of the operating system. They are described in `systemd.swap(5)`. 9. Path units may be used to activate other services when file system objects change or are modified. See `systemd.path(5)`. 10. Slice units may be used to group units which manage system processes (such as service and scope units) in a hierarchical tree for resource management purposes. See `systemd.slice(5)`. 11. Scope units are similar to service units, but manage foreign processes instead of starting them as well. See `systemd.scope(5)`. Units are named as their configuration files. Some units have special semantics. A detailed list is available in `systemd.special(7)`. systemd knows various kinds of dependencies, including positive and negative requirement dependencies (i.e. `Requires=` and `Conflicts=`) as well as ordering dependencies (`After=` and `Before=`). NB: ordering and requirement dependencies are orthogonal. If only a requirement dependency exists between two units (e.g. `foo.service` requires `bar.service`), but no ordering dependency (e.g. `foo.service` after `bar.service`) and both are requested to start, they will be started in parallel. It is a common pattern that both requirement and ordering dependencies are placed between two units. Also note that the majority of dependencies are implicitly created and maintained by systemd. In most cases, it should be unnecessary to declare additional dependencies manually, however it is possible to do this. Application programs and units (via dependencies) may request state changes of units. In systemd, these requests are encapsulated as 'jobs' and maintained in a job queue. Jobs may succeed or can fail, their execution is ordered based on the ordering dependencies of the units they have been scheduled for. On boot systemd activates the target unit `default.target` whose job is to activate on-boot services and other on-boot units by pulling them in via dependencies. Usually, the unit name is just an alias (symlink) for either `graphical.target` (for fully-featured boots into the UI) or `multi-user.target` (for limited console-only boots for use in embedded or server environments, or similar; a subset of graphical.target). However, it is at the discretion of the administrator to configure it as an alias to any other target unit. See `systemd.special(7)` for details about these target units. On first boot, `systemd` will enable or disable units according to preset policy. See `systemd.preset(5)` and "First Boot Semantics" in `machine-id(5)`. systemd only keeps a minimal set of units loaded into memory. Specifically, the only units that are kept loaded into memory are those for which at least one of the following conditions is true: 1. It is in an active, activating, deactivating or failed state (i.e. in any unit state except for `inactive`) 2. It has a job queued for it 3. It is a dependency of at least one other unit that is loaded into memory 4. It has some form of resource still allocated (e.g. a service unit that is inactive but for which a process is still lingering that ignored the request to be terminated) 5. It has been pinned into memory programmatically by a D-Bus call systemd will automatically and implicitly load units from disk — if they are not loaded yet — as soon as operations are requested for them. Thus, in many respects, the fact whether a unit is loaded or not is invisible to clients. Use `systemctl list-units --all` to comprehensively list all units currently loaded. Any unit for which none of the conditions above applies is promptly unloaded. Note that when a unit is unloaded from memory its accounting data is flushed out too. However, this data is generally not lost, as a journal log record is generated declaring the consumed resources whenever a unit shuts down. Processes systemd spawns are placed in individual Linux control groups named after the unit which they belong to in the private systemd hierarchy. (see [Control Groups v2](https://docs.kernel.org/admin-guide/cgroup-v2.html) for more information about control groups, or short "cgroups"). systemd uses this to effectively keep track of processes. Control group information is maintained in the kernel, and is accessible via the file system hierarchy (beneath `/sys/fs/cgroup/`), or in tools such as `systemd-cgls(1)` or `ps(1)` (`ps xawf -eo pid,user,cgroup,args` is particularly useful to list all processes and the systemd units they belong to.). systemd is compatible with various established Unix functionality such as `/etc/fstab` or the `utmp` database. systemd has a minimal transaction system: if a unit is requested to start up or shut down it will add it and all its dependencies to a temporary transaction. Then, it will verify if the transaction is consistent (i.e. whether the ordering of all units is cycle-free). If it is not, systemd will try to fix it up, and removes non-essential jobs from the transaction that might remove the loop. Also, systemd tries to suppress non-essential jobs in the transaction that would stop a running service. Finally it is checked whether the jobs of the transaction contradict jobs that have already been queued, and optionally the transaction is aborted then. If all worked out and the transaction is consistent and minimized in its impact it is merged with all already outstanding jobs and added to the run queue. Effectively this means that before executing a requested operation, systemd will verify that it makes sense, fixing it if possible, and only failing if it really cannot work. Note that transactions are generated independently of a unit's state at runtime, hence, for example, if a start job is requested on an already started unit, it will still generate a transaction and wake up any inactive dependencies (and cause propagation of other jobs as per the defined relationships). This is because the enqueued job is at the time of execution compared to the target unit's state and is marked successful and complete when both satisfy. However, this job also pulls in other dependencies due to the defined relationships and thus leads to, in our example, start jobs for any of those inactive units getting queued as well. Units may be generated dynamically at boot and system manager reload time, for example based on other configuration files or parameters passed on the kernel command line. For details, see `systemd.generator(7)`. # Directories System unit directories The systemd system manager reads unit configuration from various directories. Packages that want to install unit files shall place them in the directory returned by `pkg-config systemd --variable=systemdsystemunitdir`. Other directories checked are `/usr/local/lib/systemd/system` and `/usr/lib/systemd/system`. User configuration always takes precedence. `pkg-config systemd --variable=systemdsystemconfdir` returns the path of the system configuration directory. Packages should alter the content of these directories only with the `enable` and `disable` commands of the `systemctl(1)` tool. Full list of directories is provided in `systemd.unit(5)`. User unit directories Similar rules apply for the user unit directories. However, here the [XDG Base Directory specification](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) is followed to find units. Applications should place their unit files in the directory returned by `pkg-config systemd --variable=systemduserunitdir`. Global configuration is done in the directory reported by `pkg-config systemd --variable=systemduserconfdir`. The `enable` and `disable` commands of the `systemctl(1)` tool can handle both global (i.e. for all users) and private (for one user) enabling/disabling of units. Full list of directories is provided in `systemd.unit(5)`. # Signals The service listens to various UNIX process signals that can be used to request various actions asynchronously. The signal handling is enabled very early during boot, before any further processes are invoked. However, a supervising container manager or similar that intends to request these operations via this mechanism must take into consideration that this functionality is not available during the earliest initialization phase. An `sd_notify()` notification message carrying the `X_SYSTEMD_SIGNALS_LEVEL=2` field is emitted once the signal handlers are enabled, see below. This may be used to schedule submission of these signals correctly. `SIGTERM` Upon receiving this signal the systemd system manager serializes its state, reexecutes itself and deserializes the saved state again. This is mostly equivalent to `systemctl daemon-reexec`. systemd user managers will start the `exit.target` unit when this signal is received. This is mostly equivalent to `systemctl --user start exit.target --job-mode=replace-irreversibly`. `SIGINT` Upon receiving this signal the systemd system manager will start the `ctrl-alt-del.target` unit. This is mostly equivalent to `systemctl start ctrl-alt-del.target --job-mode=replace-irreversibly`. If this signal is received more than 7 times per 2s, an immediate reboot is triggered. Note that pressing Ctrl+Alt+Del on the console will trigger this signal. Hence, if a reboot is hanging, pressing Ctrl+Alt+Del more than 7 times in 2 seconds is a relatively safe way to trigger an immediate reboot. systemd user managers treat this signal the same way as `SIGTERM`. `SIGWINCH` When this signal is received the systemd system manager will start the `kbrequest.target` unit. This is mostly equivalent to `systemctl start kbrequest.target`. This signal is ignored by systemd user managers. `SIGPWR` When this signal is received the systemd manager will start the `sigpwr.target` unit. This is mostly equivalent to `systemctl start sigpwr.target`. `SIGUSR1` When this signal is received the systemd manager will try to reconnect to the D-Bus bus. `SIGUSR2` When this signal is received the systemd manager will log its complete state in human-readable form. The data logged is the same as printed by `systemd-analyze dump`. `SIGHUP` Reloads the complete daemon configuration. This is mostly equivalent to `systemctl daemon-reload`. `SIGRTMIN+0` Enters default mode, starts the `default.target` unit. This is mostly equivalent to `systemctl isolate default.target`. `SIGRTMIN+1` Enters rescue mode, starts the `rescue.target` unit. This is mostly equivalent to `systemctl isolate rescue.target`. `SIGRTMIN+2` Enters emergency mode, starts the `emergency.service` unit. This is mostly equivalent to `systemctl isolate emergency.service`. `SIGRTMIN+3` Halts the machine, starts the `halt.target` unit. This is mostly equivalent to `systemctl start halt.target --job-mode=replace-irreversibly`. `SIGRTMIN+4` Powers off the machine, starts the `poweroff.target` unit. This is mostly equivalent to `systemctl start poweroff.target --job-mode=replace-irreversibly`. `SIGRTMIN+5` Reboots the machine, starts the `reboot.target` unit. This is mostly equivalent to `systemctl start reboot.target --job-mode=replace-irreversibly`. `SIGRTMIN+6` Reboots the machine via kexec, starts the `kexec.target` unit. This is mostly equivalent to `systemctl start kexec.target --job-mode=replace-irreversibly`. `SIGRTMIN+7` Reboots userspace, starts the `soft-reboot.target` unit. This is mostly equivalent to `systemctl start soft-reboot.target --job-mode=replace-irreversibly`. `SIGRTMIN+13` Immediately halts the machine. `SIGRTMIN+14` Immediately powers off the machine. `SIGRTMIN+15` Immediately reboots the machine. `SIGRTMIN+16` Immediately reboots the machine with kexec. `SIGRTMIN+17` Immediately reboots the userspace. `SIGRTMIN+20` Enables display of status messages on the console, as controlled via `systemd.show_status=1` on the kernel command line. You may want to use `SetShowStatus()` instead of `SIGRTMIN+20` in order to prevent race conditions. See `org.freedesktop.systemd1(5)`. `SIGRTMIN+21` Disables display of status messages on the console, as controlled via `systemd.show_status=0` on the kernel command line. You may want to use `SetShowStatus()` instead of `SIGRTMIN+21` in order to prevent race conditions. See `org.freedesktop.systemd1(5)`. `SIGRTMIN+22` Sets the service manager's log level to `debug`, in a fashion equivalent to `systemd.log_level=debug` on the kernel command line. `SIGRTMIN+23` Restores the log level to its configured value. The configured value is derived from – in order of priority – the value specified with `systemd.log-level=` on the kernel command line, or the value specified with `LogLevel=` in the configuration file, or the built-in default of `info`. `SIGRTMIN+24` Immediately exits the manager (only available for --user instances). `SIGRTMIN+25` Upon receiving this signal the systemd manager will reexecute itself. This is mostly equivalent to `systemctl daemon-reexec` except that it will be done asynchronously. The systemd system manager treats this signal the same way as `SIGTERM`. `SIGRTMIN+26` Restores the log target to its configured value. The configured value is derived from – in order of priority – the value specified with `systemd.log-target=` on the kernel command line, or the value specified with `LogTarget=` in the configuration file, or the built-in default. `SIGRTMIN+27`; `SIGRTMIN+28` Sets the log target to `console` on `SIGRTMIN+27` (or `kmsg` on `SIGRTMIN+28`), in a fashion equivalent to `systemd.log_target=console` (or `systemd.log_target=kmsg` on `SIGRTMIN+28`) on the kernel command line. # Environment The environment block for the system manager is initially set by the kernel. (In particular, `key=value` assignments on the kernel command line are turned into environment variables for PID 1). For the user manager, the system manager sets the environment as described in the "Environment Variables in Spawned Processes" section of `systemd.exec(5)`. The `DefaultEnvironment=` setting in the system manager applies to all services including `user@.service`. Additional entries may be configured (as for any other service) through the `Environment=` and `EnvironmentFile=` settings for `user@.service` (see `systemd.exec(5)`). Also, additional environment variables may be set through the `ManagerEnvironment=` setting in `systemd-system.conf(5)` and `systemd-user.conf(5)`. Some of the variables understood by `systemd`: `$SYSTEMD_LOG_LEVEL` This can be overridden with `--log-level=`. `$SYSTEMD_LOG_COLOR` This can be overridden with `--log-color=`. `$SYSTEMD_LOG_TIME` This can be overridden with `--log-time=`. `$SYSTEMD_LOG_LOCATION` This can be overridden with `--log-location=`. `$SYSTEMD_LOG_TID` `$SYSTEMD_LOG_TARGET` This can be overridden with `--log-target=`. `$SYSTEMD_LOG_RATELIMIT_KMSG` `$XDG_CONFIG_HOME`; `$XDG_CONFIG_DIRS`; `$XDG_DATA_HOME`; `$XDG_DATA_DIRS` The systemd user manager uses these variables in accordance to the [XDG Base Directory specification](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) to find its configuration. `$SYSTEMD_UNIT_PATH`; `$SYSTEMD_GENERATOR_PATH`; `$SYSTEMD_ENVIRONMENT_GENERATOR_PATH` Controls where systemd looks for unit files and generators. These variables may contain a list of paths, separated by colons (`:`). When set, if the list ends with an empty component (`...:`), this list is prepended to the usual set of paths. Otherwise, the specified list replaces the usual set of paths. `$LISTEN_PID`; `$LISTEN_PIDFDID`; `$LISTEN_FDS`; `$LISTEN_FDNAMES` Set by systemd for supervised processes during socket-based activation. See `sd_listen_fds(3)` for more information. `$NOTIFY_SOCKET` Set by service manager for its services for status and readiness notifications. Also consumed by service manager for notifying supervising container managers or service managers up the stack about its own progress. See `sd_notify(3)` and the relevant section below for more information. For further environment variables understood by systemd and its various components, see [Known Environment Variables](https://systemd.io/ENVIRONMENT). # Kernel Command Line When run as the system instance, systemd parses a number of options listed below. They can be specified as kernel command line arguments which are parsed from a number of sources depending on the environment in which systemd is executed. If run inside a Linux container, these options are parsed from the command line arguments passed to systemd itself, next to any of the command line options listed in the Options section above. If run outside of Linux containers, these arguments are parsed from `/proc/cmdline` instead. The following variables are understood: `systemd.unit=`; `rd.systemd.unit=` Overrides the unit to activate on boot. Defaults to `default.target`. This may be used to temporarily boot into a different boot unit, for example `rescue.target` or `emergency.service`. See `systemd.special(7)` for details about these units. The option prefixed with `rd.` is honored only in the initrd, while the one that is not prefixed only in the main system. `systemd.dump_core` Takes a boolean argument or enables the option if specified without an argument. If enabled, the systemd manager (PID 1) dumps core when it crashes. Otherwise, no core dump is created. Defaults to enabled. `systemd.crash_chvt` Takes a positive integer, or a boolean argument. Can be also specified without an argument, with the same effect as a positive boolean. If a positive integer (in the range 1–63) is specified, the system manager (PID 1) will activate the specified virtual terminal when it crashes. Defaults to disabled, meaning that no such switch is attempted. If set to enabled, the virtual terminal the kernel messages are written to is used instead. `systemd.crash_shell` Takes a boolean argument or enables the option if specified without an argument. If enabled, the system manager (PID 1) spawns a shell when it crashes. Otherwise, no shell is spawned. Defaults to disabled, for security reasons, as the shell is not protected by password authentication. `systemd.crash_action=` Takes one of `freeze`, `reboot` or `poweroff`. Defaults to `freeze`. If set to `freeze`, the system will hang indefinitely when the system manager (PID 1) crashes. If set to `reboot`, the system manager (PID 1) will reboot the machine automatically when it crashes, after a 10s delay. If set to `poweroff`, the system manager (PID 1) will power off the machine immediately when it crashes. If combined with `systemd.crash_shell`, the configured crash action is executed after the shell exits. `systemd.confirm_spawn` Takes a boolean argument or a path to the virtual console where the confirmation messages should be emitted. Can be also specified without an argument, with the same effect as a positive boolean. If enabled, the system manager (PID 1) asks for confirmation when spawning processes using `/dev/console`. If a path or a console name (such as `ttyS0`) is provided, the virtual console pointed to by this path or described by the give name will be used instead. Defaults to disabled. `systemd.service_watchdogs=` Takes a boolean argument. If disabled, all service runtime watchdogs (`WatchdogSec=`) and emergency actions (e.g. `OnFailure=` or `StartLimitAction=`) are ignored by the system manager (PID 1); see `systemd.service(5)`. Defaults to enabled, i.e. watchdogs and failure actions are processed normally. The hardware watchdog is not affected by this option. `systemd.show_status` Takes a boolean argument or the constants `error` and `auto`. Can be also specified without an argument, with the same effect as a positive boolean. If enabled, the systemd manager (PID 1) shows terse service status updates on the console during bootup. With `error`, only messages about failures are shown, but boot is otherwise quiet. `auto` behaves like `false` until there is a significant delay in boot. Defaults to enabled, unless `quiet` is passed as kernel command line option, in which case it defaults to `error`. If specified overrides the system manager configuration file option `ShowStatus=`, see `systemd-system.conf(5)`. `systemd.status_unit_format=` Takes `name`, `description` or `combined` as the value. If `name`, the system manager will use unit names in status messages. If `combined`, the system manager will use unit names and description in status messages. When specified, overrides the system manager configuration file option `StatusUnitFormat=`, see `systemd-system.conf(5)`. `systemd.log_color`; `systemd.log_level=`; `systemd.log_location`; `systemd.log_target=`; `systemd.log_time`; `systemd.log_tid`; `systemd.log_ratelimit_kmsg` Controls log output, with the same effect as the `$SYSTEMD_LOG_COLOR`, `$SYSTEMD_LOG_LEVEL`, `$SYSTEMD_LOG_LOCATION`, `$SYSTEMD_LOG_TARGET`, `$SYSTEMD_LOG_TIME`, `$SYSTEMD_LOG_TID` and `$SYSTEMD_LOG_RATELIMIT_KMSG` environment variables described above. `systemd.log_color`, `systemd.log_location`, `systemd.log_time`, `systemd.log_tid` and `systemd.log_ratelimit_kmsg` can be specified without an argument, with the same effect as a positive boolean. `systemd.default_standard_output=`; `systemd.default_standard_error=` Controls default standard output and error output for services and sockets. That is, controls the default for `StandardOutput=` and `StandardError=` (see `systemd.exec(5)` for details). Takes one of `inherit`, `null`, `tty`, `journal`, `journal+console`, `kmsg`, `kmsg+console`. If the argument is omitted `systemd.default-standard-output=` defaults to `journal` and `systemd.default-standard-error=` to `inherit`. `systemd.setenv=` Takes a string argument in the form VARIABLE=VALUE. May be used to set default environment variables to add to forked child processes. May be used more than once to set multiple variables. `systemd.machine_id=` Takes a 32 character hex value to be used for setting the machine-id. Intended mostly for network booting where the same machine-id is desired for every boot. `systemd.set_credential=`; `systemd.set_credential_binary=` Sets a system credential, which can then be propagated to system services using the `ImportCredential=` or `LoadCredential=` setting, see `systemd.exec(5)` for details. Takes a pair of credential name and value, separated by a colon. The `systemd.set_credential=` parameter expects the credential value in literal text form, the `systemd.set_credential_binary=` parameter takes binary data encoded in Base64. Note that the kernel command line is typically accessible by unprivileged programs in `/proc/cmdline`. Thus, this mechanism is not suitable for transferring sensitive data. Use it only for data that is not sensitive (e.g. public keys/certificates, rather than private keys), or in testing/debugging environments. For further information see [System and Service Credentials](https://systemd.io/CREDENTIALS) documentation. `systemd.import_credentials=` Takes a boolean argument. If false disables importing credentials from the kernel command line, the DMI/SMBIOS OEM string table, the qemu_fw_cfg subsystem or the EFI kernel stub. `systemd.credentials_boot_policy=` Controls under which conditions a credential encrypted with a `null` key (i.e. a credential wrapped in a `systemd-creds` envelope but offering neither confidentiality nor authenticity, see `systemd-creds(1)`) is accepted at boot. This provides a fallback for provisioning credentials before a machine has a key to encrypt them against, for example during first boot or on systems without a TPM2 device. Takes one of `strict`, `tofu`, `relaxed` or `off`: - `strict` never accepts a `null` key, i.e. always insists on proper encryption. - `tofu` (trust on first use) accepts a `null` key during first boot, or when no TPM2 device is available. - `relaxed` accepts a `null` key when SecureBoot is disabled, or when no TPM2 device is available. - `off` always accepts a `null` key. Defaults to `relaxed`. Note that this policy only applies to the default acceptance decision; it has no effect on credentials encrypted against a host key or TPM2 device, which are always accepted. For further information see [System and Service Credentials](https://systemd.io/CREDENTIALS) documentation. `quiet` Turn off status output at boot, much like `systemd.show_status=no` would. Note that this option is also read by the kernel itself and disables kernel log output. Passing this option hence turns off the usual output from both the system manager and the kernel. `debug` Turn on debugging output. This is equivalent to `systemd.log_level=debug`. Note that this option is also read by the kernel itself and enables kernel debug output. Passing this option hence turns on the debug output from both the system manager and the kernel. `emergency`; `rd.emergency` Boot into emergency mode. Those options are equivalent to `systemd.unit=emergency.target` or `rd.systemd.unit=emergency.target`, respectively. They were initially provided for compatibility with SysV, but are retained as convenient shortcuts. `rescue`; `rd.rescue`; `single`; `1` Boot into rescue mode. Those options are equivalent to either `systemd.unit=rescue.target` or `rd.systemd.unit=rescue.target`. They were initially provided for compatibility with SysV, but are retained as convenient shortcuts. `3`; `5` Shortcuts to boot into specific targets: `3` is equivalent to `systemd.unit=multi-user.target` and `5` is equivalent to `systemd.unit=graphical.target`. Those options were initially provided for compatibility with SysV, but are retained as convenient shortcuts. `locale.LANG=`; `locale.LANGUAGE=`; `locale.LC_CTYPE=`; `locale.LC_NUMERIC=`; `locale.LC_TIME=`; `locale.LC_COLLATE=`; `locale.LC_MONETARY=`; `locale.LC_MESSAGES=`; `locale.LC_PAPER=`; `locale.LC_NAME=`; `locale.LC_ADDRESS=`; `locale.LC_TELEPHONE=`; `locale.LC_MEASUREMENT=`; `locale.LC_IDENTIFICATION=` Set the system locale to use. This overrides the settings in `/etc/locale.conf`. For more information, see `locale.conf(5)` and `locale(7)`. `systemd.minimum_uptime_sec=` Takes a time in seconds. Specifies the minimum uptime of the system before the system shuts down. For more information see the `MinimumUptimeSec=` setting described in `systemd-system.conf(5)`. For other kernel command line parameters understood by components of the core OS, please refer to `kernel-command-line(7)`. # System Credentials During initialization the service manager will import credentials from various sources into the system's set of credentials, which can then be propagated into services and consumed by generators: - When the service manager first initializes it will read system credentials from SMBIOS Type 11 vendor strings `io.systemd.credential:name=value`, and `io.systemd.credential.binary:name=value`. - At the same time it will import credentials from QEMU `fw_cfg`. (Note that the SMBIOS mechanism is generally preferred, because it is faster and generic.) - Credentials may be passed via the kernel command line, using the `systemd.set-credential=` parameter, see above. - Credentials may be passed from the UEFI environment via `systemd-stub(7)`. - When the service manager is invoked during the initrd → host transition it will import all files in `/run/credentials/@initrd/` as system credentials. Invoke `systemd-creds(1)` as follows to see the list of credentials passed into the system: # systemd-creds --system list For further information see [System and Service Credentials](https://systemd.io/CREDENTIALS) documentation. The service manager when run as PID 1 consumes the following system credentials: `vmm.notify_socket` Contains a `AF_VSOCK` or `AF_UNIX` address where to send a `READY=1` notification message when the service manager has completed booting. See `sd_notify(3)` and the next section for more information. Note that in case the hypervisor does not support `SOCK_DGRAM` over `AF_VSOCK`, `SOCK_SEQPACKET` will be tried instead. The credential payload for `AF_VSOCK` should be a string in the form `vsock:CID:PORT`. `vsock-stream`, `vsock-dgram` and `vsock-seqpacket` can be used instead of `vsock` to force usage of the corresponding socket type. This feature is useful for machine managers or other processes on the host to receive a notification via VSOCK when a virtual machine has finished booting. `system.machine_id` Takes a 128bit hexadecimal ID to initialize `/etc/machine-id` from, if the file is not set up yet. See `machine-id(5)` for details. For a list of system credentials various other components of systemd consume, see `systemd.system-credentials(7)`. # Readiness Protocol The service manager implements a readiness notification protocol both between the manager and its services (i.e. down the stack), and between the manager and a potential supervisor further up the stack (the latter could be a machine or container manager, or in case of a per-user service manager the system service manager instance). The basic protocol (and the suggested API for it) is described in `sd_notify(3)`. The notification socket the service manager (including PID 1) uses for reporting readiness to its own supervisor is set via the usual `$NOTIFY_SOCKET` environment variable (see above). Since this is directly settable only for container managers and for the per-user instance of the service manager, an additional mechanism to configure this is available, in particular intended for use in VM environments: the `vmm.notify_socket` system credential (see above) may be set to a suitable socket (typically an `AF_VSOCK` one) via SMBIOS Type 11 vendor strings. For details see above. The notification protocol from the service manager up the stack towards a supervisor supports a number of extension fields that allow a supervisor to learn about specific properties of the system and track its boot progress. Specifically the following fields are sent: - An `X_SYSTEMD_HOSTNAME=…` message will be sent out once the initial hostname for the system has been determined. Note that during later runtime the hostname might be changed again programmatically, and (currently) no further notifications are sent out in that case. - An `X_SYSTEMD_MACHINE_ID=…` message will be sent out once the machine ID of the system has been determined. See `machine-id(5)` for details. - An `X_SYSTEMD_SIGNALS_LEVEL=…` message will be sent out once the service manager installed the various UNIX process signal handlers described above. The field's value is an unsigned integer formatted as decimal string, and indicates the supported UNIX process signal feature level of the service manager. Currently, only a single feature level is defined: - `X_SYSTEMD_SIGNALS_LEVEL=2` covers the various UNIX process signals documented above – which are a superset of those supported by the historical SysV init system. Signals sent to PID 1 before this message is sent might not be handled correctly yet. A consumer of these messages should parse the value as an unsigned integer that indicates the level of support. For now only the mentioned level 2 is defined, but later on additional levels might be defined with higher integers, that will implement a superset of the currently defined behaviour. - `X_SYSTEMD_UNIT_ACTIVE=…` and `X_SYSTEMD_UNIT_INACTIVE=…` messages will be sent out for each target unit as it becomes active or stops being active. This is useful to track boot progress and functionality. For example, once the `ssh-access.target` unit is reported started SSH access is typically available, see `systemd.special(7)` for details. - An `X_SYSTEMD_SHUTDOWN=…` message will be sent out very shortly before the system shuts down. The value is one of the strings `reboot`, `halt`, `poweroff`, `kexec` and indicates which kind of shutdown is being executed. - An `X_SYSTEMD_REBOOT_PARAMETER=…` message will also be sent out very shortly before the system shuts down. Its value is the reboot argument as configured with `systemctl --reboot-argument=…`. Note that these extension fields are sent in addition to the regular `READY=1` and `RELOADING=1` notifications. # Options `systemd` is only very rarely invoked directly, since it is started early and is already running by the time users may interact with it. Normally, tools like `systemctl(1)` are used to give commands to the manager. Since `systemd` is usually not invoked directly, the options listed below are mostly useful for debugging and special purposes. ## Introspection and debugging options Those options are used for testing and introspection, and `systemd` may be invoked with them at any time: `--dump-configuration-items` Dump understood unit configuration items. This outputs a terse but complete list of configuration items understood in unit definition files. `--dump-bus-properties` Dump exposed bus properties. This outputs a terse but complete list of properties exposed on D-Bus. `--test` Determine the initial start-up transaction (i.e. the list of jobs enqueued at start-up), dump it and exit — without actually executing any of the determined jobs. This option is useful for debugging only. Note that during regular service manager start-up additional units not shown by this operation may be started, because hardware, socket, bus or other kinds of activation might add additional jobs as the transaction is executed. Use `--system` to request the initial transaction of the system service manager (this is also the implied default), combine with `--user` to request the initial transaction of the per-user service manager instead. `--system`; `--user` When used in conjunction with `--test`, selects whether to calculate the initial transaction for the system instance or for a per-user instance. These options have no effect when invoked without `--test`, as during regular (i.e. non-`--test`) invocations the service manager will automatically detect whether it shall operate in system or per-user mode, by checking whether the PID it is run as is 1 or not. Note that it is not supported booting and maintaining a system with the service manager running in `--system` mode but with a PID other than 1. ## Options that duplicate kernel command line settings Those options correspond directly to options listed above in "Kernel Command Line". Both forms may be used equivalently for the system manager, but it is recommended to use the forms listed above in this context, because they are properly namespaced. When an option is specified both on the kernel command line and as a normal command line argument, the latter has higher precedence. When `systemd` is used as a user manager, the kernel command line is ignored and only the options described below are understood. Nevertheless, `systemd` is usually started in this mode through the `user@.service(5)` service, which is shared between all users. It may be more convenient to use configuration files to modify settings (see `systemd-user.conf(5)`), or environment variables. See the "Environment" section above for a discussion of how the environment block is set. `--unit=` Set default unit to activate on startup. If not specified, defaults to `default.target`. See `systemd.unit=` above. `--dump-core` Enable core dumping on crash. This switch has no effect when running as user instance. Same as `systemd.dump_core=` above. `--crash-vt=VT` Switch to a specific virtual console (VT) on crash. This switch has no effect when running as user instance. Same as `systemd.crash_chvt=` above (but not the different spelling!). `--crash-shell` Run a shell on crash. This switch has no effect when running as user instance. See `systemd.crash_shell=` above. `--crash-action=` Specify what to do when the system manager (PID 1) crashes. This switch has no effect when `systemd` is running as user instance. See `systemd.crash_action=` above. `--confirm-spawn` Ask for confirmation when spawning processes. This switch has no effect when run as user instance. See `systemd.confirm_spawn` above. `--show-status` Show terse unit status information on the console during boot-up and shutdown. See `systemd.show_status` above. `--log-color` Highlight important log messages. See `systemd.log_color` above. `--log-level=` Set log level. See `systemd.log_level` above. `--log-location` Include code location in log messages. See `systemd.log_location` above. `--log-target=` Set log target. See `systemd.log_target` above. `--log-time=` Prefix console messages with timestamp. See `systemd.log_time` above. `--machine-id=` Override the machine-id set on the hard drive. See `systemd.machine_id=` above. `--service-watchdogs` Globally enable/disable all service watchdog timeouts and emergency actions. See `systemd.service_watchdogs` above. `--default-standard-output=`; `--default-standard-error=` Sets the default output or error output for all services and sockets, respectively. See `systemd.default_standard_output=` and `systemd.default_standard_error=` above. # System clock epoch When `systemd` is started or restarted, it may set the system clock to the "epoch". This mechanism is used to ensure that the system clock remains somewhat reasonably initialized and roughly monotonic across reboots, in case no battery-backed local RTC is available or it does not work correctly. The epoch is the lowest date above which the system clock time is assumed to be set correctly. When initializing, the local clock is *advanced* to the epoch if it was set to a lower value. As a special case, if the local clock is sufficiently far in the future (by default 15 years, but this can be configured at build time), the hardware clock is assumed to be broken, and the system clock is *rewound* to the epoch. The epoch is set to the highest of: the build time of `systemd`, the modification time ("mtime") of `/usr/lib/clock-epoch`, and the modification time of `/var/lib/systemd/timesync/clock`. # Files `/run/systemd/notify` Daemon status notification socket. This is an `AF_UNIX` datagram socket and is used to implement the daemon notification logic as implemented by `sd_notify(3)`. `/run/systemd/private` Used internally as communication channel between `systemctl(1)` and the systemd process. This is an `AF_UNIX` stream socket. This interface is private to systemd and should not be used in external projects. `/usr/lib/clock-epoch` The modification time ("mtime") of this file is used for the time epoch, see previous section. `/var/lib/systemd/timesync/clock` The modification time ("mtime") of this file is updated by `systemd-timesyncd.service(8)`. If present, the modification time of file is used for the epoch, see previous section. # History systemd 252 Kernel command-line arguments `systemd.unified_cgroup_hierarchy` and `systemd.legacy_systemd_cgroup_controller` were deprecated. Please switch to the unified cgroup hierarchy. # See Also The [systemd Homepage](https://systemd.io/), `systemd-system.conf(5)`, `locale.conf(5)`, `systemctl(1)`, `journalctl(1)`, `systemd-notify(1)`, `daemon(7)`, `sd-daemon(3)`, `org.freedesktop.systemd1(5)`, `systemd.unit(5)`, `systemd.special(7)`, `pkg-config(1)`, `kernel-command-line(7)`, `bootup(7)`, `systemd.directives(7)`, `org.freedesktop.systemd1(5)` For more information about the concepts and ideas behind systemd, please refer to the [Original Design Document](https://0pointer.de/blog/projects/systemd.html). # systemd.mount systemd systemd.mount 5 systemd.mount Mount unit configuration `mount.mount` # Description A unit configuration file whose name ends in `.mount` encodes information about a file system mount point controlled and supervised by systemd. This man page lists the configuration options specific to this unit type. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. The mount specific configuration options are configured in the \[Mount\] section. Additional options are listed in `systemd.exec(5)`, which define the execution environment the `mount(8)` program is executed in, and in `systemd.kill(5)`, which define the way the processes are terminated, and in `systemd.resource-control(5)`, which configure resource control settings for the processes of the service. Note that the options `User=` and `Group=` are not useful for mount units. systemd passes two parameters to `mount(8)`; the values of `What=` and `Where=`. When invoked in this way, `mount(8)` does not read any options from `/etc/fstab`, and must be run as UID 0. Mount units must be named after the mount point directories they control. Example: the mount point `/home/lennart` must be configured in a unit file `home-lennart.mount`. For details about the escaping logic used to convert a file system path to a unit name, see `systemd.unit(5)`. Note that mount units cannot be templated, nor is possible to add multiple names to a mount unit by creating symlinks to its unit file. Optionally, a mount unit may be accompanied by an automount unit, to allow on-demand or parallelized mounting. See `systemd.automount(5)`. Mount points created at runtime (independently of unit files or `/etc/fstab`) will be monitored by systemd and appear like any other mount unit in systemd. See `/proc/self/mountinfo` description in `proc(5)`. Some file systems have special semantics as API file systems for kernel-to-userspace and userspace-to-userspace interfaces. Some of them may not be changed via mount units, and cannot be disabled. For a longer discussion see [API File Systems](https://systemd.io/API_FILE_SYSTEMS). The `systemd-mount(1)` command allows creating `.mount` and `.automount` units dynamically and transiently from the command line. # Automatic Dependencies ## Implicit Dependencies The following dependencies are implicitly added: - If a mount unit is beneath another mount unit in the file system hierarchy, both a requirement dependency and an ordering dependency between both units are created automatically. - Block device backed file systems automatically gain `Requires=`, `StopPropagatedFrom=`, and `After=` type dependencies on the device unit encapsulating the block device (see `x-systemd.device-bound=` for details). - If traditional file system quota is enabled for a mount unit, automatic `Wants=` and `Before=` dependencies on `systemd-quotacheck@.service` and `quotaon@.service` are added. - Additional implicit dependencies may be added as result of execution and resource control parameters as documented in `systemd.exec(5)` and `systemd.resource-control(5)`. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - All mount units acquire automatic `Before=` and `Conflicts=` on `umount.target` in order to be stopped during shutdown. - Mount units referring to local file systems automatically gain an `After=` dependency on `local-fs-pre.target`, and a `Before=` dependency on `local-fs.target` unless one or more mount options among `nofail`, `x-systemd.wanted-by=`, and `x-systemd.required-by=` is set. See below for detailed information. Additionally, an `After=` dependency on `swap.target` is added when the file system type is `tmpfs`. - Network mount units automatically acquire `After=` dependencies on `remote-fs-pre.target`, `network.target`, plus `After=` and `Wants=` dependencies on `network-online.target`, and a `Before=` dependency on `remote-fs.target`, unless one or more mount options among `nofail`, `x-systemd.wanted-by=`, and `x-systemd.required-by=` is set. Mount units referring to local and network file systems are distinguished by their file system type specification. In some cases this is not sufficient (for example network block device based mounts, such as iSCSI), in which case `_netdev` may be added to the mount option string of the unit, which forces systemd to consider the mount unit a network mount. # `fstab` Mount units may either be configured via unit files, or via `/etc/fstab` (see `fstab(5)` for details). Mounts listed in `/etc/fstab` will be converted into native units dynamically at boot and when the configuration of the system manager is reloaded. In general, configuring mount points through `/etc/fstab` is the preferred approach to manage mounts for humans. For tooling, writing mount units should be preferred over editing `/etc/fstab`. See `systemd-fstab-generator(8)` for details about the conversion from `/etc/fstab` to mount units. The NFS mount option `bg` for NFS background mounts as documented in `nfs(5)` is detected by `systemd-fstab-generator` and the options are transformed so that systemd fulfills the job-control implications of that option. Specifically `systemd-fstab-generator` acts as though `x-systemd.mount-timeout=infinity,retry=10000` was prepended to the option list, and `fg,nofail` was appended. Depending on specific requirements, it may be appropriate to provide some of these options explicitly, or to make use of the `x-systemd.automount` option described below instead of using `bg`. When reading `/etc/fstab` a few special mount options are understood by systemd which influence how dependencies are created for mount points. systemd will create a dependency of type `Wants=` or `Requires=` (see option `nofail` below), from either `local-fs.target` or `remote-fs.target`, depending whether the file system is local or remote. `x-systemd.requires=` Configures a `Requires=` and an `After=` dependency between the created mount unit and another systemd unit, such as a device or mount unit. The argument should be a unit name, or an absolute path to a device node or mount point. This option may be specified more than once. This option is particularly useful for mount point declarations that need an additional device to be around (such as an external journal device for journal file systems) or an additional mount to be in place (such as an overlay file system that merges multiple mount points). See `After=` and `Requires=` in `systemd.unit(5)` for details. Note that this option always applies to the created mount unit only regardless whether `x-systemd.automount` has been specified. `x-systemd.wants=` Configures a `Wants=` and an `After=` dependency between the created mount unit and another systemd unit, similar to the `x-systemd.requires=` option. `x-systemd.before=`; `x-systemd.after=` In the created mount unit, configures a `Before=` or `After=` dependency on another systemd unit, such as a mount unit. The argument should be a unit name or an absolute path to a mount point. This option may be specified more than once. This option is particularly useful for mount point declarations with `nofail` option that are mounted asynchronously but need to be mounted before or after some unit start, for example, before `local-fs.target` unit. See `Before=` and `After=` in `systemd.unit(5)` for details. Note that these options always apply to the created mount unit only regardless whether `x-systemd.automount` has been specified. `x-systemd.wanted-by=`; `x-systemd.required-by=` In the created mount unit, configures a `WantedBy=` or `RequiredBy=` dependency on another unit. This option may be specified more than once. If this is specified, the default dependencies (see above) other than `umount.target` on the created mount unit, e.g. `local-fs.target`, are not automatically created. Hence it is likely that some ordering dependencies need to be set up manually through `x-systemd.before=` and `x-systemd.after=`. See `WantedBy=` and `RequiredBy=` in `systemd.unit(5)` for details. `x-systemd.wants-mounts-for=`; `x-systemd.requires-mounts-for=` Configures a `RequiresMountsFor=` or `WantsMountsFor=` dependency between the created mount unit and other mount units. The argument must be an absolute path. This option may be specified more than once. See `RequiresMountsFor=` or `WantsMountsFor=` in `systemd.unit(5)` for details. `x-systemd.onfailure=` In the created mount unit, configures an `OnFailure=` dependency. The argument is a unit name, see `x-systemd.requires=` above. This option may be specified more than once. See `OnFailure=` in `systemd.unit(5)` for details. Note that this option always applies to the created mount unit only, regardless of whether `x-systemd.automount` has been specified. Note that this option is silently ignored on swap entries. `x-systemd.graceful-option=` Additional mount option that shall be appended if supported by the kernel. This may be used to configure mount options that are optional and only enabled on kernels that support them. Note that this is supported only for native kernel mount options (i.e. explicitly not for mount options implemented in userspace, such as those processed by `/usr/bin/mount` itself, by FUSE or by mount helpers such as `mount.nfs`). This option may be specified more than once. `x-systemd.device-bound=` Takes a boolean argument. If true or no argument, a `BindsTo=` dependency on the backing device is set. If false, the mount unit is not stopped no matter whether the backing device is still present. This is useful when the file system is backed by volume managers. If not set, and the mount comes from unit fragments, i.e. generated from `/etc/fstab` by `systemd-fstab-generator(8)` or loaded from a manually configured mount unit, a combination of `Requires=` and `StopPropagatedFrom=` dependencies is set on the backing device, otherwise only `Requires=` is used. `x-systemd.automount` An automount unit will be created for the file system. See `systemd.automount(5)` for details. `x-systemd.idle-timeout=` Configures the idle timeout of the automount unit. See `TimeoutIdleSec=` in `systemd.automount(5)` for details. `x-systemd.device-timeout=` Configure how long systemd should wait for a device to show up before giving up on an entry from `/etc/fstab`. Specify a time in seconds or explicitly append a unit such as `s`, `min`, `h`, `ms`. Note that this option can only be used in `/etc/fstab`, and will be ignored when part of the `Options=` setting in a unit file. `x-systemd.mount-timeout=` Configure how long systemd should wait for the mount command to finish before giving up on an entry from `/etc/fstab`. Specify a time in seconds or explicitly append a unit such as `s`, `min`, `h`, `ms`. Note that this option can only be used in `/etc/fstab`, and will be ignored when part of the `Options=` setting in a unit file. See `TimeoutSec=` below for details. `x-systemd.makefs` The file system will be initialized on the device. If the device is not "empty", i.e. it contains any signature, the operation will be skipped. It is hence expected that this option remains set even after the device has been initialized. Note that this option can only be used in `/etc/fstab`, and will be ignored when part of the `Options=` setting in a unit file. See `systemd-makefs@.service(8)`. `wipefs(8)` may be used to remove any signatures from a block device to force `x-systemd.makefs` to reinitialize the device. `x-systemd.growfs` The file system will be grown to occupy the full block device. If the file system is already at maximum size, no action will be performed. It is hence expected that this option remains set even after the file system has been grown. Only certain file system types are supported, see `systemd-makefs@.service(8)` for details. Note that this option can only be used in `/etc/fstab`, and will be ignored when part of the `Options=` setting in a unit file. `x-systemd.pcrfs` Measures file system identity information (mount point, type, label, UUID, partition label, partition UUID) into PCR 15 after the file system has been mounted. This ensures the `systemd-pcrfs@.service(8)` or `systemd-pcrfs-root.service` services are pulled in by the mount unit. Note that this option can only be used in `/etc/fstab`, and will be ignored when part of the `Options=` setting in a unit file. It is also implied for the root and `/usr/` partitions discovered by `systemd-gpt-auto-generator(8)`. `x-systemd.validatefs` Validates mount constraint metadata of the mounted file system after mounting it. This ensures the `systemd-validatefs@.service(8)` service is pulled in by the mount unit. Note that this option can only be used in `/etc/fstab`, and will be ignored when part of the `Options=` setting in a unit file. It is also implied for all partitions discovered by `systemd-gpt-auto-generator(8)`. `x-systemd.rw-only` If a mount operation fails to mount the file system read-write, it normally tries mounting the file system read-only instead. This option disables that behaviour, and causes the mount to fail immediately instead. This option is translated into the `ReadWriteOnly=` setting in a unit file. `_netdev` Normally the file system type is used to determine if a mount is a "network mount", i.e. if it should only be started after the network is available. Using this option overrides this detection and specifies that the mount requires network. Network mount units are ordered between `remote-fs-pre.target` and `remote-fs.target`, instead of `local-fs-pre.target` and `local-fs.target`. They also pull in `network-online.target` and are ordered after it and `network.target`. `noauto`; `auto` With `noauto`, the mount unit will not be added as a dependency for `local-fs.target` or `remote-fs.target`. This means that it will not be mounted automatically during boot, unless it is pulled in by some other unit. The `auto` option has the opposite meaning and is the default. Note that if `x-systemd.automount` (see above) is used, neither `auto` nor `noauto` have any effect. The matching automount unit will be added as a dependency to the appropriate target. `nofail` With `nofail`, this mount will be only wanted, not required, by `local-fs.target` or `remote-fs.target`. Moreover, the mount unit is not ordered before these target units. This means that the boot will continue without waiting for the mount unit and regardless whether the mount point can be mounted successfully. `x-initrd.mount` An additional filesystem to be mounted in the initrd. See `initrd-fs.target` description in `systemd.special(7)`. This is both an indicator to the initrd to mount this partition early and an indicator to the host to leave the partition mounted until final shutdown. Or in other words, if this flag is set it is assumed the mount shall be active during the entire regular runtime of the system, i.e. established before the initrd transitions into the host all the way until the host transitions to the final shutdown phase. If a mount point is configured in both `/etc/fstab` and a unit file that is stored below `/usr/`, the former will take precedence. If the unit file is stored below `/etc/`, it will take precedence. This means: native unit files take precedence over traditional configuration files, but this is superseded by the rule that configuration in `/etc/` will always take precedence over configuration in `/usr/`. # Options Mount unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. Mount unit files must include a \[Mount\] section, which carries information about the file system mount points it supervises. A number of options that may be used in this section are shared with other unit types. These options are documented in `systemd.exec(5)`, `systemd.kill(5)` and `systemd.resource-control(5)`. The options specific to the \[Mount\] section of mount units are the following: `What=` Takes an absolute path or a fstab-style identifier of a device node, file or other resource to mount. See `mount(8)` for details. If this refers to a device node, a dependency on the respective device unit is automatically created. (See `systemd.device(5)` for more information.) This option is mandatory. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as `%%`. If this mount is a bind mount and the specified path does not exist yet it is created as directory. `Where=` Takes an absolute path of a file or directory for the mount point; in particular, the destination cannot be a symbolic link. If the mount point does not exist at the time of mounting, it is created as either a directory or a file. The former is the usual case; the latter is done only if this mount is a bind mount and the source (`What=`) is not a directory. This string must be reflected in the unit filename. (See above.) This option is mandatory. `Type=` Takes a string for the file system type. See `mount(8)` for details. This setting is optional. If the type is `overlay`, and `upperdir=` or `workdir=` are specified as options and the directories do not exist, they will be created. `Options=` Mount options to use when mounting. This takes a comma-separated list of options. This setting is optional. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as `%%`. `SloppyOptions=` Takes a boolean argument. If true, parsing of the options specified in `Options=` is relaxed, and unknown mount options are tolerated. This corresponds with `mount(8)`'s `-s` switch. Defaults to off. `LazyUnmount=` Takes a boolean argument. If true, detach the filesystem from the filesystem hierarchy at time of the unmount operation, and clean up all references to the filesystem as soon as they are not busy anymore. This corresponds with `umount(8)`'s `-l` switch. Defaults to off. `ReadWriteOnly=` Takes a boolean argument. If false, a mount point that shall be mounted read-write but cannot be mounted so is retried to be mounted read-only. If true the operation will fail immediately after the read-write mount attempt did not succeed. This corresponds with `mount(8)`'s `-w` switch. Defaults to off. `ForceUnmount=` Takes a boolean argument. If true, force an unmount (in case of an unreachable NFS system). This corresponds with `umount(8)`'s `-f` switch. Defaults to off. `DirectoryMode=` Directories of mount points (and any parent directories) are automatically created if needed. This option specifies the file system access mode used when creating these directories. Takes an access mode in octal notation. Defaults to 0755. `TimeoutSec=` Configures the time to wait for the mount command to finish. If a command does not exit within the configured time, the mount will be considered failed and be shut down again. All commands still running will be terminated forcibly via `SIGTERM`, and after another delay of this time with `SIGKILL`. (See `KillMode=` in `systemd.kill(5)`.) Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass 0 to disable the timeout logic. The default value is set from `DefaultTimeoutStartSec=` option in `systemd-system.conf(5)`. # See Also `systemd(1)`, `systemctl(1)`, `systemd-system.conf(5)`, `systemd.unit(5)`, `systemd.exec(5)`, `systemd.kill(5)`, `systemd.resource-control(5)`, `systemd.service(5)`, `systemd.device(5)`, `proc(5)`, `mount(8)`, `systemd-fstab-generator(8)`, `systemd.directives(7)`, `systemd-mount(1)` # systemd.mstack systemd systemd.mstack 7 systemd.mstack Mount stacks in self descriptive directories # Description Directories with the `.mstack/` suffix may encode 'mount stacks' for assembling OS mount hierarchies based on bind and overlay mounts, for use in `systemd-nspawn(1)`'s `--mstack=` switch or the service manager's `RootMStack=` setting for services. `.mstack/` directories may contain various files and subdirectories, where each will effect one layer of an `overlayfs` mount, or a bind mount. The name of the file or subdirectory indicates how it shall be used in the mount hierarchy. Specifically, the following names are defined: 1. A `layer@id/` directory will be turned into a layer of an overlayfs mount. The `id` identifier is used to define the order of the layers: a version sort is executed, with the first entry being the bottom layer in the `overlayfs` stack, and the last entry becoming the highest layer (precisely: highest "lowerdir") in the `overlayfs` stack. 2. Similar, a `layer@id.raw` regular file will be mounted as a DDI, and the resulting mount will be turned into an overlayfs layer, following the same sorting rules. 3. An `rw` directory will be turned into a writable layer at the very top of the `overlayfs` stack. A subdirectory `data` of it will become the "upperdir", a subdirectory `work` will become the "workdir". Note that these two subdirectories do not need to be created explicitly, they are created automatically on first use should they be missing. 4. A `bind@location/` directory will be bind mounted to the mount point indicated by the `location` identifier, in read-write fashion. The location is encoded via the same escaping logic used for naming `.mount` units, i.e. slashes become dashes. 5. Similar, a `bind@location.raw` file will be mounted as a DDI, and the resulting mount bind mounted to the specified location. 6. A `robind@location/` is treated very similar to `bind@location/`, but the resulting bind mount is read-only. 7. Similar, `robind@location.raw` creates a read-only bind mount from a DDI. 8. If a `root/` subdirectory exists, it is used as root of the resulting mount hierarchy, and only the `usr/` subtree of the overlayfs mount will be bound to `usr/` in the hierarchy. Note that each of the entry types above may be a symbolic link pointing to a directory or image file, instead a directory or image file itself. On each listed file or subdirectory type the `systemd.v(7)` functionality may be used, for automatic selection of versioned resources. Use the `systemd-mstack(1)` tool to process or mount `.mstack/` directories from the command line. # Examples The following `.mstack/` consists of two read-only overlayfs layers as DDI, plus one writable directory on top. The read-only layers are symlinked: 1. `foobar.mstack/layer@0.raw` → `../base.raw` 2. `foobar.mstack/layer@1.raw` → `../app.raw` 3. `foobar.mstack/rw/` The following `.mstack/` consists of a read-only DDI mounted to `/usr/` and writable root: 1. `waldo.mstack/layer@0.raw` → `../vendor.raw` 2. `waldo.mstack/root/` The following `.mstack/` consists of a read-only DDI mounted as root, but a writable `/var/` mounted on top: 1. `quux.mstack/layer@0.raw` → `../myapp1.raw` 2. `quux.mstack/bind:var` → `../myapp1-var/` # See Also `systemd(1)`, `systemd-mstack(1)`, `systemd-nspawn(1)`, `systemd.exec(5)`, `systemd.v(7)`, `systemd-vpick(1)` # systemd.net-naming-scheme systemd systemd.net-naming-scheme 7 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. | Prefix | Description | |--------|------------------------------------------------| | `en` | Ethernet | | `ib` | InfiniBand | | `sl` | Serial line IP (slip) | | `wl` | Wireless local area network (WLAN) | | `ww` | Wireless wide area network (WWAN) | | `mc` | Management Component Transport Protocol (MCTP) | Two character prefixes based on the type of interface The `udev(7)` `net_id` builtin exports the following device properties: `ID_NET_NAME_ONBOARD=`\`o`\; `ID_NET_NAME_ONBOARD=`\`d`\ 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. | Format | Description | |-------------------------|------------------------| | \`o`\ | PCI on-board index | | \`d`\ | DeviceTree alias index | On-board naming schemes `ID_NET_LABEL_ONBOARD=`\ This property is set based on textual label given by the firmware for on-board devices. This is only available for PCI devices. `ID_NET_NAME_MAC=`\`x`\ This name consists of the prefix, letter `x`, and 12 hexadecimal digits of the MAC address. It is available if the device has a fixed MAC address. Because this name is based on an attribute of the card itself, it remains "stable" when the device is moved (even between machines), but will change when the hardware is replaced. `ID_NET_NAME_SLOT=`\\[`P`\\]`s`\\[`f`\\]\[`n`\\|`d`\\]; `ID_NET_NAME_SLOT=`\`v`\; `ID_NET_NAME_SLOT=`\`x`\; `ID_NET_NAME_SLOT=`\\[`P`\\]`s`\\[`f`\\]\[`n`\\|`d`\\]`b`\; `ID_NET_NAME_SLOT=`\\[`P`\\]`s`\\[`f`\\]\[`n`\\|`d`\\]`u`\…\[`c`\\]\[`i`\\]; `ID_NET_NAME_SLOT=`\\[`P`\\]`s`\\[`f`\\]\[`n`\\|`d`\\]`v`\; `ID_NET_NAME_SLOT=`\\[`P`\\]`s`\\[`f`\\]\[`n`\\|`d`\\]`r`\; `ID_NET_NAME_SLOT=`\\[`P`\\]`s`\\[`f`\\]\[`n`\\|`d`\\]`S`\ 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. | Format | Description | |----|----| | \ \[`P`\\] `s`\ \[`f`\\] \[`n`\ \| `d`\\] | PCI slot number | | \ `v`\ | VIO slot number (IBM PowerVM) | | \ `X`\ | VIF interface number (Xen) | | … `b`\ | Broadcom bus (BCMA) core number | | … `u`\… \[`c`\\] \[`i`\\] | USB port number chain | | … `v`\ | SR-VIO slot number | | … `r`\ | SR-IOV slot number | | … `S`\ | Auxiliary sub-function (SF) number | Slot naming schemes The PCI domain is only prepended when it is not 0. All multi-function PCI devices will carry the `f`\ number in the device name, including the function 0 device. For non-multi-function devices, the number is suppressed if 0. The port name \ is used, or the port number `d`\ 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. Auxiliary sub-function (SF) network devices, where the network device's parent is an auxiliary device exposing a `sfnum` sysfs attribute (currently mlx5_core SFs), are named based on the underlying PCI function (the PF, or for VF-SF the PF behind the VF), with a suffix of `S` and the user-defined sub-function number from `sfnum`. This is analogous to how SR-IOV virtual function devices are named with a `v` suffix. If the SF's parent PCI function is itself an SR-IOV virtual function (VF-SF), the name is rooted at the PF and both suffixes are chained, with the `v` suffix preceding the `S` suffix (e.g. `enp193s0f0v0S88`). The PF, the VF, and the SF therefore form a stable, hierarchical sequence regardless of the VF's underlying PCI bus/device/function numbering. 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. `ID_NET_NAME_PATH=`\`c`\; `ID_NET_NAME_PATH=`\`a`\\`i`\; `ID_NET_NAME_PATH=`\`i`\`n`\; `ID_NET_NAME_PATH=`\`u`\…; `ID_NET_NAME_PATH=`\\[`P`\\]`p`\`s`\\[`f`\\]\[`n`\\|`d`\\]; `ID_NET_NAME_PATH=`\\[`P`\\]`p`\`s`\\[`f`\\]\[`n`\\|`d`\\]`b`\; `ID_NET_NAME_PATH=`\\[`P`\\]`p`\`s`\\[`f`\\]\[`n`\\|`d`\\]`u`\…\[`c`\\]\[`i`\\]; `ID_NET_NAME_PATH=`\\[`P`\\]`p`\`s`\\[`f`\\]\[`n`\\|`d`\\]`S`\ 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. | Format | Description | |----|----| | \ `c`\ | CCW or grouped CCW device identifier | | \ `a`\ \ `i`\ | ACPI path names for ARM64 platform devices | | \ `i`\ `n`\ | Netdevsim (simulated networking device) device number and port name | | \ \[`P`\\] `p`\ `s`\ \[`f`\\] \[`n`\ \| `d`\\] | PCI geographical location | | … `b`\ | Broadcom bus (BCMA) core number | | … `u`\… \[`c`\\] \[`i`\\] | USB port number chain | | … `S`\ | Auxiliary sub-function (SF) number | Path naming schemes CCW and grouped CCW devices are found in IBM System Z mainframes. Any leading zeros and dots are suppressed. For PCI, BCMA, and USB devices, the same rules as described above for slot naming are used. # History The following "naming schemes" have been defined (which may be chosen at system boot-up time via the `net.naming_scheme=` kernel command line switch, see above): `v238` This is the naming scheme that was implemented in systemd 238. `v239` Naming was changed for virtual network interfaces created with SR-IOV and NPAR and for devices where the PCI network controller device does not have a slot number associated. SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of `vport`, where \ 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 ("eth\") was used. Names are also generated for PCI devices where the PCI network controller device does not have an associated slot number itself, but one of its parents does. Previously those devices were not renamed and the kernel default was used. `v240` The `ib` prefix and stable names for infiniband devices are introduced. Previously those devices were not renamed. The ACPI index field (used in `ID_NET_NAME_ONBOARD=`) is now also used when 0. A new naming policy `NamePolicy=keep` was introduced. With this policy, if the network device name was already set by userspace, the device will not be renamed again. Previously, this naming policy applied implicitly, and now it must be explicitly requested. Effectively, this means that network devices will be renamed according to the configuration, even if they have been renamed already, if `keep` is not specified as the naming policy in the `.link` file. See `systemd.link(5)` for a description of `NamePolicy=`. `v241` `MACAddressPolicy=persistent` was extended to set MAC addresses based on the device name. Previously addresses were only based on the `ID_NET_NAME_*` attributes, which meant that interface names would never be generated for virtual devices. Now a persistent address will be generated for most devices, including in particular bridges. Note: when userspace does not set a MAC address for a bridge device, the kernel will initially assign a random address, and then change it when the first device is enslaved to the bridge. With this naming policy change, bridges get a persistent MAC address based on the bridge name instead of the first enslaved device. `v243` Support for renaming netdevsim (simulated networking) devices was added. Previously those devices were not renamed. Previously two-letter interface type prefix was prepended to `ID_NET_LABEL_ONBOARD=`. This is not done anymore. `v245` When `systemd-nspawn(1)` derives the name for the host side of the network interface created with `--network-veth` from the container name it previously simply truncated the result at 15 characters if longer (since that's the maximum length for network interface names). From now on, for any interface name that would be longer than 15 characters the last 4 characters are set to a 24bit hash value of the full interface name. This way network interface name collisions between multiple similarly named containers (who only differ in container name suffix) should be less likely (but still possible, since the 24bit hash value is very small). `v247` When a PCI slot is associated with a PCI bridge that has multiple child network controllers, the same value of the `ID_NET_NAME_SLOT` property might be derived for those controllers. This would cause a naming conflict if the property is selected as the device name. Now, we detect this situation and do not produce the `ID_NET_NAME_SLOT` property. `v249` PCI hotplug slot names for the s390 PCI driver are a hexadecimal representation of the `function_id` device attribute. This attribute is now used to build the `ID_NET_NAME_SLOT`. Before that, all slot names were parsed as decimal numbers, which could either result in an incorrect value of the `ID_NET_NAME_SLOT` property or none at all. Some firmware and hypervisor implementations report 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. `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). `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. `v252` Added naming scheme for platform devices with devicetree aliases. `v253` Set `ID_NET_NAME_PATH` for usb devices not connected via a PCI bus. `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*. `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`. `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. `v258` When no renaming is requested, `ID_NET_NAME` property is now equivalent to `INTERFACE` property. `v259` The naming scheme based on devicetree aliases was extended to support WLAN devices. `v260` MCTP interfaces are now assigned persistent names, using a `mc` prefix. `v261` Stable names are now generated for auxiliary sub-function (SF) network devices (such as `mlx5_core` SFs). The name is built from the parent PCI Physical Function's path with an `Ssfnum` suffix, where \ is the user-defined SF number (the value passed to `devlink port add … sfnum N`, exposed by the kernel as the `sfnum` sysfs attribute on the auxiliary device). This is analogous to the `vN` suffix used for SR-IOV virtual functions; for SFs hosted on SR-IOV VFs (VF-SF), the two suffixes are chained on top of the PF's base name. 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 "`n`\" suffix to the device name. `ID_NET_NAME_ALLOW=`\ 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`. `ID_NET_NAME_ALLOW_sysfsattr=BOOL` This udev property explicitly states if udev shall use the specified \, when composing the device name. 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
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 ...
PCI Ethernet card with firmware index "1"
ID_NET_NAME_ONBOARD=eno1 ID_NET_NAME_ONBOARD_LABEL=Ethernet Port 1
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
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
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
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
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
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
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
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
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](https://systemd.io/PREDICTABLE_INTERFACE_NAMES), `systemd-nspawn(1)` # systemd.netdev systemd systemd.netdev 5 systemd.netdev Virtual Network Device configuration `netdev.netdev` # Description A plain ini-style text file that encodes configuration about a virtual network device, used by `systemd-networkd(8)`. See `systemd.syntax(7)` for a general description of the syntax. The main Virtual Network Device file must have the extension `.netdev`; other extensions are ignored. Virtual network devices are created as soon as `systemd-networkd` is started if possible. If a netdev with the specified name already exists, `systemd-networkd` will try to update the config if the kind of the existing netdev is equivalent to the requested one, otherwise (e.g. when bridge device `foo` exists but bonding device with the same name is configured in a .netdev file) use the existing netdev as-is rather than replacing with the requested netdev. Note, several settings (e.g. vlan ID) cannot be changed after the netdev is created. To change such settings, it is necessary to first remove the existing netdev, and then run `networkctl reload` command or restart `systemd-networkd`. See also `networkctl(1)`. The `.netdev` files are read from the files located in the system network directory `/usr/lib/systemd/network` and `/usr/local/lib/systemd/network`, the volatile runtime network directory `/run/systemd/network` and the local administration network directory `/etc/systemd/network`. All configuration files are collectively sorted and processed in alphanumeric order, regardless of the directories in which they live. However, files with identical filenames replace each other. It is recommended that each filename is prefixed with a number smaller than `70` (e.g. `10-vlan.netdev`). Otherwise, `.netdev` files generated by `systemd-network-generator.service(8)` may take precedence over user configured files. Files in `/etc/` have the highest priority, files in `/run/` take precedence over files with the same name in `/usr/lib/`. This can be used to override a system-supplied configuration file with a local file if needed. As a special case, an empty file (file size 0) or symlink with the same name pointing to `/dev/null` disables the configuration file entirely (it is "masked"). Along with the netdev file `foo.netdev`, a "drop-in" directory `foo.netdev.d/` may exist. All files with the suffix `.conf` from this directory will be merged in the alphanumeric order and parsed after the main file itself has been parsed. This is useful to alter or add configuration settings, without having to modify the main configuration file. Each drop-in file must have appropriate section headers. In addition to `/etc/systemd/network`, drop-in `.d` directories can be placed in `/usr/lib/systemd/network` or `/run/systemd/network` directories. Drop-in files in `/etc/` take precedence over those in `/run/` which in turn take precedence over those in `/usr/lib/`. Drop-in files under any of these directories take precedence over the main netdev file wherever located. (Of course, since `/run/` is temporary and `/usr/lib/` is for vendors, it is unlikely drop-ins should be used in either of those places.) # Supported netdev kinds The following kinds of virtual network devices may be configured in `.netdev` files: | Kind | Description | |----|----| | `bond` | A bond device is an aggregation of all its slave devices. See [Linux Ethernet Bonding Driver HOWTO](https://docs.kernel.org/networking/bonding.html) for details. | | `bridge` | A bridge device is a software switch, and each of its slave devices and the bridge itself are ports of the switch. | | `dummy` | A dummy device drops all packets sent to it. | | `gre` | A Level 3 GRE tunnel over IPv4. See [RFC 2784](https://tools.ietf.org/html/rfc2784) for details. Name `gre0` should not be used, as the kernel creates a device with this name when the corresponding kernel module is loaded. | | `gretap` | A Level 2 GRE tunnel over IPv4. Name `gretap0` should not be used, as the kernel creates a device with this name when the corresponding kernel module is loaded. | | `erspan` | ERSPAN mirrors traffic on one or more source ports and delivers the mirrored traffic to one or more destination ports on another switch. The traffic is encapsulated in generic routing encapsulation (GRE) and is therefore routable across a layer 3 network between the source switch and the destination switch. Name `erspan0` should not be used, as the kernel creates a device with this name when the corresponding kernel module is loaded. | | `ip6gre` | A Level 3 GRE tunnel over IPv6. | | `ip6tnl` | An IPv4 or IPv6 tunnel over IPv6 | | `ip6gretap` | A Level 2 GRE tunnel over IPv6. | | `ipip` | An IPv4 over IPv4 tunnel. | | `ipvlan` | An IPVLAN device is a stacked device which receives packets from its underlying device based on IP address filtering. | | `ipvtap` | An IPVTAP device is a stacked device which receives packets from its underlying device based on IP address filtering and can be accessed using the tap user space interface. | | `macvlan` | A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering. | | `macvtap` | A macvtap device is a stacked device which receives packets from its underlying device based on MAC address filtering. | | `sit` | An IPv6 over IPv4 tunnel. | | `tap` | A persistent Level 2 tunnel between a network device and a device node. | | `tun` | A persistent Level 3 tunnel between a network device and a device node. | | `veth` | An Ethernet tunnel between a pair of network devices. | | `vlan` | A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging. See [IEEE 802.1Q](http://www.ieee802.org/1/pages/802.1Q.html) for details. | | `vti` | An IPv4 over IPSec tunnel. | | `vti6` | An IPv6 over IPSec tunnel. | | `vxlan` | A virtual extensible LAN (vxlan), for connecting Cloud computing deployments. | | `geneve` | A GEneric NEtwork Virtualization Encapsulation (GENEVE) netdev driver. | | `hsr` | A High-availability Seamless Redundancy (HSR) or Parallel Redundancy Protocol (PRP) interface. HSR and PRP are two protocols defined by the IEC 62439-3 standard, providing seamless failover against failure of any single network component. | | `l2tp` | A Layer 2 Tunneling Protocol (L2TP) is a tunneling protocol used to support virtual private networks (VPNs) or as part of the delivery of services by ISPs. It does not provide any encryption or confidentiality by itself | | `macsec` | Media Access Control Security (MACsec) is an 802.1AE IEEE industry-standard security technology that provides secure communication for all traffic on Ethernet links. MACsec provides point-to-point security on Ethernet links between directly connected nodes and is capable of identifying and preventing most security threats. | | `vrf` | A Virtual Routing and Forwarding ([VRF](https://docs.kernel.org/networking/vrf.html)) interface to create separate routing and forwarding domains. | | `vcan` | The virtual CAN driver (vcan). Similar to the network loopback devices, vcan offers a virtual local CAN interface. | | `vxcan` | The virtual CAN tunnel driver (vxcan). Similar to the virtual ethernet driver veth, vxcan implements a local CAN traffic tunnel between two virtual CAN network devices. When creating a vxcan, two vxcan devices are created as pair. When one end receives the packet it appears on its pair and vice versa. The vxcan can be used for cross namespace communication. | | `wireguard` | WireGuard Secure Network Tunnel. | | `nlmon` | A Netlink monitor device. Use an nlmon device when you want to monitor system Netlink messages. | | `fou` | Foo-over-UDP tunneling. | | `xfrm` | A virtual tunnel interface like vti/vti6 but with several advantages. | | `ifb` | The Intermediate Functional Block (ifb) pseudo network interface acts as a QoS concentrator for multiple different sources of traffic. | | `bareudp` | Bare UDP tunnels provide a generic L3 encapsulation support for tunnelling different L3 protocols like MPLS, IP etc. inside of a UDP tunnel. | | `batadv` | [B.A.T.M.A.N. Advanced](https://www.open-mesh.org/projects/open-mesh/wiki) is a routing protocol for multi-hop mobile ad-hoc networks which operates on layer 2. | | `ipoib` | An IP over Infiniband subinterface. | | `wlan` | A virtual wireless network (WLAN) interface. | Supported kinds of virtual network devices # \[Match\] Section Options A virtual network device is only created if the \[Match\] section matches the current environment, or if the section is empty. The following keys are accepted: # \[NetDev\] Section Options The \[NetDev\] section accepts the following keys: `Description=` A free-form description of the netdev. `Name=` The interface name used when creating the netdev. This setting is compulsory. `Kind=` The netdev kind. This setting is compulsory. See the `Supported netdev kinds` section for the valid keys. `MTUBytes=` The maximum transmission unit in bytes to set for the device. The usual suffixes K, M, G are supported and are understood to the base of 1024. For `tun` or `tap` devices, `MTUBytes=` setting is not currently supported in \[NetDev\] section. Please specify it in \[Link\] section of corresponding `systemd.network(5)` files. `MACAddress=` Specifies the MAC address to use for the device, or takes the special value `none`. When `none`, `systemd-networkd` does not request the MAC address for the device, and the kernel will assign a random MAC address. For `tun`, `tap`, or `l2tp` devices, the `MACAddress=` setting in the \[NetDev\] section is not supported and will be ignored. Please specify it in the \[Link\] section of the corresponding `systemd.network(5)` file. If this option is not set, `vlan` device inherits the MAC address of the master interface. For other kind of netdevs, if this option is not set, then the MAC address is generated based on the interface name and the `machine-id(5)`. Note, even if `none` is specified, `systemd-udevd` will assign the persistent MAC address for the device, as `99-default.link` has `MACAddressPolicy=persistent`. So, it is also necessary to create a custom .link file for the device, if the MAC address assignment is not desired. # \[Bridge\] Section Options The \[Bridge\] section only applies for netdevs of kind `bridge`, and accepts the following keys: `HelloTimeSec=` HelloTimeSec specifies the number of seconds between two hello packets sent out by the root bridge and the designated bridges. Hello packets are used to communicate information about the topology throughout the entire bridged local area network. `MaxAgeSec=` MaxAgeSec specifies the number of seconds of maximum message age. If the last seen (received) hello packet is more than this number of seconds old, the bridge in question will start the takeover procedure in attempt to become the Root Bridge itself. `ForwardDelaySec=` ForwardDelaySec specifies the number of seconds spent in each of the Listening and Learning states before the Forwarding state is entered. `AgeingTimeSec=` This specifies the number of seconds a MAC Address will be kept in the forwarding database after having a packet received from this MAC Address. `Priority=` The priority of the bridge. An integer between 0 and 65535. A lower value means higher priority. The bridge having the lowest priority will be elected as root bridge. `GroupForwardMask=` A 16-bit bitmask represented as an integer which allows forwarding of link local frames with 802.1D reserved addresses (01:80:C2:00:00:0X). A logical AND is performed between the specified bitmask and the exponentiation of 2^X, the lower nibble of the last octet of the MAC address. For example, a value of 8 would allow forwarding of frames addressed to 01:80:C2:00:00:03 (802.1X PAE). `DefaultPVID=` This specifies the default port VLAN ID of a newly attached bridge port. Set this to an integer in the range 1…4094 or `none` to disable the PVID. `MulticastQuerier=` Takes a boolean. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel. If enabled, the kernel will send general ICMP queries from a zero source address. This feature should allow faster convergence on startup, but it causes some multicast-aware switches to misbehave and disrupt forwarding of multicast packets. When unset, the kernel's default will be used. `MulticastSnooping=` Takes a boolean. This setting controls the IFLA_BR_MCAST_SNOOPING option in the kernel. If enabled, IGMP snooping monitors the Internet Group Management Protocol (IGMP) traffic between hosts and multicast routers. When unset, the kernel's default will be used. `VLANFiltering=` Takes a boolean. This setting controls the IFLA_BR_VLAN_FILTERING option in the kernel. If enabled, the bridge will be started in VLAN-filtering mode. When unset, the kernel's default will be used. `VLANProtocol=` Allows setting the protocol used for VLAN filtering. Takes `802.1q` or, `802.1ad`, and defaults to unset and kernel's default is used. `STP=` Takes a boolean. This enables the bridge's Spanning Tree Protocol (STP). When unset, the kernel's default will be used. `MulticastIGMPVersion=` Allows changing bridge's multicast Internet Group Management Protocol (IGMP) version. Takes an integer 2 or 3. When unset, the kernel's default will be used. `FDBMaxLearned=` Specifies the maximum number of learned Ethernet addresses for the bridge. When the limit is reached, no more addresses are learned. When unset, the kernel's default will be used. 0 disables the limit. `LinkLocalLearning=` Takes a boolean. This enables learning source addresses from link local frames. When unset, the kernel's default will be used. # \[VLAN\] Section Options The \[VLAN\] section only applies for netdevs of kind `vlan`, and accepts the following key: `Id=` The VLAN ID to use. An integer in the range 0…4094. This setting is compulsory. `Protocol=` Allows setting the protocol used for the VLAN interface. Takes `802.1q` or, `802.1ad`, and defaults to unset and kernel's default is used. `GVRP=` Takes a boolean. The Generic VLAN Registration Protocol (GVRP) is a protocol that allows automatic learning of VLANs on a network. When unset, the kernel's default will be used. `MVRP=` Takes a boolean. Multiple VLAN Registration Protocol (MVRP) formerly known as GARP VLAN Registration Protocol (GVRP) is a standards-based Layer 2 network protocol, for automatic configuration of VLAN information on switches. It was defined in the 802.1ak amendment to 802.1Q-2005. When unset, the kernel's default will be used. `LooseBinding=` Takes a boolean. The VLAN loose binding mode, in which only the operational state is passed from the parent to the associated VLANs, but the VLAN device state is not changed. When unset, the kernel's default will be used. `ReorderHeader=` Takes a boolean. When enabled, the VLAN reorder header is used and VLAN interfaces behave like physical interfaces. When unset, the kernel's default will be used. `EgressQOSMaps=`; `IngressQOSMaps=` Defines a mapping of Linux internal packet priority (`SO_PRIORITY`) to VLAN header PCP field for outgoing and incoming frames, respectively. Takes a whitespace-separated list of integer pairs, where each integer must be in the range 1…4294967294, in the format `from`-`to`, e.g., `21-7 45-5`. Note that `from` must be greater than or equal to `to`. When unset, the kernel's default will be used. # \[MACVLAN\] Section Options The \[MACVLAN\] section only applies for netdevs of kind `macvlan`, and accepts the following key: `Mode=` The MACVLAN mode to use. The supported options are `private`, `vepa`, `bridge`, `passthru`, and `source`. `SourceMACAddress=` A whitespace-separated list of remote hardware addresses allowed on the MACVLAN. This option only has an effect in source mode. Use full colon-, hyphen- or dot-delimited hexadecimal. This option may appear more than once, in which case the lists are merged. If the empty string is assigned to this option, the list of hardware addresses defined prior to this is reset. Defaults to unset. `BroadcastMulticastQueueLength=` Specifies the length of the receive queue for broadcast/multicast packets. An unsigned integer in the range 0…4294967294. Defaults to unset. `BroadcastQueueThreshold=` Controls the threshold for broadcast queueing of the macvlan device. Takes the special value `no`, or an integer in the range 0…2147483647. When `no` is specified, the broadcast queueing is disabled altogether. When an integer is specified, a multicast address will be queued as broadcast if the number of devices using the macvlan is greater than the given value. Defaults to unset, and the kernel default will be used. # \[MACVTAP\] Section Options The \[MACVTAP\] section applies for netdevs of kind `macvtap` and accepts the same keys as \[MACVLAN\]. # \[IPVLAN\] Section Options The \[IPVLAN\] section only applies for netdevs of kind `ipvlan`, and accepts the following key: `Mode=` The IPVLAN mode to use. The supported options are `L2`,`L3` and `L3S`. `Flags=` The IPVLAN flags to use. The supported options are `bridge`,`private` and `vepa`. # \[IPVTAP\] Section Options The \[IPVTAP\] section only applies for netdevs of kind `ipvtap` and accepts the same keys as \[IPVLAN\]. # \[VXLAN\] Section Options The \[VXLAN\] section only applies for netdevs of kind `vxlan`, and accepts the following keys: `VNI=` The VXLAN Network Identifier (or VXLAN Segment ID). Takes a number in the range 1…16777215. Ignored if `External=` is set to true. `Remote=` Configures destination IP address. `Local=` Configures local IP address. It must be an address on the underlying interface of the VXLAN interface, or one of the special values `ipv4_link_local`, `ipv6_link_local`, `dhcp4`, `dhcp6`, and `slaac`. If one of the special values is specified, an address which matches the corresponding type on the underlying interface will be used. Defaults to unset. `Group=` Configures VXLAN multicast group IP address. All members of a VXLAN must use the same multicast group address. `TOS=` The Type Of Service byte value for a vxlan interface. `TTL=` A fixed Time To Live N on Virtual eXtensible Local Area Network packets. Takes `inherit` or a number in the range 0…255. 0 is a special value meaning inherit the inner protocol's TTL value. `inherit` means that it will inherit the outer protocol's TTL value. `MacLearning=` Takes a boolean. When true, enables dynamic MAC learning to discover remote MAC addresses. `FDBAgeingSec=` The lifetime of Forwarding Database entry learnt by the kernel, in seconds. `MaximumFDBEntries=` Configures maximum number of FDB entries. `ReduceARPProxy=` Takes a boolean. When true, bridge-connected VXLAN tunnel endpoint answers ARP requests from the local bridge on behalf of remote [ Distributed Overlay Virtual Ethernet (DOVE)](https://en.wikipedia.org/wiki/Distributed_Overlay_Virtual_Ethernet) clients. Defaults to false. `L2MissNotification=` Takes a boolean. When true, enables netlink LLADDR miss notifications. `L3MissNotification=` Takes a boolean. When true, enables netlink IP address miss notifications. `RouteShortCircuit=` Takes a boolean. When true, route short circuiting is turned on. `UDPChecksum=` Takes a boolean. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on. `UDP6ZeroChecksumTx=` Takes a boolean. When true, sending zero checksums in VXLAN/IPv6 is turned on. `UDP6ZeroChecksumRx=` Takes a boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on. `RemoteChecksumTx=` Takes a boolean. When true, remote transmit checksum offload of VXLAN is turned on. `RemoteChecksumRx=` Takes a boolean. When true, remote receive checksum offload in VXLAN is turned on. `GroupPolicyExtension=` Takes a boolean. When true, it enables Group Policy VXLAN extension security label mechanism across network peers based on VXLAN. For details about the Group Policy VXLAN, see the [ VXLAN Group Policy ](https://tools.ietf.org/html/draft-smith-vxlan-group-policy) document. Defaults to false. `GenericProtocolExtension=` Takes a boolean. When true, Generic Protocol Extension extends the existing VXLAN protocol to provide protocol typing, OAM, and versioning capabilities. For details about the VXLAN GPE Header, see the [ Generic Protocol Extension for VXLAN ](https://tools.ietf.org/html/draft-ietf-nvo3-vxlan-gpe-07) document. If destination port is not specified and Generic Protocol Extension is set, the default port of 4790 is used. Defaults to false. `DestinationPort=` Configures the default destination UDP port. If the destination port is not specified, the Linux kernel default will be used. Set to 4789 to get the IANA assigned value. `PortRange=` Configures the source port range for the VXLAN. The kernel assigns the source UDP port based on the flow to help the receiver to do load balancing. When this option is not set, the normal range of local UDP ports is used. `FlowLabel=` Specifies the flow label to use in outgoing packets. The valid range is 0-1048575. `IPDoNotFragment=` Allows setting the IPv4 Do not Fragment (DF) bit in outgoing packets, or to inherit its value from the IPv4 inner header. Takes a boolean value, or `inherit`. Set to `inherit` if the encapsulated protocol is IPv6. When unset, the kernel's default will be used. `Independent=` Takes a boolean. When true, the vxlan interface is created without any underlying network interface. Defaults to false, which means that a .network file that requests this VXLAN interface using `VXLAN=` is required for the VXLAN to be created. `External=` Takes a boolean. When true, the vxlan interface is externally controlled, for example by an EVPN control plane. Defaults to false. `VNIFilter=` Takes a boolean. When true, the interface is capable of filtering VNI filtering. Ignored if `External=` is set to false. Defaults to false. # \[GENEVE\] Section Options The \[GENEVE\] section only applies for netdevs of kind `geneve`, and accepts the following keys: `Id=` Specifies the Virtual Network Identifier (VNI) to use, a number between 0 and 16777215. This field is mandatory. `Remote=` Specifies the unicast destination IP address to use in outgoing packets. `TOS=` Specifies the TOS value to use in outgoing packets. Takes a number between 1 and 255. `TTL=` Accepts the same values as in the \[VXLAN\] section, except that when unset or set to 0, the kernel's default will be used, meaning that packet TTL will be set from `/proc/sys/net/ipv4/ip_default_ttl`. `UDPChecksum=` Takes a boolean. When true, specifies that UDP checksum is calculated for transmitted packets over IPv4. `UDP6ZeroChecksumTx=` Takes a boolean. When true, skip UDP checksum calculation for transmitted packets over IPv6. `UDP6ZeroChecksumRx=` Takes a boolean. When true, allows incoming UDP packets over IPv6 with zero checksum field. `DestinationPort=` Specifies destination port. Defaults to 6081. If not set or assigned the empty string, the default port of 6081 is used. `FlowLabel=` Specifies the flow label to use in outgoing packets. `IPDoNotFragment=` Accepts the same key as in \[VXLAN\] section. `InheritInnerProtocol=` Takes a boolean. When true, inner Layer 3 protocol is set as Protocol Type in the GENEVE header instead of Ethernet. Defaults to false. # \[HSR\] Section Options The \[HSR\] section only applies for netdevs of kind `hsr`, and accepts the following keys: `Ports=` Specifies the underlying interfaces. This field is mandatory and must contain exactly two interface names separated by space. This option can be specified multiples times, hence the two cases below have the same result: Ports=eth1 eth2 Ports=eth1 Ports=eth2 All the previous assignments are cleared when an empty string is specified. `Protocol=` Specifies the protocol used by the interface. Takes one of `hsr` or `prp`. Defaults to `hsr`. Both protocols work by sending two copies of every outgoing frame, one for each of the two ports. The destination node receives the two frames and keeps only the first one. If a link fails, only one of the two frames is received. HSR uses a ring topology where the two outgoing frames are sent in opposite directions in the ring. PRP doesn't need a specific topology, but it requires two completely redundant networks attached to the two ports. `Supervision=` Specifies the last byte of the destination MAC address of supervision frames. Takes a number between 0 and 255. Defaults to 0. Supervision frames are used by the HSR and the PRP protocols to monitor the integrity of the network and the presence of nodes. The first 5 bytes of the destination MAC are always 01:15:4E:00:01 while the last byte is configurable. # \[BareUDP\] Section Options The \[BareUDP\] section only applies for netdevs of kind `bareudp`, and accepts the following keys: `DestinationPort=` Specifies the destination UDP port (in range 1…65535). This is mandatory. `EtherType=` Specifies the L3 protocol. Takes one of `ipv4`, `ipv6`, `mpls-uc` or `mpls-mc`. This is mandatory. `MinSourcePort=` Specifies the lowest value of the UDP tunnel source port (in range 1…65535). Defaults to unset. # \[L2TP\] Section Options The \[L2TP\] section only applies for netdevs of kind `l2tp`, and accepts the following keys: `TunnelId=` Specifies the tunnel identifier. Takes a number in the range 1…4294967295. The value used must match the `PeerTunnelId=` value being used at the peer. This setting is compulsory. `PeerTunnelId=` Specifies the peer tunnel id. Takes a number in the range 1…4294967295. The value used must match the `TunnelId=` value being used at the peer. This setting is compulsory. `Remote=` Specifies the IP address of the remote peer. This setting is compulsory. `Local=` Specifies the IP address of a local interface. Takes an IP address, or the special values `auto`, `static`, or `dynamic`. Optionally a name of a local interface can be specified after `@`, e.g. `192.168.0.1@eth0` or `auto@eth0`. When an address is specified, then a local or specified interface must have the address, and the remote address must be accessible through the local address. If `auto`, then one of the addresses on a local or specified interface which is accessible to the remote address will be used. Similarly, if `static` or `dynamic` is set, then one of the static or dynamic addresses will be used. Defaults to `auto`. `EncapsulationType=` Specifies the encapsulation type of the tunnel. Takes one of `udp` or `ip`. `UDPSourcePort=` Specifies the UDP source port to be used for the tunnel. When UDP encapsulation is selected it is mandatory. Ignored when IP encapsulation is selected. `UDPDestinationPort=` Specifies destination port. When UDP encapsulation is selected it is mandatory. Ignored when IP encapsulation is selected. `UDPChecksum=` Takes a boolean. When true, specifies that UDP checksum is calculated for transmitted packets over IPv4. `UDP6ChecksumTx=` Takes a boolean. When true, skip UDP checksum calculation for transmitted packets over IPv6. `UDP6ChecksumRx=` Takes a boolean. When true, allows incoming UDP packets over IPv6 with zero checksum field. # \[L2TPSession\] Section Options The \[L2TPSession\] section only applies for netdevs of kind `l2tp`, and accepts the following keys: `Name=` Specifies the name of the session. This setting is compulsory. `SessionId=` Specifies the session identifier. Takes a number in the range 1…4294967295. The value used must match the `SessionId=` value being used at the peer. This setting is compulsory. `PeerSessionId=` Specifies the peer session identifier. Takes a number in the range 1…4294967295. The value used must match the `PeerSessionId=` value being used at the peer. This setting is compulsory. `Layer2SpecificHeader=` Specifies the layer 2 specific header type of the session. One of `none` or `default`. Defaults to `default`. # \[MACsec\] Section Options The \[MACsec\] section only applies for network devices of kind `macsec`, and accepts the following keys: `Port=` Specifies the port to be used for the MACsec transmit channel. The port is used to make secure channel identifier (SCI). Takes a value between 1 and 65535. Defaults to unset. `Encrypt=` Takes a boolean. When true, enable encryption. Defaults to unset. # \[MACsecReceiveChannel\] Section Options The \[MACsecReceiveChannel\] section only applies for network devices of kind `macsec`, and accepts the following keys: `Port=` Specifies the port to be used for the MACsec receive channel. The port is used to make secure channel identifier (SCI). Takes a value between 1 and 65535. This option is compulsory, and is not set by default. `MACAddress=` Specifies the MAC address to be used for the MACsec receive channel. The MAC address used to make secure channel identifier (SCI). This setting is compulsory, and is not set by default. # \[MACsecTransmitAssociation\] Section Options The \[MACsecTransmitAssociation\] section only applies for network devices of kind `macsec`, and accepts the following keys: `PacketNumber=` Specifies the packet number to be used for replay protection and the construction of the initialization vector (along with the secure channel identifier \[SCI\]). Takes a value between 1-4,294,967,295. Defaults to unset. `KeyId=` Specifies the identification for the key. Takes a number between 0-255. This option is compulsory, and is not set by default. `Key=` Specifies the encryption key used in the transmission channel. The same key must be configured on the peer’s matching receive channel. This setting is compulsory, and is not set by default. Takes a 128-bit key encoded in a hexadecimal string, for example `dffafc8d7b9a43d5b9a3dfbbf6a30c16`. `KeyFile=` Takes an absolute path to a file which contains a 128-bit key encoded in a hexadecimal string, which will be used in the transmission channel. When this option is specified, `Key=` is ignored. Note that the file must be readable by the user `systemd-network`, so it should be, e.g., owned by `root:systemd-network` with a `0640` file mode. If the path refers to an `AF_UNIX` stream socket in the file system a connection is made to it and the key read from it. `Activate=` Takes a boolean. If enabled, then the security association is activated. Defaults to unset. `UseForEncoding=` Takes a boolean. If enabled, then the security association is used for encoding. Only one \[MACsecTransmitAssociation\] section can enable this option. When enabled, `Activate=yes` is implied. Defaults to unset. # \[MACsecReceiveAssociation\] Section Options The \[MACsecReceiveAssociation\] section only applies for network devices of kind `macsec`, and accepts the following keys: `Port=` Accepts the same key as in \[MACsecReceiveChannel\] section. `MACAddress=` Accepts the same key as in \[MACsecReceiveChannel\] section. `PacketNumber=` Accepts the same key as in \[MACsecTransmitAssociation\] section. `KeyId=` Accepts the same key as in \[MACsecTransmitAssociation\] section. `Key=` Accepts the same key as in \[MACsecTransmitAssociation\] section. `KeyFile=` Accepts the same key as in \[MACsecTransmitAssociation\] section. `Activate=` Accepts the same key as in \[MACsecTransmitAssociation\] section. # \[Tunnel\] Section Options The \[Tunnel\] section only applies for netdevs of kind `ipip`, `sit`, `gre`, `gretap`, `ip6gre`, `ip6gretap`, `vti`, `vti6`, `ip6tnl`, and `erspan` and accepts the following keys: `External=` Takes a boolean value. When true, then the tunnel is externally controlled, which is also known as collect metadata mode, and most settings below like `Local=` or `Remote=` are ignored. This implies `Independent=`. Defaults to false. `Local=` A static local address for tunneled packets. It must be an address on another interface of this host, or one of the special values `any`, `ipv4_link_local`, `ipv6_link_local`, `dhcp4`, `dhcp6`, `dhcp_pd`, and `slaac`. If one of the special values except for `any` is specified, an address which matches the corresponding type on the underlying interface will be used. Defaults to `any`. `Remote=` The remote endpoint of the tunnel. Takes an IP address or the special value `any`. `TOS=` The Type Of Service byte value for a tunnel interface. For details about the TOS, see the [ Type of Service in the Internet Protocol Suite ](http://tools.ietf.org/html/rfc1349) document. `TTL=` A fixed Time To Live N on tunneled packets. N is a number in the range 1…255. 0 is a special value meaning that packets inherit the TTL value. The default value for IPv4 tunnels is 0 (inherit). The default value for IPv6 tunnels is 64. `DiscoverPathMTU=` Takes a boolean. When true, enables Path MTU Discovery on the tunnel. When `IgnoreDontFragment=` is enabled, defaults to false. Otherwise, defaults to true. `IgnoreDontFragment=` Takes a boolean. When true, enables IPv4 Don't Fragment (DF) suppression on the tunnel. Defaults to false. Note that if `IgnoreDontFragment=` is set to true, `DiscoverPathMTU=` cannot be set to true. Only applicable to GRE, GRETAP, and ERSPAN tunnels. `IPv6FlowLabel=` Configures the 20-bit flow label (see [ RFC 6437](https://tools.ietf.org/html/rfc6437)) field in the IPv6 header (see [ RFC 2460](https://tools.ietf.org/html/rfc2460)), which is used by a node to label packets of a flow. It is only used for IPv6 tunnels. A flow label of zero is used to indicate packets that have not been labeled. It can be configured to a value in the range 0…0xFFFFF, or be set to `inherit`, in which case the original flowlabel is used. `CopyDSCP=` Takes a boolean. When true, the Differentiated Service Code Point (DSCP) field will be copied to the inner header from outer header during the decapsulation of an IPv6 tunnel packet. DSCP is a field in an IP packet that enables different levels of service to be assigned to network traffic. Defaults to `no`. `EncapsulationLimit=` The Tunnel Encapsulation Limit option specifies how many additional levels of encapsulation are permitted to be prepended to the packet. For example, a Tunnel Encapsulation Limit option containing a limit value of zero means that a packet carrying that option may not enter another tunnel before exiting the current tunnel. (see [ RFC 2473](https://tools.ietf.org/html/rfc2473#section-4.1.1)). The valid range is 0…255 and `none`. Defaults to 4. `Key=` The `Key=` parameter specifies the same key to use in both directions (`InputKey=` and `OutputKey=`). The `Key=` is either a number or an IPv4 address-like dotted quad. It is used as mark-configured SAD/SPD entry as part of the lookup key (both in data and control path) in IP XFRM (framework used to implement IPsec protocol). See [ ip-xfrm — transform configuration](https://man7.org/linux/man-pages/man8/ip-xfrm.8.html) for details. It is only used for VTI/VTI6, GRE, GRETAP, and ERSPAN tunnels. `InputKey=` The `InputKey=` parameter specifies the key to use for input. The format is same as `Key=`. It is only used for VTI/VTI6, GRE, GRETAP, and ERSPAN tunnels. `OutputKey=` The `OutputKey=` parameter specifies the key to use for output. The format is same as `Key=`. It is only used for VTI/VTI6, GRE, GRETAP, and ERSPAN tunnels. `Mode=` Specifies the tunnel mode. Acceptable values depend on the tunnel kind.
Supported tunnel modes
Kind Mode Description
ipip ipip IPv4 over IPv4 (default)
any both IPv4 and IPv6 over IPv4
sit ipip IPv4 over IPv4
ip6ip IPv6 over IPv4 (default)
any both IPv4 and IPv6 over IPv4
ip6tnl ipip6 IPv4 over IPv6
ip6ip6 IPv6 over IPv6
any both IPv4 and IPv6 over IPv6 (default)
`Independent=` Takes a boolean. When false (the default), the tunnel is always created over some network device, and a .network file that requests this tunnel using `Tunnel=` is required for the tunnel to be created. When true, the tunnel is created independently of any network as "tunnel@NONE". `AssignToLoopback=` Takes a boolean. If set to `yes`, the loopback interface `lo` is used as the underlying device of the tunnel interface. Defaults to `no`. `AllowLocalRemote=` Takes a boolean. When true allows tunnel traffic on `ip6tnl` devices where the remote endpoint is a local host address. When unset, the kernel's default will be used. `FooOverUDP=` Takes a boolean. Specifies whether `FooOverUDP=` tunnel is to be configured. Defaults to false. This takes effects only for IPIP, SIT, GRE, and GRETAP tunnels. For more detail information see [Foo over UDP](https://lwn.net/Articles/614348) `FOUDestinationPort=` This setting specifies the UDP destination port for encapsulation. This field is mandatory when `FooOverUDP=yes`, and is not set by default. `FOUSourcePort=` This setting specifies the UDP source port for encapsulation. Defaults to `0` — that is, the source port for packets is left to the network stack to decide. `Encapsulation=` Accepts the same key as in the \[FooOverUDP\] section. `IPv6RapidDeploymentPrefix=` Reconfigure the tunnel for [IPv6 Rapid Deployment](https://tools.ietf.org/html/rfc5569), also known as 6rd. The value is an ISP-specific IPv6 prefix with a non-zero length. Only applicable to SIT tunnels. `ISATAP=` Takes a boolean. If set, configures the tunnel as Intra-Site Automatic Tunnel Addressing Protocol (ISATAP) tunnel. Only applicable to SIT tunnels. When unset, the kernel's default will be used. `SerializeTunneledPackets=` Takes a boolean. If set to yes, then packets are serialized. Only applies for GRE, GRETAP, and ERSPAN tunnels. When unset, the kernel's default will be used. `ERSPANVersion=` Specifies the ERSPAN version number. Takes 0 for version 0 (a.k.a. type I), 1 for version 1 (a.k.a. type II), or 2 for version 2 (a.k.a. type III). Defaults to 1. `ERSPANIndex=` Specifies the ERSPAN v1 index field for the interface. Takes an integer in the range 0…1048575, which is associated with the ERSPAN traffic's source port and direction. Only used when `ERSPANVersion=1`. Defaults to 0. `ERSPANDirection=` Specifies the ERSPAN v2 mirrored traffic's direction. Takes `ingress` or `egress`. Only used when `ERSPANVersion=2`. Defaults to `ingress`. `ERSPANHardwareId=` Specifies a unique identifier of the ERSPAN v2 engine. Takes an integer in the range 0…63. Only used when `ERSPANVersion=2`. Defaults to 0. # \[FooOverUDP\] Section Options The \[FooOverUDP\] section only applies for netdevs of kind `fou` and accepts the following keys: `Encapsulation=` Specifies the encapsulation mechanism used to store networking packets of various protocols inside the UDP packets. Supports the following values: `FooOverUDP` provides the simplest no-frills model of UDP encapsulation, it simply encapsulates packets directly in the UDP payload. `GenericUDPEncapsulation` is a generic and extensible encapsulation, it allows encapsulation of packets for any IP protocol and optional data as part of the encapsulation. For more detailed information see [Generic UDP Encapsulation](https://lwn.net/Articles/615044). Defaults to `FooOverUDP`. `Port=` Specifies the port number where the encapsulated packets will arrive. Those packets will be removed and manually fed back into the network stack with the encapsulation removed to be sent to the real destination. This option is mandatory. `PeerPort=` Specifies the peer port number. Defaults to unset. Note that when peer port is set `Peer=` address is mandatory. `Protocol=` The `Protocol=` specifies the protocol number of the packets arriving at the UDP port. When `Encapsulation=FooOverUDP`, this field is mandatory and is not set by default. Takes an IP protocol name such as `gre` or `ipip`, or an integer within the range 1…255. When `Encapsulation=GenericUDPEncapsulation`, this must not be specified. `Peer=` Configures peer IP address. Note that when peer address is set `PeerPort=` is mandatory. `Local=` Configures local IP address. # \[Peer\] Section Options The \[Peer\] section only applies for netdevs of kind `veth` and accepts the following keys: `Name=` The interface name used when creating the netdev. This setting is compulsory. `MACAddress=` The peer MACAddress, if not set, it is generated in the same way as the MAC address of the main interface. # \[VXCAN\] Section Options The \[VXCAN\] section only applies for netdevs of kind `vxcan` and accepts the following key: `Peer=` The peer interface name used when creating the netdev. This setting is compulsory. # \[Tun\] Section Options The \[Tun\] section only applies for netdevs of kind `tun`, and accepts the following keys: `MultiQueue=` Takes a boolean. Configures whether to use multiple file descriptors (queues) to parallelize packets sending and receiving. Defaults to `no`. `PacketInfo=` Takes a boolean. Configures whether packets should be prepended with four extra bytes (two flag bytes and two protocol bytes). If disabled, it indicates that the packets will be pure IP packets. Defaults to `no`. `VNetHeader=` Takes a boolean. Configures IFF_VNET_HDR flag for a tun or tap device. It allows sending and receiving larger Generic Segmentation Offload (GSO) packets. This may increase throughput significantly. Defaults to `no`. `User=` User to grant access to the `/dev/net/tun` device. Note that the user must be resolvable during early boot. Using non-system users is deprecated. `Group=` Group to grant access to the `/dev/net/tun` device. Note that the group must be resolvable during early boot. Using non-system groups is deprecated. `KeepCarrier=` Takes a boolean. If enabled, to make the interface maintain its carrier status, the file descriptor of the interface is kept open. This may be useful to keep the interface in running state, for example while the backing process is temporarily shutdown. Defaults to `no`. # \[Tap\] Section Options The \[Tap\] section only applies for netdevs of kind `tap`, and accepts the same keys as the \[Tun\] section. # \[WireGuard\] Section Options The \[WireGuard\] section accepts the following keys: `PrivateKey=` The Base64 encoded private key for the interface. It can be generated using the `wg genkey` command (see `wg(8)`). Specially, if the specified key is prefixed with `@`, it is interpreted as the name of the credential from which the actual key shall be read. `systemd-networkd.service(8)` automatically imports credentials matching `network.wireguard.*`. For more details on credentials, refer to `systemd.exec(5)`. A private key is mandatory to use WireGuard. If not set, the credential `network.wireguard.private.netdev` is used if exists. I.e. for `50-foobar.netdev`, `network.wireguard.private.50-foobar` is tried. Note that because this information is secret, it is strongly recommended to use an (encrypted) credential. Alternatively, you may want to set the permissions of the .netdev file to be owned by `root:systemd-network` with a `0640` file mode. `PrivateKeyFile=` Takes an absolute path to a file which contains the Base64 encoded private key for the interface. When this option is specified, then `PrivateKey=` is ignored. Note that the file must be readable by the user `systemd-network`, so it should be, e.g., owned by `root:systemd-network` with a `0640` file mode. If the path refers to an `AF_UNIX` stream socket in the file system a connection is made to it and the key read from it. `ListenPort=` Sets UDP port for listening. Takes either value between 1 and 65535 or `auto`. If `auto` is specified, the port is automatically generated based on interface name. Defaults to `auto`. `FirewallMark=` Sets a firewall mark on outgoing WireGuard packets from this interface. Takes a number between 1 and 4294967295. `RouteTable=` The table identifier for the routes to the addresses specified in the `AllowedIPs=`. Takes a negative boolean value, one of the predefined names `default`, `main`, and `local`, names defined in `RouteTable=` in `networkd.conf(5)`, or a number in the range 1…4294967295. When `off` the routes to the addresses specified in the `AllowedIPs=` setting will not be configured. Defaults to false. This setting will be ignored when the same setting is specified in the \[WireGuardPeer\] section. `RouteMetric=` The priority of the routes to the addresses specified in the `AllowedIPs=`. Takes an integer in the range 0…4294967295. Defaults to 0 for IPv4 addresses, and 1024 for IPv6 addresses. This setting will be ignored when the same setting is specified in the \[WireGuardPeer\] section. # \[WireGuardPeer\] Section Options The \[WireGuardPeer\] section accepts the following keys: `PublicKey=` Sets a Base64 encoded public key calculated by `wg pubkey` (see `wg(8)`) from a private key, and usually transmitted out of band to the author of the configuration file. This option honors the `@` prefix in the same way as the `PrivateKey=` setting of the `[WireGuard]` section. This option is mandatory for this section. `PublicKeyFile=` Takes an absolute path to a file which contains the Base64 encoded public key for the peer. When this option is specified, then `PublicKey=` will be ignored. Note that the file must be readable by the user `systemd-network`, so it should be, e.g., owned by `root:systemd-network` with a `0640` file mode. If the path refers to an `AF_UNIX` stream socket in the file system a connection is made to it and the key read from it. `PresharedKey=` Optional preshared key for the interface. It can be generated by the `wg genpsk` command. This option adds an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. This option honors the `@` prefix in the same way as the `PrivateKey=` setting of the `[WireGuard]` section. Note that because this information is secret, it is strongly recommended to use an (encrypted) credential. Alternatively, you may want to set the permissions of the .netdev file to be owned by `root:systemd-network` with a `0640` file mode. `PresharedKeyFile=` Takes an absolute path to a file which contains the Base64 encoded preshared key for the peer. When this option is specified, then `PresharedKey=` is ignored. Note that the file must be readable by the user `systemd-network`, so it should be, e.g., owned by `root:systemd-network` with a `0640` file mode. If the path refers to an `AF_UNIX` stream socket in the file system a connection is made to it and the key read from it. `AllowedIPs=` Sets a comma-separated list of IP (v4 or v6) addresses with CIDR masks from which this peer is allowed to send incoming traffic and to which outgoing traffic for this peer is directed. This setting can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. The catch-all 0.0.0.0/0 may be specified for matching all IPv4 addresses, and ::/0 may be specified for matching all IPv6 addresses. Note that this only affects *routing inside the network interface itself*, i.e. the packets that pass through the tunnel itself. To cause packets to be sent via the tunnel in the first place, an appropriate route needs to be added as well — either in the `[Routes]` section on the `.network` matching the wireguard interface, or externally to `systemd-networkd`. `Endpoint=` Sets an endpoint IP address or hostname, followed by a colon, and then a port number. IPv6 address must be in the square brackets. For example, `111.222.333.444:51820` for IPv4 and `[1111:2222::3333]:51820` for IPv6 address. This endpoint will be updated automatically once to the most recent source IP address and port of correctly authenticated packets from the peer at configuration time. This option honors the `@` prefix in the same way as the `PrivateKey=` setting of the `[WireGuard]` section. `PersistentKeepalive=` Sets a seconds interval, between 1 and 65535 inclusive, of how often to send an authenticated empty packet to the peer for the purpose of keeping a stateful firewall or NAT mapping valid persistently. For example, if the interface very rarely sends traffic, but it might at anytime receive traffic from a peer, and it is behind NAT, the interface might benefit from having a persistent keepalive interval of 25 seconds. If set to 0 or "off", this option is disabled. By default or when unspecified, this option is off. Most users will not need this. `RouteTable=` The table identifier for the routes to the addresses specified in the `AllowedIPs=`. Takes a negative boolean value, one of the predefined names `default`, `main`, and `local`, names defined in `RouteTable=` in `networkd.conf(5)`, or a number in the range 1…4294967295. Defaults to unset, and the value specified in the same setting in the \[WireGuard\] section will be used. `RouteMetric=` The priority of the routes to the addresses specified in the `AllowedIPs=`. Takes an integer in the range 0…4294967295. Defaults to unset, and the value specified in the same setting in the \[WireGuard\] section will be used. # \[Bond\] Section Options The \[Bond\] section accepts the following key: `Mode=` Specifies one of the bonding policies. The default is `balance-rr` (round robin). Possible values are `balance-rr`, `active-backup`, `balance-xor`, `broadcast`, `802.3ad`, `balance-tlb`, and `balance-alb`. `TransmitHashPolicy=` Selects the transmit hash policy to use for slave selection in balance-xor, 802.3ad, and tlb modes. Possible values are `layer2`, `layer3+4`, `layer2+3`, `encap2+3`, and `encap3+4`. `LACPTransmitRate=` Specifies the rate with which link partner transmits Link Aggregation Control Protocol Data Unit packets in 802.3ad mode. Possible values are `slow`, which requests partner to transmit LACPDUs every 30 seconds, and `fast`, which requests partner to transmit LACPDUs every second. The default value is `slow`. `MIIMonitorSec=` Specifies the frequency that Media Independent Interface link monitoring will occur. A value of zero disables MII link monitoring. This value is rounded down to the nearest millisecond. The default value is 0. `PeerNotifyDelaySec=` Specifies the number of seconds the delay between each peer notification (gratuitous ARP and unsolicited IPv6 Neighbor Advertisement) when they are issued after a failover event. This delay should be a multiple of the MII link monitor interval (miimon). The valid range is 0...300s. The default value is 0, which means to match the value of the `MIIMonitorSec=`. `UpDelaySec=` Specifies the delay before a link is enabled after a link up status has been detected. This value is rounded down to a multiple of `MIIMonitorSec=`. The default value is 0. `DownDelaySec=` Specifies the delay before a link is disabled after a link down status has been detected. This value is rounded down to a multiple of `MIIMonitorSec=`. The default value is 0. `LearnPacketIntervalSec=` Specifies the number of seconds between instances where the bonding driver sends learning packets to each slave peer switch. The valid range is 1…0x7fffffff; the default value is 1. This option has an effect only for the balance-tlb and balance-alb modes. `AdSelect=` Specifies the 802.3ad aggregation selection logic to use. Possible values are `stable`, `bandwidth` and `count`. `AdActorSystemPriority=` Specifies the 802.3ad actor system priority. Takes a number in the range 1…65535. `AdUserPortKey=` Specifies the 802.3ad user defined portion of the port key. Takes a number in the range 0…1023. `AdActorSystem=` Specifies the 802.3ad system MAC address. This cannot be a null or multicast address. `FailOverMACPolicy=` Specifies whether the active-backup mode should set all slaves to the same MAC address at the time of enslavement or, when enabled, to perform special handling of the bond's MAC address in accordance with the selected policy. The default policy is none. Possible values are `none`, `active` and `follow`. `ARPValidate=` Specifies whether or not ARP probes and replies should be validated in any mode that supports ARP monitoring, or whether non-ARP traffic should be filtered (disregarded) for link monitoring purposes. Possible values are `none`, `active`, `backup` and `all`. `ARPIntervalSec=` Specifies the ARP link monitoring frequency. A value of 0 disables ARP monitoring. The default value is 0, and the default unit seconds. `ARPIPTargets=` Specifies the IP addresses to use as ARP monitoring peers when `ARPIntervalSec=` is greater than 0. These are the targets of the ARP request sent to determine the health of the link to the targets. Specify these values in IPv4 dotted decimal format. At least one IP address must be given for ARP monitoring to function. The maximum number of targets that can be specified is 16. The default value is no IP addresses. `ARPAllTargets=` Specifies the quantity of `ARPIPTargets=` that must be reachable in order for the ARP monitor to consider a slave as being up. This option affects only active-backup mode for slaves with ARPValidate enabled. Possible values are `any` and `all`. `PrimaryReselectPolicy=` Specifies the reselection policy for the primary slave. This affects how the primary slave is chosen to become the active slave when failure of the active slave or recovery of the primary slave occurs. This option is designed to prevent flip-flopping between the primary slave and other slaves. Possible values are `always`, `better` and `failure`. `ResendIGMP=` Specifies the number of IGMP membership reports to be issued after a failover event. One membership report is issued immediately after the failover, subsequent packets are sent in each 200ms interval. The valid range is 0…255. Defaults to 1. A value of 0 prevents the IGMP membership report from being issued in response to the failover event. `PacketsPerSlave=` Specify the number of packets to transmit through a slave before moving to the next one. When set to 0, then a slave is chosen at random. The valid range is 0…65535. Defaults to 1. This option only has effect when in balance-rr mode. `GratuitousARP=` Specify the number of peer notifications (gratuitous ARPs and unsolicited IPv6 Neighbor Advertisements) to be issued after a failover event. As soon as the link is up on the new slave, a peer notification is sent on the bonding device and each VLAN sub-device. This is repeated at each link monitor interval (ARPIntervalSec or MIIMonitorSec, whichever is active) if the number is greater than 1. The valid range is 0…255. The default value is 1. These options affect only the active-backup mode. `AllSlavesActive=` Takes a boolean. Specifies that duplicate frames (received on inactive ports) should be dropped when false, or delivered when true. Normally, bonding will drop duplicate frames (received on inactive ports), which is desirable for most users. But there are some cases where it is nice to allow duplicate frames to be delivered. The default value is false (drop duplicate frames received on inactive ports). `DynamicTransmitLoadBalancing=` Takes a boolean. Specifies if dynamic shuffling of flows is enabled. Applies only for balance-tlb mode. Defaults to unset. `MinLinks=` Specifies the minimum number of links that must be active before asserting carrier. The default value is 0. `ARPMissedMax=` Specify the maximum number of arp interval monitor cycle for missed ARP replies. If this number is exceeded, link is reported as down. Defaults to unset. For more detail information see [ Linux Ethernet Bonding Driver HOWTO](https://docs.kernel.org/networking/bonding.html) # \[Xfrm\] Section Options The \[Xfrm\] section accepts the following keys: `InterfaceId=` Sets the ID/key of the xfrm interface which needs to be associated with a SA/policy. Can be decimal or hexadecimal, valid range is 1-0xffffffff. This is mandatory. `Independent=` Takes a boolean. If false (the default), the xfrm interface must have an underlying device which can be used for hardware offloading. For more detail information see [Virtual XFRM Interfaces](https://lwn.net/Articles/757391). # \[VRF\] Section Options The \[VRF\] section only applies for netdevs of kind `vrf` and accepts the following key: `Table=` The routing table identifier. Takes a route table name or number. Route table names may be predefined or configured with `RouteTable=` in `networkd.conf(5)`. This setting is compulsory. # \[BatmanAdvanced\] Section Options The \[BatmanAdvanced\] section only applies for netdevs of kind `batadv` and accepts the following keys: `GatewayMode=` Takes one of `off`, `server`, or `client`. A batman-adv node can either run in server mode (sharing its internet connection with the mesh) or in client mode (searching for the most suitable internet connection in the mesh) or having the gateway support turned off entirely (which is the default setting). `Aggregation=` Takes a boolean value. Enables or disables aggregation of originator messages. Defaults to true. `BridgeLoopAvoidance=` Takes a boolean value. Enables or disables avoidance of loops on bridges. Defaults to true. `DistributedArpTable=` Takes a boolean value. Enables or disables the distributed ARP table. Defaults to true. `Fragmentation=` Takes a boolean value. Enables or disables fragmentation. Defaults to true. `HopPenalty=` The hop penalty setting allows one to modify `batctl(8)` preference for multihop routes vs. short routes. This integer value is applied to the TQ (Transmit Quality) of each forwarded OGM (Originator Message), thereby propagating the cost of an extra hop (the packet has to be received and retransmitted which costs airtime). A higher hop penalty will make it more unlikely that other nodes will choose this node as intermediate hop towards any given destination. The default hop penalty of '15' is a reasonable value for most setups and probably does not need to be changed. However, mobile nodes could choose a value of 255 (maximum value) to avoid being chosen as a router by other nodes. The minimum value is 0. `OriginatorIntervalSec=` The value specifies the interval in seconds, unless another time unit is specified in which batman-adv floods the network with its protocol information. See `systemd.time(7)` for more information. `GatewayBandwidthDown=` If the node is a server, this parameter is used to inform other nodes in the network about this node's internet connection download bandwidth in bits per second. Just enter any number suffixed with K, M, G or T (base 1000) and the batman-adv module will propagate the entered value in the mesh. `GatewayBandwidthUp=` If the node is a server, this parameter is used to inform other nodes in the network about this node's internet connection upload bandwidth in bits per second. Just enter any number suffixed with K, M, G or T (base 1000) and the batman-adv module will propagate the entered value in the mesh. `RoutingAlgorithm=` This can be either `batman-v` or `batman-iv` and describes which routing_algo of `batctl(8)` to use. The algorithm cannot be changed after interface creation. Defaults to `batman-v`. # \[IPoIB\] Section Options The \[IPoIB\] section only applies for netdevs of kind `ipoib` and accepts the following keys: `PartitionKey=` Takes an integer in the range 1…0xffff, except for 0x8000. Defaults to unset, and the kernel's default is used. `Mode=` Takes one of the special values `datagram` or `connected`. Defaults to unset, and the kernel's default is used. When `datagram`, the Infiniband unreliable datagram (UD) transport is used, and so the interface MTU is equal to the IB L2 MTU minus the IPoIB encapsulation header (4 bytes). For example, in a typical IB fabric with a 2K MTU, the IPoIB MTU will be 2048 - 4 = 2044 bytes. When `connected`, the Infiniband reliable connected (RC) transport is used. Connected mode takes advantage of the connected nature of the IB transport and allows an MTU up to the maximal IP packet size of 64K, which reduces the number of IP packets needed for handling large UDP datagrams, TCP segments, etc and increases the performance for large messages. `IgnoreUserspaceMulticastGroups=` Takes a boolean value. When true, the kernel ignores multicast groups handled by userspace. Defaults to unset, and the kernel's default is used. # \[WLAN\] Section Options The \[WLAN\] section only applies to WLAN interfaces, and accepts the following keys: `PhysicalDevice=` Specifies the name or index of the physical WLAN device (e.g. `0` or `phy0`). The list of the physical WLAN devices that exist on the host can be obtained by `iw phy` command. This option is mandatory. `Type=` Specifies the type of the interface. Takes one of the `ad-hoc`, `station`, `ap`, `ap-vlan`, `wds`, `monitor`, `mesh-point`, `p2p-client`, `p2p-go`, `p2p-device`, `ocb`, `nan`, `nan-data` and `pd`. This option is mandatory. `WDS=` Enables the Wireless Distribution System (WDS) mode on the interface. The mode is also known as the `4 address mode`. Takes a boolean value. Defaults to unset, and the kernel's default will be used. # Examples
/etc/systemd/network/25-bridge.netdev
[NetDev] Name=bridge0 Kind=bridge
/etc/systemd/network/25-vlan1.netdev
[Match] Virtualization=no [NetDev] Name=vlan1 Kind=vlan [VLAN] Id=1
/etc/systemd/network/25-ipip.netdev
[NetDev] Name=ipip-tun Kind=ipip MTUBytes=1480 [Tunnel] Local=192.168.223.238 Remote=192.169.224.239 TTL=64
/etc/systemd/network/1-fou-tunnel.netdev
[NetDev] Name=fou-tun Kind=fou [FooOverUDP] Port=5555 Protocol=4
/etc/systemd/network/25-fou-ipip.netdev
[NetDev] Name=ipip-tun Kind=ipip [Tunnel] Independent=yes Local=10.65.208.212 Remote=10.65.208.211 FooOverUDP=yes FOUDestinationPort=5555
/etc/systemd/network/25-tap.netdev
[NetDev] Name=tap-test Kind=tap [Tap] MultiQueue=yes PacketInfo=yes
/etc/systemd/network/25-sit.netdev
[NetDev] Name=sit-tun Kind=sit MTUBytes=1480 [Tunnel] Local=10.65.223.238 Remote=10.65.223.239
/etc/systemd/network/25-6rd.netdev
[NetDev] Name=6rd-tun Kind=sit MTUBytes=1480 [Tunnel] Local=10.65.223.238 IPv6RapidDeploymentPrefix=2602::/24
/etc/systemd/network/25-gre.netdev
[NetDev] Name=gre-tun Kind=gre MTUBytes=1480 [Tunnel] Local=10.65.223.238 Remote=10.65.223.239
/etc/systemd/network/25-ip6gre.netdev
[NetDev] Name=ip6gre-tun Kind=ip6gre [Tunnel] Key=123
/etc/systemd/network/25-vti.netdev
[NetDev] Name=vti-tun Kind=vti MTUBytes=1480 [Tunnel] Local=10.65.223.238 Remote=10.65.223.239
/etc/systemd/network/25-veth.netdev
[NetDev] Name=veth-test Kind=veth [Peer] Name=veth-peer
/etc/systemd/network/25-bond.netdev
[NetDev] Name=bond1 Kind=bond [Bond] Mode=802.3ad TransmitHashPolicy=layer3+4 MIIMonitorSec=1s LACPTransmitRate=fast
/etc/systemd/network/25-dummy.netdev
[NetDev] Name=dummy-test Kind=dummy MACAddress=12:34:56:78:9a:bc
/etc/systemd/network/25-vrf.netdev
Create a VRF interface with table 42. [NetDev] Name=vrf-test Kind=vrf [VRF] Table=42
/etc/systemd/network/25-macvtap.netdev
Create a MacVTap device. [NetDev] Name=macvtap-test Kind=macvtap
/etc/systemd/network/25-wireguard.netdev
[NetDev] Name=wg0 Kind=wireguard [WireGuard] PrivateKey=EEGlnEPYJV//kbvvIqxKkQwOiS+UENyPncC4bF46ong= ListenPort=51820 [WireGuardPeer] PublicKey=RDf+LSpeEre7YEIKaxg+wbpsNV7du+ktR99uBEtIiCA= AllowedIPs=fd31:bf08:57cb::/48,192.168.26.0/24 Endpoint=wireguard.example.com:51820
/etc/systemd/network/27-xfrm.netdev
[NetDev] Name=xfrm0 Kind=xfrm [Xfrm] Independent=yes
# See Also `systemd(1)`, `systemd-networkd.service(8)`, `systemd.link(5)`, `systemd.network(5)`, `systemd-network-generator.service(8)` # systemd.network systemd systemd.network 5 systemd.network Network configuration `network.network` # Description A plain ini-style text file that encodes network configuration for matching network interfaces, used by `systemd-networkd(8)`. See `systemd.syntax(7)` for a general description of the syntax. The main network file must have the extension `.network`; other extensions are ignored. Networks are applied to links whenever the links appear. Note that not all settings and configurations can be made with `.network` files, and that it may be necessary to use `systemd.link(5)`) or `systemd.netdev(5)`) files in conjunction with `.network` files when working with physical and virtual network devices respectively. The `.network` files are read from the files located in the system network directories `/usr/lib/systemd/network` and `/usr/local/lib/systemd/network` , the volatile runtime network directory `/run/systemd/network` and the local administration network directory `/etc/systemd/network`. All configuration files are collectively sorted and processed in alphanumeric order, regardless of the directories in which they live. However, files with identical filenames replace each other. It is recommended that each filename is prefixed with a number smaller than `70` (e.g. `10-eth0.network`). Otherwise, the default `.network` files or those generated by `systemd-network-generator.service(8)` may take precedence over user configured files. Files in `/etc/` have the highest priority, files in `/run/` take precedence over files with the same name under `/usr/`. This can be used to override a system-supplied configuration file with a local file if needed. As a special case, an empty file (file size 0) or symlink with the same name pointing to `/dev/null` disables the configuration file entirely (it is "masked"). Along with the network file `foo.network`, a "drop-in" directory `foo.network.d/` may exist. All files with the suffix `.conf` from this directory will be merged in the alphanumeric order and parsed after the main file itself has been parsed. This is useful to alter or add configuration settings, without having to modify the main configuration file. Each drop-in file must have appropriate section headers. In addition to `/etc/systemd/network`, drop-in `.d` directories can be placed in `/usr/lib/systemd/network` or `/run/systemd/network` directories. Drop-in files in `/etc/` take precedence over those in `/run/` which in turn take precedence over those in `/usr/lib/`. Drop-in files under any of these directories take precedence over the main network file wherever located. # \[Match\] Section Options The network file contains a \[Match\] section, which determines if a given network file may be applied to a given interface; and a \[Network\] section specifying how the interface should be configured. The first (in alphanumeric order) of the network files that matches a given interface is applied, all later files are ignored, even if they match as well. Note that any network interfaces that have the `ID_NET_MANAGED_BY=` udev property set will never be matched by any .network files – unless the property's value is the string `io.systemd.Network` – even if the \[Match\] section would otherwise match. This may be used to exclude specific network interfaces from `systemd-networkd(8)`'s management, while keeping the \[Match\] section generic. The `ID_NET_MANAGED_BY=` property thus declares intended *ownership* of the device, and permits ensuring that concurrent network management implementations do not compete for management of specific devices. A network file is said to match a network interface if all matches specified by the \[Match\] section are satisfied. When a network file does not contain valid settings in \[Match\] section, then the file will match all interfaces and `systemd-networkd` warns about that. Hint: to avoid the warning and to make it clear that all interfaces shall be matched, add the following: Name=* The following keys are accepted: `Name=` A whitespace-separated list of shell-style globs matching the device name, as exposed by the udev property `INTERFACE`, or device's alternative names. If the list is prefixed with a "!", the test is inverted. `WLANInterfaceType=` A whitespace-separated list of wireless network type. Supported values are `ad-hoc`, `station`, `ap`, `ap-vlan`, `wds`, `monitor`, `mesh-point`, `p2p-client`, `p2p-go`, `p2p-device`, `ocb`, and `nan`. If the list is prefixed with a "!", the test is inverted. `SSID=` A whitespace-separated list of shell-style globs matching the SSID of the currently connected wireless LAN. If the list is prefixed with a "!", the test is inverted. `BSSID=` A whitespace-separated list of hardware address of the currently connected wireless LAN. Use full colon-, hyphen- or dot-delimited hexadecimal. See the example in `MACAddress=`. This option may appear more than once, in which case the lists are merged. If the empty string is assigned to this option, the list is reset. # \[Link\] Section Options The \[Link\] section accepts the following keys: `MACAddress=` The hardware address to set for the device. `MTUBytes=` The maximum transmission unit in bytes to set for the device. The usual suffixes K, M, G, are supported and are understood to the base of 1024. Note that if IPv6 is enabled on the interface, and the MTU is chosen below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value. `ARP=` Takes a boolean. If set to true, the IPv4 ARP (low-level Address Resolution Protocol) and IPv6 NDP (Neighbor Discovery Protocol) for this interface are enabled. For example, disabling ARP is useful when creating multiple MACVLAN or VLAN virtual interfaces atop a single lower-level physical interface, which will then only serve as a link/"bridge" device aggregating traffic to the same physical link and not participate in the network otherwise. Defaults to unset, and enabled when the IPv4 link-local addressing is enabled in `LinkLocalAddressing=` or an IPv4 address with `DuplicateAddressDetection=` enabled is requested. Otherwise, the kernel's default will be used. `Multicast=` Takes a boolean. If set to true, the multicast flag on the device is enabled. Defaults to unset and the flag is unchanged. When disabled, `IPv6AcceptRA=` and `IPv6SendRA=` cannot be enabled. `AllMulticast=` Takes a boolean. If set to true, the driver retrieves all multicast packets from the network. This happens when multicast routing is enabled. Defaults to unset. `Promiscuous=` Takes a boolean. If set to true, promiscuous mode of the interface is enabled. Defaults to unset. If this is set to false for the underlying link of a `passthru` mode MACVLAN/MACVTAP, the virtual interface will be created with the `nopromisc` flag set. `Unmanaged=` Takes a boolean. When `yes`, no attempts are made to bring up or configure matching links, equivalent to when there are no matching network files. Defaults to `no`. This is useful for preventing later matching network files from interfering with certain interfaces that are fully controlled by other applications. `Group=` Link groups are similar to port ranges found in managed switches. When network interfaces are added to a numbered group, operations on all the interfaces from that group can be performed at once. Takes an unsigned integer in the range 0…2147483647. Defaults to unset. `RequiredForOnline=` Takes a boolean, a minimum operational state (e.g., `carrier`), or a range of operational state separated with a colon (e.g., `degraded:routable`). Please see `networkctl(1)` for possible operational states. When `yes`, the network is deemed required when determining whether the system is online (including when running `systemd-networkd-wait-online`). When `no`, the network is ignored when determining the online state. When a minimum operational state and an optional maximum operational state are set, `systemd-networkd-wait-online` deems that the interface is online when the operational state is in the specified range. Defaults to `yes` when `ActivationPolicy=` is not set, or set to `up`, `always-up`, or `bound`. Defaults to `no` when `ActivationPolicy=` is set to `manual` or `down`. This is forced to `no` when `ActivationPolicy=` is set to `always-down`. The network will be brought up normally (as configured by `ActivationPolicy=`), but in the event that there is no address being assigned by DHCP or the cable is not plugged in, the link will simply remain offline and be skipped automatically by `systemd-networkd-wait-online` if `RequiredForOnline=no`. The boolean value `yes` is translated as follows; `CAN devices` `carrier`, `Master devices, e.g. bond or bridge` `degraded-carrier` with `RequiredFamilyForOnline=any`, `Bonding port interfaces` `enslaved`, `Other interfaces` `degraded`. This setting can be overridden by the command line option for `systemd-networkd-wait-online`. See `systemd-networkd-wait-online.service(8)` for more details. `RequiredFamilyForOnline=` Takes an address family. When specified, an IP address in the given family is deemed required when determining whether the link is online (including when running `systemd-networkd-wait-online`). Takes one of `ipv4`, `ipv6`, `both`, or `any`. Defaults to `any`. Note that this option has no effect if `RequiredForOnline=no`. `ActivationPolicy=` Specifies the policy for `systemd-networkd` managing the link administrative state. Specifically, this controls how `systemd-networkd` changes the network device's `IFF_UP` flag, which is sometimes controlled by system administrators by running e.g., `ip link set dev eth0 up` or `ip link set dev eth0 down`, and can also be changed with `networkctl up eth0` or `networkctl down eth0`. Takes one of `up`, `always-up`, `manual`, `always-down`, `down`, or `bound`. When `manual`, `systemd-networkd` will not change the link's admin state automatically; the system administrator must bring the interface up or down manually, as desired. When `up` (the default) or `always-up`, or `down` or `always-down`, `systemd-networkd` will set the link up or down, respectively, when the interface is (re)configured. When `always-up` or `always-down`, `systemd-networkd` will set the link up or down, respectively, any time `systemd-networkd` detects a change in the administrative state. When `BindCarrier=` is also set, this is automatically set to `bound` and any other value is ignored. When the policy is set to `down` or `manual`, the default value of `RequiredForOnline=` is `no`. When the policy is set to `always-down`, the value of `RequiredForOnline=` forced to `no`. The administrative state is not the same as the carrier state, so using `always-up` does not mean the link will never lose carrier. The link carrier depends on both the administrative state as well as the network device's physical connection. However, to avoid reconfiguration failures, when using `always-up`, `IgnoreCarrierLoss=` is forced to true. # \[Network\] Section Options The \[Network\] section accepts the following keys: `Description=` A description of the device. This is only used for presentation purposes. `DHCP=` Enables DHCPv4 and/or DHCPv6 client support. Accepts `yes`, `no`, `ipv4`, or `ipv6`. Defaults to `no`. Note that DHCPv6 will by default be triggered by Router Advertisements, if reception is enabled, regardless of this parameter. By explicitly enabling DHCPv6 support here, the DHCPv6 client will be started in the mode specified by the `WithoutRA=` setting in the \[DHCPv6\] section, regardless of the presence of routers on the link, or what flags the routers pass. See `IPv6AcceptRA=`. Furthermore, note that by default the domain name specified through DHCP is not used for name resolution. See option `UseDomains=` below. See the \[DHCPv4\] or \[DHCPv6\] sections below for further configuration options for the DHCP client support. `DHCPRelay=` Takes one of `upstream` or `downstream`. When specified, the host acts as a DHCP relay agent. When set to `upstream`, the interface behaves as an upstream interface of the DHCP relay agent. When set to `downstream`, the interface behaves as a downstream interface of the DHCP relay agent. To make the DHCP relay agent work, at least one upstream interface and one downstream interface must be configured on the host. This requires `ServerAddress=` in the \[DHCPRelay\] section to be configured in `networkd.conf`. If `ServerAddress=` is not configured, this setting is ignored. See `networkd.conf(5)` for more details about `ServerAddress=` and other host-wide settings. Also, further per-interface settings can be configured in the \[DHCPRelay\] section described below. Defaults to unset, and the interface is not used for DHCP relay forwarding. `DHCPServer=` Takes a boolean. If set to `yes`, DHCPv4 server will be started. Defaults to `no`. Further settings for the DHCP server may be set in the \[DHCPServer\] section described below. Even if this is enabled, the DHCP server will not be started automatically and wait for the persistent storage being ready to load/save leases in the storage, unless `PersistLeases=no/runtime` is specified in the \[DHCPServer\] section. It will be started after `systemd-networkd-persistent-storage.service` is started, which calls `networkctl persistent-storage yes`. See `networkctl(1)` for more details. `LinkLocalAddressing=` Enables link-local address autoconfiguration. Accepts a boolean, `ipv4`, and `ipv6`. An IPv6 link-local address is configured when `yes` or `ipv6`. An IPv4 link-local address is configured when `yes` or `ipv4` and when DHCPv4 autoconfiguration has been unsuccessful for some time. (IPv4 link-local address autoconfiguration will usually happen in parallel with repeated attempts to acquire a DHCPv4 lease). Defaults to `no` when `KeepMaster=` or `Bridge=` is set or when the specified `MACVLAN=`/`MACVTAP=` has `Mode=passthru`, or `ipv6` otherwise. As WireGuard interfaces do not have a hardware address, the kernel generates the IPv6 link-local address on them in the same way as the `random` mode even when `eui64` is used, see `IPv6LinkLocalAddressGenerationMode=` below. When IPv4 link-local addressing is enabled, `ARP=` is enabled unless if it is explicitly configured. `IPv6LinkLocalAddressGenerationMode=` Specifies how IPv6 link-local address is generated. Takes one of `eui64`, `none`, `stable-privacy` and `random`. When unset, `stable-privacy` is used if `IPv6StableSecretAddress=` is specified, and if not, `eui64` is used. Note that if `LinkLocalAddressing=` is `no` or `ipv4`, then `IPv6LinkLocalAddressGenerationMode=` will be ignored. Also, even if `LinkLocalAddressing=` is `yes` or `ipv6`, setting `IPv6LinkLocalAddressGenerationMode=none` disables to configure an IPv6 link-local address. `IPv6StableSecretAddress=` Takes an IPv6 address. The specified address will be used as a stable secret for generating IPv6 link-local address. If this setting is specified, and `IPv6LinkLocalAddressGenerationMode=` is unset, then `IPv6LinkLocalAddressGenerationMode=stable-privacy` is implied. If this setting is not specified, and `stable-privacy` is set to `IPv6LinkLocalAddressGenerationMode=`, then a stable secret address will be generated from the local machine ID and the interface name. `IPv4LLStartAddress=` Specifies the first IPv4 link-local address to try. Takes an IPv4 address for example 169.254.1.2, from the link-local address range: 169.254.0.0/16 except for 169.254.0.0/24 and 169.254.255.0/24. This setting may be useful if the device should always have the same address as long as there is no address conflict. When unset, a random address will be automatically selected. Defaults to unset. `IPv4LLRoute=` Takes a boolean. If set to true, sets up the route needed for non-IPv4LL hosts to communicate with IPv4LL-only hosts. Defaults to false. `DefaultRouteOnDevice=` Takes a boolean. If set to true, sets up the IPv4 default route bound to the interface. Defaults to false. This is useful when creating routes on point-to-point interfaces. This is equivalent to e.g. the following, ip route add default dev veth99 or, [Route] Gateway=0.0.0.0 Currently, there are no way to specify e.g., the table for the route configured by this setting. To configure the default route with such an additional property, please use the following instead: [Route] Gateway=0.0.0.0 Table=1234 If you'd like to create an IPv6 default route bound to the interface, please use the following: [Route] Gateway=:: Table=1234 `LLMNR=` Takes a boolean or `resolve`. When true, enables [Link-Local Multicast Name Resolution](https://tools.ietf.org/html/rfc4795) on the link. When set to `resolve`, only resolution is enabled, but not host registration and announcement. Defaults to true. This setting is read by `systemd-resolved.service(8)`. `MulticastDNS=` Takes a boolean or `resolve`. When true, enables [Multicast DNS](https://tools.ietf.org/html/rfc6762) support on the link. When set to `resolve`, only resolution is enabled, but not host or service registration and announcement. Defaults to false. This setting is read by `systemd-resolved.service(8)`. `DNSOverTLS=` Takes a boolean or `opportunistic`. When true, enables [DNS-over-TLS](https://tools.ietf.org/html/rfc7858) support on the link. When set to `opportunistic`, compatibility with non-DNS-over-TLS servers is increased, by automatically turning off DNS-over-TLS servers in this case. This option defines a per-interface setting for `resolved.conf(5)`'s global `DNSOverTLS=` option. Defaults to unset, and the global setting will be used. This setting is read by `systemd-resolved.service(8)`. `DNSSEC=` Takes a boolean or `allow-downgrade`. When true, enables [DNSSEC](https://tools.ietf.org/html/rfc4033) DNS validation support on the link. When set to `allow-downgrade`, compatibility with non-DNSSEC capable networks is increased, by automatically turning off DNSSEC in this case. This option defines a per-interface setting for `resolved.conf(5)`'s global `DNSSEC=` option. Defaults to unset, and the global setting will be used. This setting is read by `systemd-resolved.service(8)`. `DNSSECNegativeTrustAnchors=` A space-separated list of DNSSEC negative trust anchor domains. If specified and DNSSEC is enabled, look-ups done via the interface's DNS server will be subject to the list of negative trust anchors, and not require authentication for the specified domains, or anything below it. Use this to disable DNSSEC authentication for specific private domains, that cannot be proven valid using the Internet DNS hierarchy. Defaults to the empty list. This setting is read by `systemd-resolved.service(8)`. `LLDP=` Controls support for Ethernet LLDP packet reception. LLDP is a link-layer protocol commonly implemented on professional routers and bridges which announces which physical port a system is connected to, as well as other related data. Accepts a boolean or the special value `routers-only`. When true, incoming LLDP packets are accepted and a database of all LLDP neighbors maintained. If `routers-only` is set only LLDP data of various types of routers is collected and LLDP data about other types of devices ignored (such as stations, telephones and others). If false, LLDP reception is disabled. Defaults to `routers-only`. Use `networkctl(1)` to query the collected neighbor data. LLDP is only available on Ethernet links. See `EmitLLDP=` below for enabling LLDP packet emission from the local system. `EmitLLDP=` Controls support for Ethernet LLDP packet emission. Accepts a boolean parameter or the special values `nearest-bridge`, `non-tpmr-bridge` and `customer-bridge`. Defaults to false, which turns off LLDP packet emission. If not false, a short LLDP packet with information about the local system is sent out in regular intervals on the link. The LLDP packet will contain information about the local hostname, the local machine ID (as stored in `machine-id(5)`) and the local interface name, as well as the pretty hostname of the system (as set in `machine-info(5)`). LLDP emission is only available on Ethernet links. Note that this setting passes data suitable for identification of host to the network and should thus not be enabled on untrusted networks, where such identification data should not be made available. Use this option to permit other systems to identify on which interfaces they are connected to this system. The three special values control propagation of the LLDP packets. The `nearest-bridge` setting permits propagation only to the nearest connected bridge, `non-tpmr-bridge` permits propagation across Two-Port MAC Relays, but not any other bridges, and `customer-bridge` permits propagation until a customer bridge is reached. For details about these concepts, see [IEEE 802.1AB-2016](https://standards.ieee.org/findstds/standard/802.1AB-2016.html). Note that configuring this setting to true is equivalent to `nearest-bridge`, the recommended and most restricted level of propagation. See `LLDP=` above for an option to enable LLDP reception. `BindCarrier=` A link name or a list of link names. When set, controls the behavior of the current link. When all links in the list are in an operational down state, the current link is brought down. When at least one link has carrier, the current interface is brought up. This forces `ActivationPolicy=` to be set to `bound`. `Address=` A static IPv4 or IPv6 address and its prefix length, separated by a `/` character. Specify this key more than once to configure several addresses. The format of the address must be as described in `inet_pton(3)`. This is a short-hand for an \[Address\] section only containing an Address key (see below). This option may be specified more than once. If the specified address is `0.0.0.0` (for IPv4) or `::` (for IPv6), a new address range of the requested size is automatically allocated from a system-wide pool of unused ranges. Note that the prefix length must be equal or larger than 8 for IPv4, and 64 for IPv6. The allocated range is checked against all current network interfaces and all known network configuration files to avoid address range conflicts. The default system-wide pool consists of 192.168.0.0/16, 172.16.0.0/12 and 10.0.0.0/8 for IPv4, and fd00::/8 for IPv6. This functionality is useful to manage a large number of dynamically created network interfaces with the same network configuration and automatic address range assignment. If an IPv4 link-local address (169.254.0.0/16) is specified, IPv4 Address Conflict Detection ([RFC 5227](https://tools.ietf.org/html/rfc5227)) is enabled for the address. To assign an IPv4 link-local address without IPv4 Address Conflict Detection, please use \[Address\] section to configure the address and disable `DuplicateAddressDetection=`. [Address] Address=169.254.10.1/24 DuplicateAddressDetection=none If an empty string is specified, then the all previous assignments in both \[Network\] and \[Address\] sections are cleared. `Gateway=` The gateway address, which must be in the format described in `inet_pton(3)`. This is a short-hand for a \[Route\] section only containing a `Gateway=` key. This option may be specified more than once. If an empty string is specified, then the all previous assignments in both \[Network\] and \[Route\] sections are cleared. `DNS=` A DNS server address, which must be in the format described in `inet_pton(3)`. This option may be specified more than once. Each address can optionally take a port number separated with `:`, a network interface name or index separated with `%`, and a Server Name Indication (SNI) separated with `#`. When IPv6 address is specified with a port number, then the address must be in the square brackets. That is, the acceptable full formats are `111.222.333.444:9953%ifname#example.com` for IPv4 and `[1111:2222::3333]:9953%ifname#example.com` for IPv6. If an empty string is assigned, then the all previous assignments are cleared. This setting is read by `systemd-resolved.service(8)`. `UseDomains=` Specifies the protocol-independent default value for the same settings in \[IPv6AcceptRA\], \[DHCPv4\], and \[DHCPv6\] sections below. Takes a boolean, or the special value `route`. See also the same setting in \[DHCPv4\] below. Defaults to unset. `Domains=` A whitespace-separated list of domains which should be resolved using the DNS servers on this link. Each item in the list should be a domain name, optionally prefixed with a tilde (`~`). The domains with the prefix are called "routing-only domains". The domains without the prefix are called "search domains" and are first used as search suffixes for extending single-label hostnames (hostnames containing no dots) to become fully qualified domain names (FQDNs). If a single-label hostname is resolved on this interface, each of the specified search domains are appended to it in turn, converting it into a fully qualified domain name, until one of them may be successfully resolved. Both "search" and "routing-only" domains are used for routing of DNS queries: look-ups for hostnames ending in those domains (hence also single label names, if any "search domains" are listed), are routed to the DNS servers configured for this interface. The domain routing logic is particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each interface. The "routing-only" domain `~.` (the tilde indicating definition of a routing domain, the dot referring to the DNS root domain which is the implied suffix of all valid DNS names) has special effect. It causes all DNS traffic which does not match another configured domain routing entry to be routed to DNS servers specified for this interface. This setting is useful to prefer a certain set of DNS servers if a link on which they are connected is available. This setting is read by `systemd-resolved.service(8)`. "Search domains" correspond to the `domain` and `search` entries in `resolv.conf(5)`. Domain name routing has no equivalent in the traditional glibc API, which has no concept of domain name servers limited to a specific link. This option may be specified more than once. If an empty string is assigned, then the all previous assignments are cleared. `DNSDefaultRoute=` Takes a boolean argument. If true, this link's configured DNS servers are used for resolving domain names that do not match any link's configured `Domains=` setting. If false, this link's configured DNS servers are never used for such domains, and are exclusively used for resolving names that match at least one of the domains configured on this link. If not specified, defaults to an automatic mode: queries not matching any link's configured domains will be routed to this link if it has no routing-only domains configured. `NTP=` An NTP server address (either an IP address, or a hostname). This option may be specified more than once. This setting is read by `systemd-timesyncd.service(8)`. `IPv4Forwarding=` Configures IPv4 packet forwarding for the interface. Takes a boolean value. This controls the `net.ipv4.conf.INTERFACE.forwarding` sysctl option of the network interface. See [IP Sysctl](https://docs.kernel.org/networking/ip-sysctl.html) for more details about the sysctl option. Defaults to true if `IPMasquerade=` is enabled for IPv4, otherwise the value specified to the same setting in `networkd.conf(5)` will be used. If none of them are specified, the sysctl option will not be changed. To control the global setting, use the same setting in `networkd.conf(5)`. `IPv6Forwarding=` Configures interface-specific host/router behaviour. Takes a boolean value. This controls the `net.ipv6.conf.INTERFACE.forwarding` sysctl option of the network interface. See [IP Sysctl](https://docs.kernel.org/networking/ip-sysctl.html) for more details about the sysctl option. Defaults to true if `IPMasquerade=` is enabled for IPv6 or `IPv6SendRA=` is enabled, otherwise the value specified to the same setting in `networkd.conf(5)` will be used. If none of them are specified, the sysctl option will not be changed. To control the global setting, use the same setting in `networkd.conf(5)`. Note, unlike `IPv4Forwarding=`, enabling per-interface `IPv6Forwarding=` on two or more interfaces *DOES NOT* make IPv6 packets forwarded within the interfaces. This setting just controls the per-interface sysctl value, and the sysctl value is not directly correlated to whether packets are forwarded. To ensure IPv6 packets forwarded, the global setting in `networkd.conf(5)` needs to be enabled. `IPMasquerade=` Configures IP masquerading for the network interface. If enabled, packets forwarded from the network interface will appear as coming from the local host. Typically, this should be enabled on the downstream interface of routers. Takes one of `ipv4`, `ipv6`, `both`, or `no`. Defaults to `no`. Note that any positive boolean values such as `yes` or `true` are now deprecated. Please use one of the values above. Specifying `ipv4` or `both` implies `IPv4Forwarding=` settings in both .network file for this interface and the global `networkd.conf(5)` unless they are explicitly specified. Similarly for `IPv6Forwarding=` when `ipv6` or `both` is specified. See `IPv4Forwarding=`/`IPv6Forwarding=` in the above for the per-link settings, and `networkd.conf(5)` for the global settings. `IPv6PrivacyExtensions=` Configures use of stateless temporary addresses that change over time (see [RFC 4941](https://tools.ietf.org/html/rfc4941), Privacy Extensions for Stateless Address Autoconfiguration in IPv6). Takes a boolean or the special values `prefer-public` and `kernel`. When true, enables the privacy extensions and prefers temporary addresses over public addresses. When `prefer-public`, enables the privacy extensions, but prefers public addresses over temporary addresses. When false, the privacy extensions remain disabled. When `kernel`, the kernel's default setting will be left in place. When unspecified, the value specified in the same setting in `networkd.conf(5)`, which defaults to `no`, will be used. `IPv6AcceptRA=` Takes a boolean. Controls IPv6 Router Advertisement (RA) reception support for the interface. If true, RAs are accepted; if false, RAs are ignored. When RAs are accepted, they may trigger the start of the DHCPv6 client if the relevant flags are set in the RA data, or if no routers are found on the link. This cannot be enabled on devices aggregated in a bond device, or when IPv6 link-local addressing (see `LinkLocalAddressing=`) or multicasting (see `Multicast=`) is disabled. Note, multicasting is disabled by default for some configurations, e.g. bridge ports. Hence, in that case `Multicast=` needs to be explicitly enabled to make this feature usable. When `IPv6SendRA=`, `IPv6Forwarding=`, or `IPMasquerade=` is enabled, this feature is disabled by default, but can be overridden by explicitly enabling this setting. Note, `IPv6Forwarding=` may be indirectly enabled when the global setting with the same name is enabled, or when `IPMasquerade=` is enabled on *any other interfaces*. See also `IPv6Forwarding=` and `IPMasquerade=` for more details. Enabled by default otherwise. Further settings for the IPv6 RA support may be configured in the \[IPv6AcceptRA\] section, see below. Also see [IP Sysctl](https://docs.kernel.org/networking/ip-sysctl.html) in the kernel documentation regarding `accept_ra`, but note that systemd's setting of `1` (i.e. true) corresponds to kernel's setting of `2`. Note that kernel's implementation of the IPv6 RA protocol is always disabled, regardless of this setting. If this option is enabled, a userspace implementation of the IPv6 RA protocol is used, and the kernel's own implementation remains disabled, since `systemd-networkd` needs to know all details supplied in the advertisements, and these are not available from the kernel if the kernel's own implementation is used. `IPv6DuplicateAddressDetection=` Configures the amount of IPv6 Duplicate Address Detection (DAD) probes to send. When unset, the kernel's default will be used. `IPv6HopLimit=` Configures IPv6 Hop Limit. Takes an integer in the range 1…255. For each router that forwards the packet, the hop limit is decremented by 1. When the hop limit field reaches zero, the packet is discarded. When unset, the kernel's default will be used. `IPv6RetransmissionTimeSec=` Configures IPv6 Retransmission Time. The time between retransmitted Neighbor Solicitation messages. Used by address resolution and the Neighbor Unreachability Detection algorithm. A value of zero is ignored and the kernel's current value will be used. Defaults to unset, and the kernel's current value will be used. `IPv4DuplicateAddressDetectionTimeoutSec=` Configures the maximum timeout for IPv4 Duplicate Address Detection (RFC 5227). Must be a value between 1 millisecond and 60 seconds. If set, Duplicate Address Detection takes a randomized time between 57% (4/7) and 100% of the given value. If unset, defaults to 200 milliseconds. `IPv4ReversePathFilter=` Configure IPv4 Reverse Path Filtering. If enabled, when an IPv4 packet is received, the machine will first check whether the *source* of the packet would be routed through the interface it came in. If there is no route to the source on that interface, the machine will drop the packet. Takes one of `no`, `strict`, or `loose`. When `no`, no source validation will be done. When `strict`, each incoming packet is tested against the FIB and if the incoming interface is not the best reverse path, the packet check will fail. By default, failed packets are discarded. When `loose`, each incoming packet's source address is tested against the FIB. The packet is dropped only if the source address is not reachable via any interface on that router. See [RFC 3704](https://tools.ietf.org/html/rfc1027). When unset, the kernel's default will be used. `MulticastIGMPVersion=` Configures IPv4 Multicast IGMP Version to be used, and controls the value of `/proc/sys/net/ipv4/conf/INTERFACE/force_igmp_version`. Takes one of `no`, `v1`, `v2`, or `v3`. When `no`, no enforcement of an IGMP version is applied. IGMPv1/v2 fallbacks are allowed, and `systemd-networkd` will return to IGMPv3 mode after all IGMPv1/v2 Querier Present timers have expired. When `v1`, use of IGMP version 1 is enforced. An IGMPv1 report will be returned even if IGMPv2/v3 queries are received. When `v2`, use of IGMP version 2 is enforced. An IGMPv2 report will be returned if an IGMPv2/v3 query is received. `systemd-networkd` will fall back to IGMPv1 if an IGMPv1 query is received. When `v3`, use of IGMP version 3 is enforced, and the response is the same as with `no`. Defaults to unset — the sysctl is not set. `IPv4AcceptLocal=` Takes a boolean. Accept packets with local source addresses. In combination with suitable routing, this can be used to direct packets between two local interfaces over the wire and have them accepted properly. When unset, the kernel's default will be used. `IPv4RouteLocalnet=` Takes a boolean. When true, the kernel does not consider loopback addresses as martian source or destination while routing. This enables the use of 127.0.0.0/8 for local routing purposes. When unset, the kernel's default will be used. `IPv4SrcValidMark=` Takes a boolean. When enabled, the packet's firewall mark (fwmark) is included in the reverse path filter route lookup for source address validation on this interface. This is particularly useful for policy routing setups where packets may arrive with source addresses that are only valid in routing tables selected by their fwmark. When unset, the kernel's default will be used. `IPv4ProxyARP=` Takes a boolean. Configures proxy ARP for IPv4. Proxy ARP is the technique in which one host, usually a router, answers ARP requests intended for another machine. By "faking" its identity, the router accepts responsibility for routing packets to the "real" destination. See [RFC 1027](https://tools.ietf.org/html/rfc1027). When unset, the kernel's default will be used. `IPv4ProxyARPPrivateVLAN=` Takes a boolean. Configures proxy ARP private VLAN for IPv4, also known as VLAN aggregation, private VLAN, source-port filtering, port-isolation, or MAC-forced forwarding. This variant of the ARP proxy technique will allow the ARP proxy to reply back to the same interface. See [RFC 3069](https://tools.ietf.org/html/rfc3069). When unset, the kernel's default will be used. `IPv6ProxyNDP=` Takes a boolean. Configures proxy NDP for IPv6. Proxy NDP (Neighbor Discovery Protocol) is a technique for IPv6 to allow routing of addresses to a different destination when peers expect them to be present on a certain physical link. In this case, a router answers Neighbour Advertisement messages intended for another machine by offering its own MAC address as destination. Unlike proxy ARP for IPv4, it is not enabled globally, but will only send Neighbour Advertisement messages for addresses in the IPv6 neighbor proxy table, which can also be shown by `ip -6 neighbour show proxy`. `systemd-networkd` will control the per-interface \`proxy_ndp\` switch for each configured interface depending on this option. When unset, the kernel's default will be used. `ProxyNeighbor=` Takes an IPv4 or IPv6 address for which ARP requests or Neighbour Advertisement messages will be proxied. This option may be specified more than once. `systemd-networkd` will add the specified address to the kernel's neighbour proxy table. For an IPv4 address, a proxy ARP entry will be added. For an IPv6 address, a proxy NDP entry will be added. When an IPv6 address is specified, `IPv6ProxyNDP=yes` is implied. If `IPv6ProxyNDP=` is explicitly disabled, IPv6 addresses specified with `ProxyNeighbor=` are ignored. Note, unlike IPv6, specifying an IPv4 address does *not* imply `IPv4ProxyARP=`. `IPv6SendRA=` Whether to enable or disable Router Advertisement sending on a link. Takes a boolean value. When enabled, prefixes configured in \[IPv6Prefix\] sections and routes configured in the \[IPv6RoutePrefix\] sections are distributed as defined in the \[IPv6SendRA\] section. If `DHCPPrefixDelegation=` is enabled, then the delegated prefixes are also distributed. See `DHCPPrefixDelegation=` setting and the \[IPv6SendRA\], \[IPv6Prefix\], \[IPv6RoutePrefix\], and \[DHCPPrefixDelegation\] sections for more configuration options. If enabled, `IPv6Forwarding=` on this interface is also enabled, unless the setting is explicitly specified. See `IPv6Forwarding=` in the above for more details. `DHCPPrefixDelegation=` Takes a boolean value. When enabled, requests subnet prefixes on another link via the DHCPv6 protocol or via the 6RD option in the DHCPv4 protocol. An address within each delegated prefix will be assigned, and the prefixes will be announced through IPv6 Router Advertisement if `IPv6SendRA=` is enabled. This behaviour can be configured in the \[DHCPPrefixDelegation\] section. Defaults to disabled. `IPv6MTUBytes=` Configures IPv6 maximum transmission unit (MTU). An integer greater than or equal to 1280 bytes. When unset, the kernel's default will be used. `MPLSRouting=` Control whether Multi-protocol Label Switching (MPLS) routing is enabled on this interface. This configures `/proc/sys/net/mpls/conf/INTERFACE/input`. Takes a boolean. Defaults to unset, and the kernel's default will be used. Note, `systemd-networkd` does *not* load any required kernel modules for MPLS. To enable the feature, `mpls_router` kernel module must be loaded before `systemd-networkd.service` is started. Consider adding the kernel module to `modules-load.d(5)`. `KeepMaster=` Takes a boolean value. When enabled, the current master interface index will not be changed, and `BatmanAdvanced=`, `Bond=`, `Bridge=`, and `VRF=` settings are ignored. This may be useful when a netdev with a master interface is created by another program, e.g. `systemd-nspawn(1)`. Defaults to false. `BatmanAdvanced=`; `Bond=`; `Bridge=`; `VRF=` The name of the B.A.T.M.A.N. Advanced, bond, bridge, or VRF interface to add the link to. See `systemd.netdev(5)`. `IPoIB=`; `IPVLAN=`; `IPVTAP=`; `MACsec=`; `MACVLAN=`; `MACVTAP=`; `Tunnel=`; `VLAN=`; `VXLAN=`; `Xfrm=` Takes a space-separated list of stacked netdevs to be created on the interface. See `systemd.netdev(5)`. This option may be specified more than once. If an empty string is specified, previous assignments for all netdev types are cleared. `ActiveSlave=` Takes a boolean. Specifies the new active slave. The `ActiveSlave=` option is only valid for following modes: `active-backup`, `balance-alb`, and `balance-tlb`. Defaults to false. `PrimarySlave=` Takes a boolean. Specifies which slave is the primary device. The specified device will always be the active slave while it is available. Only when the primary is off-line will alternate devices be used. This is useful when one slave is preferred over another, e.g. when one slave has higher throughput than another. The `PrimarySlave=` option is only valid for following modes: `active-backup`, `balance-alb`, and `balance-tlb`. Defaults to false. `ConfigureWithoutCarrier=` Takes a boolean. Allows `systemd-networkd` to configure a specific link even if it has no carrier. Defaults to false. If enabled, and the `IgnoreCarrierLoss=` setting is not explicitly set, then it is enabled as well. With this enabled, to make the interface enter the `configured` state, which is required to make `systemd-networkd-wait-online` work properly for the interface, all dynamic address configuration mechanisms like `DHCP=` and `IPv6AcceptRA=` (which is enabled by default in most cases) need to be disabled. Also, `DuplicateAddressDetection=` (which is enabled by default for IPv4 link-local addresses and all IPv6 addresses) needs to be disabled for all static address configurations. Otherwise, without carrier, the interface will be stuck in the `configuring` state, and `systemd-networkd-wait-online` for the interface will timeout. Also, it is recommended to set `RequiredForOnline=no-carrier` to make `systemd-networkd-wait-online` work for the interface. `IgnoreCarrierLoss=` Takes a boolean or a timespan. When true, `systemd-networkd` retains both the static and dynamic configuration of the interface even if its carrier is lost. When false, `systemd-networkd` drops both the static and dynamic configuration of the interface. When a timespan is specified, `systemd-networkd` waits for the specified timespan, and ignores the carrier loss if the link regain its carrier within the timespan. Setting 0 seconds is equivalent to `no`, and `infinite` is equivalent to `yes`. Setting a finite timespan may be useful when e.g. in the following cases: - A wireless interface connecting to a network which has multiple access points with the same SSID. - Enslaving a wireless interface to a bond interface, which may disconnect from the connected access point and causes its carrier to be lost. - The driver of the interface resets when the MTU is changed. When `Bond=` is specified to a wireless interface, defaults to 3 seconds. When the DHCPv4 client is enabled and `UseMTU=` in the \[DHCPv4\] section enabled, defaults to 5 seconds. Otherwise, defaults to the value specified with `ConfigureWithoutCarrier=`. When `ActivationPolicy=` is set to `always-up`, this is forced to `yes`, and ignored any user specified values. `KeepConfiguration=` Takes a boolean or one of `static`, `dynamic-on-stop`, and `dynamic`. When `static`, `systemd-networkd` will not drop statically configured addresses and routes on starting up process. When `dynamic-on-stop`, the dynamically configured addresses and routes, such as DHCPv4, DHCPv6, SLAAC, and IPv4 link-local address, will not be dropped when `systemd-networkd` is being stopped. When `dynamic`, the dynamically configured addresses and routes will never be dropped, and the lifetime of DHCPv4 leases will be ignored. This is contrary to the DHCP specification, but may be the best choice if, e.g., the root filesystem relies on this connection. The setting `dynamic` implies `dynamic-on-stop`, and `yes` implies `dynamic` and `static`. Defaults to `dynamic-on-stop` when `systemd-networkd` is running in initrd, `yes` when the root filesystem is a network filesystem, and `no` otherwise. # \[Address\] Section Options An \[Address\] section accepts the following keys. Specify several \[Address\] sections to configure several addresses. `Address=` As in the \[Network\] section. This setting is mandatory. Each \[Address\] section can contain one `Address=` setting. `Peer=` The peer address in a point-to-point connection. Accepts the same format as the `Address=` setting. `Broadcast=` Takes an IPv4 address or boolean value. The address must be in the format described in `inet_pton(3)`. If set to true, then the IPv4 broadcast address will be derived from the `Address=` setting. If set to false, then the broadcast address will not be set. Defaults to true, except for wireguard interfaces, where it defaults to false. `Label=` Specifies the label for the IPv4 address. The label must be a 7-bit ASCII string with a length of 1…15 characters. Defaults to unset. `PreferredLifetime=` Allows the default "preferred lifetime" of the address to be overridden. Only three settings are accepted: `forever`, `infinity`, which is the default and means that the address never expires, and `0`, which means that the address is considered immediately "expired" and will not be used, unless explicitly requested. A setting of `PreferredLifetime=0` is useful for addresses which are added to be used only by a specific application, which is then configured to use them explicitly. `Scope=` The scope of the address, which can be `global` (valid everywhere on the network, even through a gateway), `link` (only valid on this device, will not traverse a gateway) or `host` (only valid within the device itself, e.g. 127.0.0.1) or an integer in the range 0…255. Defaults to `global`. IPv4 only - IPv6 scope is automatically assigned by the kernel and cannot be set manually. `RouteMetric=` The metric of the prefix route, which is pointing to the subnet of the configured IP address, taking the configured prefix length into account. Takes an unsigned integer in the range 0…4294967295. When unset or set to 0, the kernel's default value is used. This setting will be ignored when `AddPrefixRoute=` is false. `HomeAddress=` Takes a boolean. Designates this address the "home address" as defined in [RFC 6275](https://tools.ietf.org/html/rfc6275). Supported only on IPv6. Defaults to false. `DuplicateAddressDetection=` Takes one of `ipv4`, `ipv6`, `both`, or `none`. When `ipv4`, performs IPv4 Address Conflict Detection. See [RFC 5227](https://tools.ietf.org/html/rfc5227). When `ipv6`, performs IPv6 Duplicate Address Detection. See [RFC 4862](https://tools.ietf.org/html/rfc4862). Defaults to `ipv4` for IPv4 link-local addresses (169.254.0.0/16), `ipv6` for IPv6 addresses, and `none` otherwise. When enabled, regardless implicitly or not, `ARP=` is enabled unless it is explicitly configured. `ManageTemporaryAddress=` Takes a boolean. If true the kernel manage temporary addresses created from this one as template on behalf of Privacy Extensions [RFC 3041](https://tools.ietf.org/html/rfc3041). For this to become active, the use_tempaddr sysctl setting has to be set to a value greater than zero. The given address needs to have a prefix length of 64. This flag allows using privacy extensions in a manually configured network, just like if stateless auto-configuration was active. Defaults to false. `AddPrefixRoute=` Takes a boolean. When true, the prefix route for the address is automatically added. Defaults to true. `AutoJoin=` Takes a boolean. Joining multicast group on ethernet level via `ip maddr` command would not work if we have an Ethernet switch that does IGMP snooping since the switch would not replicate multicast packets on ports that did not have IGMP reports for the multicast addresses. Linux vxlan interfaces created via `ip link add vxlan` or `systemd-networkd`'s netdev kind vxlan have the group option that enables them to do the required join. By extending `ip address` command with option `autojoin` we can get similar functionality for openvswitch (OVS) vxlan interfaces as well as other tunneling mechanisms that need to receive multicast traffic. Defaults to `no`. `NetLabel=`\ This setting provides a method for integrating static and dynamic network configuration into Linux [NetLabel](https://docs.kernel.org/netlabel/index.html) subsystem rules, used by [Linux Security Modules (LSMs)](https://en.wikipedia.org/wiki/Linux_Security_Modules) for network access control. The label, with suitable LSM rules, can be used to control connectivity of (for example) a service with peers in the local network. At least with SELinux, only the ingress can be controlled but not egress. The benefit of using this setting is that it may be possible to apply interface independent part of NetLabel configuration at very early stage of system boot sequence, at the time when the network interfaces are not available yet, with `netlabelctl(8)`, and the per-interface configuration with `systemd-networkd` once the interfaces appear later. Currently this feature is only implemented for SELinux. The option expects a single NetLabel label. The label must conform to lexicographic restrictions of LSM labels. When an interface is configured with IP addresses, the addresses and subnetwork masks will be appended to the [NetLabel Fallback Peer Labeling](https://github.com/SELinuxProject/selinux-notebook/blob/main/src/network_support.md) rules. They will be removed when the interface is deconfigured. Failures to manage the labels will be ignored. > [!WARNING] > Once labeling is enabled for network traffic, a lot of LSM access control points in Linux networking stack go from dormant to active. Care should be taken to avoid getting into a situation where for example remote connectivity is broken, when the security policy has not been updated to consider LSM per-packet access controls and no rules would allow any network traffic. Also note that additional configuration with `netlabelctl(8)` is needed. Example: [Address] NetLabel=system_u:object_r:localnet_peer_t:s0 With the example rules applying for interface `eth0`, when the interface is configured with an IPv4 address of 10.0.0.123/8, `systemd-networkd` performs the equivalent of `netlabelctl` operation netlabelctl unlbl add interface eth0 address:10.0.0.0/8 label:system_u:object_r:localnet_peer_t:s0 and the reverse operation when the IPv4 address is deconfigured. The configuration can be used with LSM rules; in case of SELinux to allow a SELinux domain to receive data from objects of SELinux `peer` class. For example: type localnet_peer_t; allow my_server_t localnet_peer_t:peer recv; The effect of the above configuration and rules (in absence of other rules as may be the case) is to only allow `my_server_t` (and nothing else) to receive data from local subnet 10.0.0.0/8 of interface `eth0`. `NFTSet=`\:\:\:\ This setting provides a method for integrating network configuration into firewall rules with [NFT](https://netfilter.org/projects/nftables/index.html) sets. The benefit of using the setting is that static network configuration (or dynamically obtained network addresses, see similar directives in other sections) can be used in firewall rules with the indirection of NFT set types. For example, access could be granted for hosts in the local subnetwork only. Firewall rules using IP address of an interface are also instantly updated when the network configuration changes, for example via DHCP. This option expects a whitespace separated list of NFT set definitions. Each definition consists of a colon-separated tuple of source type (one of `address`, `prefix` or `ifindex`), NFT address family (one of `arp`, `bridge`, `inet`, `ip`, `ip6`, or `netdev`), table name and set name. The names of tables and sets must conform to lexicographic restrictions of NFT table names. The type of the element used in the NFT filter must match the type implied by the directive (`address`, `prefix` or `ifindex`) and address type (IPv4 or IPv6) as shown in the table below. | Source type | Description | Corresponding NFT type name | |----|----|----| | `address` | host IP address | `ipv4_addr` or `ipv6_addr` | | `prefix` | network prefix | `ipv4_addr` or `ipv6_addr`, with `flags interval` | | `ifindex` | interface index | `iface_index` | Defined `source type` values When an interface is configured with IP addresses, the addresses, subnetwork masks or interface index will be appended to the NFT sets. The information will be removed when the interface is deconfigured. `systemd-networkd` only inserts elements to (or removes from) the sets, so the related NFT rules, tables and sets must be prepared elsewhere in advance. Failures to manage the sets will be ignored. Example: [Address] NFTSet=prefix:netdev:filter:eth_ipv4_prefix Corresponding NFT rules: table netdev filter { set eth_ipv4_prefix { type ipv4_addr flags interval } chain eth_ingress { type filter hook ingress device "eth0" priority filter; policy drop; ip daddr != @eth_ipv4_prefix drop accept } } # \[Neighbor\] Section Options A \[Neighbor\] section accepts the following keys. The neighbor section adds a permanent, static entry to the neighbor table (IPv6) or ARP table (IPv4) for the given hardware address on the links matched for the network. Specify several \[Neighbor\] sections to configure several static neighbors. `Address=` The IP address of the neighbor. `LinkLayerAddress=` The link layer address (MAC address or IP address) of the neighbor. # \[IPv6AddressLabel\] Section Options An \[IPv6AddressLabel\] section accepts the following keys. Specify several \[IPv6AddressLabel\] sections to configure several address labels. IPv6 address labels are used for address selection. See [RFC 3484](https://tools.ietf.org/html/rfc3484). Precedence is managed by userspace, and only the label itself is stored in the kernel. `Label=` The label for the prefix. Takes an unsigned integer in the range 0…4294967294 (0xfffffffe). 4294967295 (0xffffffff) is reserved. This setting is mandatory. `Prefix=` Takes an IPv6 address with a prefix length, separated by a slash `/` character. This setting is mandatory. # \[RoutingPolicyRule\] Section Options An \[RoutingPolicyRule\] section accepts the following settings. Specify several \[RoutingPolicyRule\] sections to configure several rules. `TypeOfService=` This specifies the Type of Service (ToS) field of packets to match; it takes an unsigned integer in the range 0…255. The field can be used to specify precedence (the first 3 bits) and ToS (the next 3 bits). The field can be also used to specify Differentiated Services Code Point (DSCP) (the first 6 bits) and Explicit Congestion Notification (ECN) (the last 2 bits). See [Type of Service](https://en.wikipedia.org/wiki/Type_of_service) and [Differentiated services](https://en.wikipedia.org/wiki/Differentiated_services) for more details. `From=` Specifies the source address prefix to match. Possibly followed by a slash and the prefix length. `To=` Specifies the destination address prefix to match. Possibly followed by a slash and the prefix length. `FirewallMark=` Specifies the iptables firewall mark value to match (a number in the range 0…4294967295). Optionally, the firewall mask (also a number between 0…4294967295) can be suffixed with a slash (`/`), e.g., `7/255`. When the mark value is non-zero and no mask is explicitly specified, all bits of the mark are compared. `Table=` Specifies the routing table identifier to look up if the rule selector matches. Takes one of predefined names `default`, `main`, and `local`, and names defined in `RouteTable=` in `networkd.conf(5)`, or a number between 1 and 4294967295. Defaults to `main`. Ignored if `L3MasterDevice=` is true. `Priority=` Specifies the priority of this rule. `Priority=` is an integer in the range 0…4294967295. Higher number means lower priority, and rules get processed in order of increasing number. Defaults to unset, and the kernel will pick a value dynamically. `GoTo=` Specifies the target priority used by the `goto` type of rule. Takes an integer in the range 1…4294967295. This must be larger than the priority of the rule specified in `Priority=`. When specified, `Type=goto` is implied. This is mandatory when `Type=goto`. `IncomingInterface=` Specifies incoming device to match. If the interface is loopback, the rule only matches packets originating from this host. `OutgoingInterface=` Specifies the outgoing device to match. The outgoing interface is only available for packets originating from local sockets that are bound to a device. `L3MasterDevice=` Takes a boolean. Specifies whether the rule is to direct lookups to the tables associated with level 3 master devices (also known as Virtual Routing and Forwarding or VRF devices). For further details see [ Virtual Routing and Forwarding (VRF)](https://docs.kernel.org/networking/vrf.html). Defaults to false. `SourcePort=` Specifies the source IP port or IP port range match in forwarding information base (FIB) rules. A port range is specified by the lower and upper port separated by a dash. Defaults to unset. `DestinationPort=` Specifies the destination IP port or IP port range match in forwarding information base (FIB) rules. A port range is specified by the lower and upper port separated by a dash. Defaults to unset. `IPProtocol=` Specifies the IP protocol to match in forwarding information base (FIB) rules. Takes IP protocol name such as `tcp`, `udp` or `sctp`, or IP protocol number such as `6` for `tcp` or `17` for `udp`. Defaults to unset. `InvertRule=` A boolean. Specifies whether the rule is to be inverted. Defaults to false. `Family=` Takes a special value `ipv4`, `ipv6`, or `both`. By default, the address family is determined by the address specified in `To=` or `From=`. If neither `To=` nor `From=` are specified, then defaults to `ipv4`. `User=` Takes a username, a user ID, or a range of user IDs separated by a dash. Defaults to unset. `SuppressPrefixLength=` Takes a number \ in the range 0…128 and rejects routing decisions that have a prefix length of \ or less. Defaults to unset. `SuppressInterfaceGroup=` Takes an integer in the range 0…2147483647 and rejects routing decisions that have an interface with the same group id. It has the same meaning as `suppress_ifgroup` in `ip rule`. Defaults to unset. `Type=` Specifies Routing Policy Database (RPDB) rule type. Takes one of `table`, `goto`, `nop`, `blackhole`, `unreachable`, or `prohibit`. When `goto`, the target priority must be specified in `GoTo=`. Defaults to `table`. # \[NextHop\] Section Options The \[NextHop\] section is used to manipulate entries in the kernel's "nexthop" tables. The \[NextHop\] section accepts the following settings. Specify several \[NextHop\] sections to configure several hops. `Id=` The id of the next hop. Takes an integer in the range 1…4294967295. This is mandatory if `ManageForeignNextHops=no` is specified in `networkd.conf(5)`. Otherwise, if unspecified, an unused ID will be automatically picked. `Gateway=` As in the \[Network\] section. `Family=` Takes one of the special values `ipv4` or `ipv6`. By default, the family is determined by the address specified in `Gateway=`. If `Gateway=` is not specified, then defaults to `ipv4`. `OnLink=` Takes a boolean. If set to true, the kernel does not have to check if the gateway is reachable directly by the current machine (i.e., attached to the local network), so that we can insert the nexthop in the kernel table without it being complained about. Defaults to `no`. `Blackhole=` Takes a boolean. If enabled, packets to the corresponding routes are discarded silently, and `Gateway=` cannot be specified. Defaults to `no`. `Group=` Takes a whitespace separated list of nexthop IDs. Each ID must be in the range 1…4294967295. Optionally, each nexthop ID can take a weight after a colon (`id:weight`). The weight must be in the range 1…255. If the weight is not specified, then it is assumed that the weight is 1. This setting cannot be specified with `Gateway=`, `Family=`, `Blackhole=`. This setting can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. Defaults to unset. # \[Route\] Section Options The \[Route\] section accepts the following settings. Specify several \[Route\] sections to configure several routes. `Gateway=` Takes the gateway address or the special values `_dhcp4` and `_ipv6ra`. If `_dhcp4` or `_ipv6ra` is set, then the gateway address provided by DHCPv4 or IPv6 RA is used. When`_dhcp4`, the acquired DHCPv4 address will be used as the preferred source address of the route, unless it is explicitly configured in `PreferredSource=`. `GatewayOnLink=` Takes a boolean. If set to true, the kernel does not have to check if the gateway is reachable directly by the current machine (i.e., attached to the local network), so that we can insert the route in the kernel table without it being complained about. Defaults to `no`. `Destination=` The destination prefix of the route. Possibly followed by a slash and the prefix length. If omitted, a full-length host route is assumed. `Source=` The source prefix of the route. Possibly followed by a slash and the prefix length. If omitted, a full-length host route is assumed. `Metric=` The metric of the route. Takes an unsigned integer in the range 0…4294967295. Defaults to unset, and the kernel's default will be used. `IPv6Preference=` Specifies the route preference as defined in [RFC 4191](https://tools.ietf.org/html/rfc4191) for Router Discovery messages. Which can be one of `low` the route has a lowest priority, `medium` the route has a default priority or `high` the route has a highest priority. `Scope=` The scope of the IPv4 route, which can be `global`, `site`, `link`, `host`, or `nowhere`: - `global` means the route can reach hosts more than one hop away. - `site` means an interior route in the local autonomous system. - `link` means the route can only reach hosts on the local network (one hop away). - `host` means the route will not leave the local machine (used for internal addresses like 127.0.0.1). - `nowhere` means the destination does not exist. For IPv4 route, defaults to `host` if `Type=` is `local` or `nat`, and `link` if `Type=` is `broadcast`, `multicast`, `anycast`, or `unicast`. In other cases, defaults to `global`. The value is not used for IPv6. `PreferredSource=` The preferred source address of the route. Takes `no` or an address in the format described in `inet_pton(3)`. If `Gateway=_dhcp4` is specified, defaults to the acquired DHCPv4 address. Otherwise, defaults to unset. The value `no` may be useful to configure a route with `Gateway=_dhcp4` without setting preferred source route address. `Table=` The table identifier for the route. Takes one of predefined names `default`, `main`, and `local`, and names defined in `RouteTable=` in `networkd.conf(5)`, or a number between 1 and 4294967295. The table can be retrieved using `ip route show table num`. If unset and `Type=` is `local`, `broadcast`, `anycast`, or `nat`, then `local` is used. In other cases, defaults to `main`. `HopLimit=` Configures per route hop limit. Takes an integer in the range 1…255. See also `IPv6HopLimit=`. `Protocol=` The protocol identifier for the route. Takes a number between 0 and 255 or the special values `kernel`, `boot`, `static`, `ra` and `dhcp`. Defaults to `static`. `Type=` Specifies the type for the route. Takes one of `unicast`, `local`, `broadcast`, `anycast`, `multicast`, `blackhole`, `unreachable`, `prohibit`, `throw`, `nat`, and `xresolve`. If `unicast`, a regular route is defined, i.e. a route indicating the path to take to a destination network address. If `blackhole`, packets to the defined route are discarded silently. If `unreachable`, packets to the defined route are discarded and the ICMP message "Host Unreachable" is generated. If `prohibit`, packets to the defined route are discarded and the ICMP message "Communication Administratively Prohibited" is generated. If `throw`, route lookup in the current routing table will fail and the route selection process will return to Routing Policy Database (RPDB). Defaults to `unicast`. `InitialCongestionWindow=` The TCP initial congestion window is used during the start of a TCP connection. During the start of a TCP session, when a client requests a resource, the server's initial congestion window determines how many packets will be sent during the initial burst of data without waiting for acknowledgement. Takes a number between 1 and 1023. Note that 100 is considered an extremely large value for this option. When unset, the kernel's default (typically 10) will be used. `InitialAdvertisedReceiveWindow=` The TCP initial advertised receive window is the amount of receive data (in bytes) that can initially be buffered at one time on a connection. The sending host can send only that amount of data before waiting for an acknowledgment and window update from the receiving host. Takes a number between 1 and 1023. Note that 100 is considered an extremely large value for this option. When unset, the kernel's default will be used. `QuickAck=` Takes a boolean. When true, the TCP quick ACK mode for the route is enabled. When unset, the kernel's default will be used. `FastOpenNoCookie=` Takes a boolean. When true enables TCP fastopen without a cookie on a per-route basis. When unset, the kernel's default will be used. `MTUBytes=` The maximum transmission unit in bytes to set for the route. The usual suffixes K, M, G, are supported and are understood to the base of 1024. `TCPAdvertisedMaximumSegmentSize=` Specifies the Path MSS (in bytes) hints given on TCP layer. The usual suffixes K, M, G, are supported and are understood to the base of 1024. An unsigned integer in the range 1…4294967294. When unset, the kernel's default will be used. `TCPCongestionControlAlgorithm=` Specifies the TCP congestion control algorithm for the route. Takes a name of the algorithm, e.g. `bbr`, `dctcp`, or `vegas`. When unset, the kernel's default will be used. `TCPRetransmissionTimeoutSec=` Specifies the TCP Retransmission Timeout (RTO) for the route. Takes time values in seconds. This value specifies the timeout of an alive TCP connection, when retransmissions remain unacknowledged. When unset, the kernel's default will be used. `MultiPathRoute=` Configures multipath route. Multipath routing is the technique of using multiple alternative paths through a network. Takes a gateway address and/or a network interface name or index (prefixed with `@`). At least one of these must be specified. Optionally, a weight in 1..256 can be specified, separated with whitespace. This setting can be specified multiple times. If an empty string is assigned, then all previous assignments are cleared. Examples: MultiPathRoute=10.0.0.1@eth0 20 MultiPathRoute=192.168.1.1 50 MultiPathRoute=@wg0 15 MultiPathRoute=2001:db8::1@eth0 `NextHop=` Specifies the nexthop id. Takes an unsigned integer in the range 1…4294967295. If set, the corresponding \[NextHop\] section must be configured. Defaults to unset. # \[DHCPv4\] Section Options The \[DHCPv4\] section configures the DHCPv4 client, if it is enabled with the `DHCP=` setting described above: `RequestAddress=` Takes an IPv4 address. When specified, the Requested IP Address option (option code 50) is added with it to the initial DHCPDISCOVER message sent by the DHCP client. Defaults to unset, and an already assigned dynamic address to the interface is automatically picked. `SendHostname=` When true (the default), the machine's hostname (or the value specified with `Hostname=`, described below) will be sent to the DHCP server. Note that the hostname must consist only of 7-bit ASCII lower-case characters and no spaces, and be formatted as a valid DNS domain name. A single-label hostname is sent as DHCP option 12 (Host Name, [RFC 2132](https://tools.ietf.org/html/rfc2132)); a multi-label hostname (FQDN) is sent instead as DHCP option 81 (Client FQDN, [RFC 4702](https://tools.ietf.org/html/rfc4702)). Otherwise, the hostname is not sent even if this option is true. `Hostname=` Use this value for the hostname which is sent to the DHCP server, instead of machine's hostname. Note that the specified hostname must consist only of 7-bit ASCII lower-case characters and no spaces, and be formatted as a valid DNS domain name. Multi-label hostnames (FQDNs) are acceptable; see `SendHostname=` above for details. `SendHostnameUpdates=` Takes a boolean. When true (the default) and the machine's hostname is sent to the DHCP server, the hostname sent by the running DHCP client is updated when the machine's hostname is changed, and the lease is renewed immediately to send the new hostname. When false, the hostname known when the interface was configured is sent until the interface is reconfigured. Disabling this may be useful when the DHCP server provides different settings depending on the hostname sent by the client. This setting has no effect when `SendHostname=no`, `Hostname=`, or `Anonymize=yes` is specified. `MUDURL=` When configured, the specified Manufacturer Usage Description (MUD) URL will be sent to the DHCPv4 server. Takes a URL of length up to 255 characters. A superficial verification that the string is a valid URL will be performed. DHCPv4 clients are intended to have at most one MUD URL associated with them. See [RFC 8520](https://tools.ietf.org/html/rfc8520). MUD is an embedded software standard defined by the IETF that allows IoT device makers to advertise device specifications, including the intended communication patterns for their device when it connects to the network. The network can then use this to author a context-specific access policy, so the device functions only within those parameters. `ClientIdentifier=` The DHCPv4 client identifier to use. Takes one of `mac` or `duid`. If set to `mac`, the MAC address of the link is used. If set to `duid`, an RFC4361-compliant Client ID, which is the combination of IAID and DUID, is used. IAID can be configured by `IAID=`. DUID can be configured by `DUIDType=` and `DUIDRawData=`. When `Anonymize=` is enabled, `mac` is unconditionally used and the specified value will be ignored. When unspecified, the value specified in the same setting in `networkd.conf(5)` will be used. `VendorClassIdentifier=` The vendor class identifier used to identify vendor type and configuration. `UserClass=` A DHCPv4 client can use UserClass option to identify the type or category of user or applications it represents. The information contained in this option is a string that represents the user class of which the client is a member. Each class sets an identifying string of information to be used by the DHCP service to classify clients. Takes a whitespace-separated list of strings. `DUIDType=` Override the global `DUIDType=` setting for this network. See `networkd.conf(5)` for a description of possible values. `DUIDRawData=` Override the global `DUIDRawData=` setting for this network. See `networkd.conf(5)` for a description of possible values. `IAID=` The DHCP Identity Association Identifier (IAID) for the interface, a 32-bit unsigned integer. `RapidCommit=` Takes a boolean. The DHCPv4 client can obtain configuration parameters from a DHCPv4 server through a rapid two-message exchange (discover and ack). When the rapid commit option is set by both the DHCPv4 client and the DHCPv4 server, the two-message exchange is used. Otherwise, the four-message exchange (discover, offer, request, and ack) is used. The two-message exchange provides faster client configuration. See [RFC 4039](https://tools.ietf.org/html/rfc4039) for details. Defaults to true when `Anonymize=no` and neither `AllowList=` nor `DenyList=` is specified, and false otherwise. `Anonymize=` Takes a boolean. When true, the options sent to the DHCP server will follow the [RFC 7844](https://tools.ietf.org/html/rfc7844) (Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information. Defaults to false. This option should only be set to true when `MACAddressPolicy=` is set to `random` (see `systemd.link(5)`). When true, `ClientIdentifier=mac`, `RapidCommit=no`, `SendHostname=no`, `Use6RD=no`, `UseCaptivePortal=no`, `UseMTU=no`, `UseNTP=no`, `UseSIP=no`, and `UseTimezone=no` are implied and these settings in the .network file are silently ignored. Also, `Hostname=`, `MUDURL=`, `RequestAddress=`, `RequestOptions=`, `SendOption=`, `SendVendorOption=`, `UserClass=`, and `VendorClassIdentifier=` are silently ignored. With this option enabled DHCP requests will mimic those generated by Microsoft Windows, in order to reduce the ability to fingerprint and recognize installations. This means DHCP request sizes will grow and lease data will be more comprehensive than normally, though most of the requested data is not actually used. `RequestOptions=` Sets request options to be sent to the server in the DHCPv4 request options list. A whitespace-separated list of integers in the range 1…254. Defaults to unset. `SendOption=` Send an arbitrary raw option in the DHCPv4 request. Takes a DHCP option number, data type and data separated with a colon (`option:type:value`). The option number must be an integer in the range 1…254. The type takes one of `uint8`, `uint16`, `uint32`, `ipv4address`, or `string`. Special characters in the data string may be escaped using [C-style escapes](https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences). This setting can be specified multiple times. If an empty string is specified, then all options specified earlier are cleared. Defaults to unset. `SendVendorOption=` Send an arbitrary vendor option in the DHCPv4 request. Takes a DHCP option number, data type and data separated with a colon (`option:type:value`). The option number must be an integer in the range 1…254. The type takes one of `uint8`, `uint16`, `uint32`, `ipv4address`, or `string`. Special characters in the data string may be escaped using [C-style escapes](https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences). This setting can be specified multiple times. If an empty string is specified, then all options specified earlier are cleared. Defaults to unset. `IPServiceType=` Takes one of the special values `none`, `CS6`, or `CS4`. When `none` no IP service type is set to the packet sent from the DHCPv4 client. When `CS6` (network control) or `CS4` (realtime), the corresponding service type will be set. Defaults to `CS6`. `SocketPriority=` The Linux socket option `SO_PRIORITY` applied to the raw IP socket used for initial DHCPv4 messages. Unset by default. Usual values range from 0 to 6. More details about `SO_PRIORITY` socket option in `socket(7)`. Can be used in conjunction with \[VLAN\] section `EgressQOSMaps=` setting of .netdev file to set the 802.1Q VLAN ethernet tagged header priority, see `systemd.netdev(5)`. `BOOTP=` Takes a boolean. When enabled, the DHCPv4 client will be configured to communicate with BOOTP servers, rather than with DHCP servers. Defaults to off. `Label=` Specifies the label for the IPv4 address received from the DHCP server. The label must be a 7-bit ASCII string with a length of 1…15 characters. Defaults to unset. `UseDNS=` When true (the default), the DNS servers received from the DHCP server will be used. This corresponds to the `nameserver` option in `resolv.conf(5)`. `RoutesToDNS=` When true, the routes to the DNS servers received from the DHCP server will be configured. When `UseDNS=` is disabled, this setting is ignored. Defaults to true. `UseNTP=` When true (the default), the NTP servers received from the DHCP server will be used by `systemd-timesyncd.service`. `RoutesToNTP=` When true, the routes to the NTP servers received from the DHCP server will be configured. When `UseNTP=` is disabled, this setting is ignored. Defaults to true. `UseSIP=` When true (the default), the SIP servers received from the DHCP server will be collected and made available to client programs. `UseCaptivePortal=` When true (the default), the captive portal advertised by the DHCP server will be recorded and made available to client programs and displayed in the `networkctl(1)` status output per-link. `UseDNR=` When true, designated resolvers advertised by the DHCP server will be used as encrypted DNS servers. See [RFC 9463](https://datatracker.ietf.org/doc/html/rfc9463). Defaults to unset, and the value for `UseDNS=` will be used. `UseMTU=` When true, the interface maximum transmission unit from the DHCP server will be used on the current link. If `MTUBytes=` is set, then this setting is ignored. Defaults to false. Note, some drivers will reset the interfaces if the MTU is changed. For such interfaces, please try to use `IgnoreCarrierLoss=` with a short timespan, e.g. `3 seconds`. `UseHostname=` When true (the default), the hostname received from the DHCP server will be set as the transient hostname of the system. `UseDomains=` Takes a boolean, or the special value `route`. When true, the domain name received from the DHCP server will be used as DNS search domain over this link, similarly to the effect of the `Domains=` setting. If set to `route`, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching, similarly to the effect of the `Domains=` setting when the argument is prefixed with `~`. When unspecified, the value specified in the same setting in the \[Network\] section will be used. When it is unspecified, the value specified in the same setting in the \[DHCPv4\] section in `networkd.conf(5)` will be used. When it is unspecified, the value specified in the same setting in the \[Network\] section in `networkd.conf(5)` will be used. When none of them are specified, defaults to `no`. It is recommended to enable this option only on trusted networks, as setting this affects resolution of all hostnames, in particular of single-label names. It is generally safer to use the supplied domain only as routing domain, rather than as search domain, in order to not have it affect local resolution of single-label names. When set to true, this setting corresponds to the `domain` option in `resolv.conf(5)`. `UseRoutes=` When true (the default), the static routes will be requested from the DHCP server and added to the routing table with a metric of 1024, and a scope of `global`, `link` or `host`, depending on the route's destination and gateway. If the destination is on the local host, e.g., 127.x.x.x, or the same as the link's own address, the scope will be set to `host`. Otherwise, if the gateway is null (a direct route), a `link` scope will be used. For anything else, scope defaults to `global`. `RouteMetric=` Set the routing metric for routes specified by the DHCP server (including the prefix route added for the specified prefix). Takes an unsigned integer in the range 0…4294967295. Defaults to 1024. `RouteTable=num` The table identifier for DHCP routes. Takes one of predefined names `default`, `main`, and `local`, and names defined in `RouteTable=` in `networkd.conf(5)`, or a number between 1…4294967295. When used in combination with `VRF=`, the VRF's routing table is used when this parameter is not specified. `RouteMTUBytes=` Specifies the MTU for the DHCP routes. Please see the \[Route\] section for further details. `QuickAck=` Takes a boolean. When true, the TCP quick ACK mode is enabled for the routes configured by the acquired DHCPv4 lease. When unset, the kernel's default will be used. `InitialCongestionWindow=` As in the \[Route\] section. `InitialAdvertisedReceiveWindow=` As in the \[Route\] section. `UseGateway=` When true, and the DHCP server provides a Router option, the default gateway based on the router address will be configured. Defaults to unset, and the value specified with `UseRoutes=` will be used. Note, when the server provides both the Router and Classless Static Routes option, and `UseRoutes=` is enabled, the Router option is always ignored regardless of this setting. See [RFC 3442](https://datatracker.ietf.org/doc/html/rfc3442). `UseTimezone=` When true, the timezone received from the DHCP server will be set as timezone of the local system. Defaults to false. `Use6RD=` When true, subnets of the received IPv6 prefix are assigned to downstream interfaces which enables `DHCPPrefixDelegation=`. See also `DHCPPrefixDelegation=` in the \[Network\] section, the \[DHCPPrefixDelegation\] section, and [RFC 5969](https://tools.ietf.org/html/rfc5969). Defaults to false. `UnassignedSubnetPolicy=` Takes `none`, or one of the reject types: `unreachable`, `prohibit`, `blackhole`, or `throw`. If a reject type is specified, the reject route corresponding to the acquired 6RD prefix will be configured. For example, when `unreachable`, unreachable 2001:db8::/56 dev lo proto dhcp metric 1024 pref medium will be configured. See [RFC 7084](https://datatracker.ietf.org/doc/html/rfc7084). If `none` is specified, such route will not be configured. This may be useful when custom firewall rules that handle packets for unassigned subnets will be configured. Defaults to `unreachable`. `IPv6OnlyMode=` When true, the DHCPv4 configuration will be delayed by the timespan provided by the DHCP server and skip to configure dynamic IPv4 network connectivity if IPv6 connectivity is provided within the timespan. See [RFC 8925](https://tools.ietf.org/html/rfc8925). Defaults to false. `FallbackLeaseLifetimeSec=` Allows one to set DHCPv4 lease lifetime when DHCPv4 server does not send the lease lifetime. Takes one of `forever` or `infinity`. If specified, the acquired address never expires. Defaults to unset. `RequestBroadcast=` Request the server to use broadcast messages before the IP address has been configured. This is necessary for devices that cannot receive RAW packets, or that cannot receive packets at all before an IP address has been configured. On the other hand, this must not be enabled on networks where broadcasts are filtered out. `MaxAttempts=` Specifies how many times the DHCPv4 client configuration should be attempted. Takes a number or `infinity`. Defaults to `infinity`. Note that the time between retries is increased exponentially, up to approximately one per minute, so the network will not be overloaded even if this number is high. The default is suitable in most circumstances. `ListenPort=` Set the port from which the DHCP client packets originate. `ServerPort=` Set the port on which the DHCP server is listening. `DenyList=` A whitespace-separated list of IPv4 addresses. Each address can optionally take a prefix length after `/`. DHCP offers from servers in the list are rejected. Note that if `AllowList=` is configured then `DenyList=` is ignored. Note that this filters only DHCP offers, so the filtering might not work when `RapidCommit=` is enabled. See also `RapidCommit=` above. `AllowList=` A whitespace-separated list of IPv4 addresses. Each address can optionally take a prefix length after `/`. DHCP offers from servers in the list are accepted. Note that this filters only DHCP offers, so the filtering might not work when `RapidCommit=` is enabled. See also `RapidCommit=` above. `SendRelease=` When true, the DHCPv4 client sends a DHCP release packet when it stops. Defaults to true. `SendDecline=` A boolean. When true, `systemd-networkd` performs IPv4 Duplicate Address Detection to the acquired address by the DHCPv4 client. If duplicate is detected, the DHCPv4 client rejects the address by sending a `DHCPDECLINE` packet to the DHCP server, and tries to obtain an IP address again. See [RFC 5227](https://tools.ietf.org/html/rfc5227). Defaults to false. `NetLabel=` This applies the NetLabel for the addresses received with DHCP, like `NetLabel=` in \[Address\] section applies it to statically configured addresses. See `NetLabel=` in \[Address\] section for more details. `NFTSet=` This applies the NFT set for the network configuration received with DHCP, like `NFTSet=` in \[Address\] section applies it to static configuration. See `NFTSet=` in \[Address\] section for more details. For `address` or `prefix` source types, the type of the element used in the NFT filter must be `ipv4_addr`. # \[DHCPv6\] Section Options The \[DHCPv6\] section configures the DHCPv6 client, if it is enabled with the `DHCP=` setting described above, or invoked by the IPv6 Router Advertisement: `MUDURL=`; `IAID=`; `DUIDType=`; `DUIDRawData=`; `RequestOptions=` As in the \[DHCPv4\] section. `SendOption=` As in the \[DHCPv4\] section, however because DHCPv6 uses 16-bit fields to store option numbers, the option number is an integer in the range 1…65536. `SendVendorOption=` Send an arbitrary vendor option in the DHCPv6 request. Takes an enterprise identifier, DHCP option number, data type, and data separated with a colon (`enterprise identifier:option:type:value`). Enterprise identifier is an unsigned integer in the range 1…4294967294. The option number must be an integer in the range 1…254. Data type takes one of `uint8`, `uint16`, `uint32`, `ipv4address`, `ipv6address`, or `string`. Special characters in the data string may be escaped using [C-style escapes](https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences). This setting can be specified multiple times. If an empty string is specified, then all options specified earlier are cleared. Defaults to unset. `UserClass=` A DHCPv6 client can use User Class option to identify the type or category of user or applications it represents. The information contained in this option is a string that represents the user class of which the client is a member. Each class sets an identifying string of information to be used by the DHCP service to classify clients. Special characters in the data string may be escaped using [C-style escapes](https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences). This setting can be specified multiple times. If an empty string is specified, then all options specified earlier are cleared. Takes a whitespace-separated list of strings. Note that currently `NUL` bytes are not allowed. `VendorClass=` A DHCPv6 client can use VendorClass option to identify the vendor that manufactured the hardware on which the client is running. The information contained in the data area of this option is contained in one or more opaque fields that identify details of the hardware configuration. Takes a whitespace-separated list of strings. `PrefixDelegationHint=` Takes an IPv6 address with prefix length in the same format as the `Address=` in the \[Network\] section. The DHCPv6 client will include a prefix hint in the DHCPv6 solicitation sent to the server. The prefix length must be in the range 1…128. Defaults to unset. `UnassignedSubnetPolicy=` Takes `none` or one of the reject types: `unreachable`, `prohibit`, `blackhole`, or `throw`. If a reject type is specified, the reject route corresponding to the delegated prefix will be configured. For example, when `unreachable`, unreachable 2001:db8::/56 dev lo proto dhcp metric 1024 pref medium will be configured. See [RFC 7084](https://datatracker.ietf.org/doc/html/rfc7084). If `none` is specified, such route will not be configured. This may be useful when custom firewall rules that handle packets for unassigned subnets will be configured. Defaults to `unreachable`. `RouteTable=num` The table identifier for routes installed by the DHCPv6 client, e.g. unreachable routes for delegated prefixes. Takes one of the predefined names `default`, `main`, and `local`, names defined in `RouteTable=` in `networkd.conf(5)`, or a number between 1…4294967295. When used in combination with `VRF=`, the VRF's routing table is used when this parameter is not specified. `RapidCommit=` Takes a boolean. The DHCPv6 client can obtain configuration parameters from a DHCPv6 server through a rapid two-message exchange (solicit and reply). When the rapid commit option is set by both the DHCPv6 client and the DHCPv6 server, the two-message exchange is used. Otherwise, the four-message exchange (solicit, advertise, request, and reply) is used. The two-message exchange provides faster client configuration. See [RFC 3315](https://tools.ietf.org/html/rfc3315#section-17.2.1) for details. Defaults to true, and the two-message exchange will be used if the server support it. `SendHostname=` When true (the default), the machine's hostname (or the value specified with `Hostname=`, described below) will be sent to the DHCPv6 server. Note that the hostname must consist only of 7-bit ASCII lower-case characters and no spaces or dots, and be formatted as a valid DNS domain name. Otherwise, the hostname is not sent even if this option is true. `Hostname=` Use this value for the hostname which is sent to the DHCPv6 server, instead of machine's hostname. Note that the specified hostname must consist only of 7-bit ASCII lower-case characters and no spaces or dots, and be formatted as a valid DNS domain name. `SendHostnameUpdates=` As in the \[DHCPv4\] section, but for the DHCPv6 client. This setting has no effect when `SendHostname=no` or `Hostname=` is specified. `UseAddress=` When true (the default), the IP addresses provided by the DHCPv6 server will be assigned. `UseCaptivePortal=` When true (the default), the captive portal advertised by the DHCPv6 server will be recorded and made available to client programs and displayed in the `networkctl(1)` status output per-link. `UseDelegatedPrefix=` When true (the default), the client will request the DHCPv6 server to delegate prefixes. If the server provides prefixes to be delegated, then subnets of the prefixes are assigned to the interfaces that have `DHCPPrefixDelegation=yes`. See also the `DHCPPrefixDelegation=` setting in the \[Network\] section, settings in the \[DHCPPrefixDelegation\] section, and [RFC 8415](https://www.rfc-editor.org/rfc/rfc8415.html#section-6.3). `UseDNS=`; `UseDNR=`; `UseNTP=`; `UseSIP=`; `UseHostname=`; `UseDomains=`; `NetLabel=`; `SendRelease=` As in the \[DHCPv4\] section. `NFTSet=` This applies the NFT set for the network configuration received with DHCP, like `NFTSet=` in \[Address\] section applies it to static configuration. See `NFTSet=` in \[Address\] section for more details. For `address` or `prefix` source types, the type of the element used in the NFT filter must be `ipv6_addr`. `WithoutRA=` Allows DHCPv6 client to start without router advertisements's `managed` or `other configuration` flag. Takes one of `no`, `solicit`, or `information-request`. If this is not specified, `solicit` is used when `DHCPPrefixDelegation=` is enabled and `UplinkInterface=:self` is specified in the \[DHCPPrefixDelegation\] section. Otherwise, defaults to `no`, and the DHCPv6 client will be started when an RA is received. See also the `DHCPv6Client=` setting in the \[IPv6AcceptRA\] section. # \[DHCPPrefixDelegation\] Section Options The \[DHCPPrefixDelegation\] section configures subnet prefixes of the delegated prefixes acquired by a DHCPv6 client or by a DHCPv4 client through the 6RD option on another interface. The settings in this section are used only when the `DHCPPrefixDelegation=` setting in the \[Network\] section is enabled. `UplinkInterface=` Specifies the name or the index of the uplink interface, or one of the special values `:self` and `:auto`. When `:self`, the interface itself is considered the uplink interface, and `WithoutRA=solicit` is implied if the setting is not explicitly specified. When `:auto`, the first link which acquired prefixes to be delegated from the DHCPv6 or DHCPv4 server is selected. Defaults to `:auto`. `SubnetId=` Configure a specific subnet ID on the interface from a (previously) received prefix delegation. You can either set "auto" (the default) or a specific subnet ID (as defined in [RFC 4291](https://tools.ietf.org/html/rfc4291#section-2.5.4), section 2.5.4), in which case the allowed value is hexadecimal, from 0 to 0x7fffffffffffffff inclusive. `Announce=` Takes a boolean. When enabled, and `IPv6SendRA=` in \[Network\] section is enabled, the delegated prefixes are distributed through the IPv6 Router Advertisement. This setting will be ignored when the `DHCPPrefixDelegation=` setting is enabled on the upstream interface. Defaults to yes. `Assign=` Takes a boolean. Specifies whether to add an address from the delegated prefixes which are received from the WAN interface by the DHCPv6 Prefix Delegation. When true (on LAN interface), the EUI-64 algorithm will be used by default to form an interface identifier from the delegated prefixes. See also `Token=` setting below. Defaults to yes. `Token=` Specifies an optional address generation mode for assigning an address in each delegated prefix. This accepts the same syntax as `Token=` in the \[IPv6AcceptRA\] section. If `Assign=` is set to false, then this setting will be ignored. Defaults to unset, which means the EUI-64 algorithm will be used. `ManageTemporaryAddress=` As in the \[Address\] section, but defaults to true. `RouteMetric=` The metric of the route to the delegated prefix subnet. Takes an unsigned integer in the range 0…4294967295. When set to 0, the kernel's default value is used. Defaults to 256. `NetLabel=` This applies the NetLabel for the addresses received with DHCP, like `NetLabel=` in \[Address\] section applies it to statically configured addresses. See `NetLabel=` in \[Address\] section for more details. `NFTSet=` This applies the NFT set for the network configuration received with DHCP, like `NFTSet=` in \[Address\] section applies it to static configuration. See `NFTSet=` in \[Address\] section for more details. For `address` or `prefix` source types, the type of the element used in the NFT filter must be `ipv6_addr`. # \[IPv6AcceptRA\] Section Options The \[IPv6AcceptRA\] section configures the IPv6 Router Advertisement (RA) client, if it is enabled with the `IPv6AcceptRA=` setting described above: `UseRedirect=` When true (the default), Redirect message sent by the current first-hop router will be accepted, and routes to redirected nodes will be configured. `Token=` Specifies an optional address generation mode for the Stateless Address Autoconfiguration (SLAAC). The following values are supported: `eui64` The EUI-64 algorithm will be used to generate an address for that prefix. Only supported by Ethernet or InfiniBand interfaces. `static:ADDRESS` An IPv6 address must be specified after a colon (`:`), and the lower bits of the supplied address are combined with the upper bits of a prefix received in a Router Advertisement (RA) message to form a complete address. Note that if multiple prefixes are received in an RA message, or in multiple RA messages, addresses will be formed from each of them using the supplied address. This mode implements SLAAC but uses a static interface identifier instead of an identifier generated by using the EUI-64 algorithm. Because the interface identifier is static, if Duplicate Address Detection detects that the computed address is a duplicate (in use by another node on the link), then this mode will fail to provide an address for that prefix. If an IPv6 address without `static` is specified, then `static` mode is assumed. `prefixstable[:ADDRESS][,UUID]` The algorithm specified in [RFC 7217](https://tools.ietf.org/html/rfc7217) will be used to generate interface identifiers. This mode can optionally take an IPv6 address separated with a colon (`:`). If an IPv6 address is specified, then an interface identifier is generated only when a prefix received in an RA message matches the supplied address. This mode can also optionally take a non-null UUID in the format which `sd_id128_from_string()` accepts, e.g. `86b123b969ba4b7eb8b3d8605123525a` or `86b123b9-69ba-4b7e-b8b3-d8605123525a`. If a UUID is specified, the value is used as the secret key to generate interface identifiers. If not specified, then an application specific ID generated with the system's machine-ID will be used as the secret key. See `sd-id128(3)`, `sd_id128_from_string(3)`, and `sd_id128_get_machine(3)`. Note that the `prefixstable` algorithm uses both the interface name and MAC address as input to the hash to compute the interface identifier, so if either of those are changed the resulting interface identifier (and address) will be changed, even if the prefix received in the RA message has not been changed. If no address generation mode is specified (which is the default), or a received prefix does not match any of the addresses provided in `prefixstable` mode, then the EUI-64 algorithm will be used for Ethernet or InfiniBand interfaces, otherwise `prefixstable` will be used to form an interface identifier for that prefix. This setting can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. Examples: Token=eui64 Token=::1a:2b:3c:4d Token=static:::1a:2b:3c:4d Token=prefixstable Token=prefixstable:2002:da8:1:: `UseDNS=` When true (the default), the DNS servers received in the Router Advertisement will be used. This corresponds to the `nameserver` option in `resolv.conf(5)`. `UseDNR=` When true, the DNR servers received in the Router Advertisement will be used. Defaults to the value of `UseDNS=`. `UseDomains=` Takes a boolean, or the special value `route`. When true, the domain name received via IPv6 Router Advertisement (RA) will be used as DNS search domain over this link, similarly to the effect of the `Domains=` setting. If set to `route`, the domain name received via IPv6 RA will be used for routing DNS queries only, but not for searching, similarly to the effect of the `Domains=` setting when the argument is prefixed with `~`. Defaults to false. It is recommended to enable this option only on trusted networks, as setting this affects resolution of all hostnames, in particular of single-label names. It is generally safer to use the supplied domain only as routing domain, rather than as search domain, in order to not have it affect local resolution of single-label names. When set to true, this setting corresponds to the `domain` option in `resolv.conf(5)`. `RouteTable=num` The table identifier for the routes received in the Router Advertisement. Takes one of predefined names `default`, `main`, and `local`, and names defined in `RouteTable=` in `networkd.conf(5)`, or a number between 1…4294967295. When used in combination with `VRF=`, the VRF's routing table is used when this parameter is not specified. `RouteMetric=` Set the routing metric for the routes received in the Router Advertisement. Takes an unsigned integer in the range 0…4294967295, or three unsigned integer separated with `:`, in that case the first one is used when the router preference is high, the second is for medium preference, and the last is for low preference (`high:medium:low`). Defaults to `512:1024:2048`. `QuickAck=` Takes a boolean. When true, the TCP quick ACK mode is enabled for the routes configured by the received RAs. When unset, the kernel's default will be used. `UseMTU=` Takes a boolean. When true, the MTU received in the Router Advertisement will be used. Defaults to true. `UseHopLimit=` Takes a boolean. When true, the hop limit received in the Router Advertisement will be set to routes configured based on the advertisement. See also `IPv6HopLimit=`. Defaults to true. `UseReachableTime=` Takes a boolean. When true, the reachable time received in the Router Advertisement will be set on the interface receiving the advertisement. It is used as the base timespan of the validity of a neighbor entry. Defaults to true. `UseRetransmissionTime=` Takes a boolean. When true, the retransmission time received in the Router Advertisement will be set on the interface receiving the advertisement. It is used as the time between retransmissions of Neighbor Solicitation messages to a neighbor when resolving the address or when probing the reachability of a neighbor. Defaults to true. `UseGateway=` When true (the default), the router address will be configured as the default gateway. `UseRoutePrefix=` When true (the default), the routes corresponding to the route prefixes received in the Router Advertisement will be configured. `UseCaptivePortal=` When true (the default), the captive portal received in the Router Advertisement will be recorded and made available to client programs and displayed in the `networkctl(1)` status output per-link. `UsePREF64=` When true, the IPv6 PREF64 (or NAT64) prefixes received in the Router Advertisement will be recorded and made available to client programs and displayed in the `networkctl(1)` status output per-link. See [RFC 8781](https://tools.ietf.org/html/rfc8781). Defaults to false. `UseAutonomousPrefix=` When true (the default), the autonomous prefix received in the Router Advertisement will be used and take precedence over any statically configured ones. `UseOnLinkPrefix=` When true (the default), the onlink prefix received in the Router Advertisement will be used and takes precedence over any statically configured ones. `RouterDenyList=` A whitespace-separated list of IPv6 router addresses. Each address can optionally take a prefix length after `/`. Any information advertised by the listed router is ignored. `RouterAllowList=` A whitespace-separated list of IPv6 router addresses. Each address can optionally take a prefix length after `/`. Only information advertised by the listed router is accepted. Note that if `RouterAllowList=` is configured then `RouterDenyList=` is ignored. `PrefixDenyList=` A whitespace-separated list of IPv6 prefixes. Each prefix can optionally take its prefix length after `/`. IPv6 prefixes supplied via router advertisements in the list are ignored. `PrefixAllowList=` A whitespace-separated list of IPv6 prefixes. Each prefix can optionally take its prefix length after `/`. IPv6 prefixes supplied via router advertisements in the list are allowed. Note that if `PrefixAllowList=` is configured then `PrefixDenyList=` is ignored. `RouteDenyList=` A whitespace-separated list of IPv6 route prefixes. Each prefix can optionally take its prefix length after `/`. IPv6 route prefixes supplied via router advertisements in the list are ignored. `RouteAllowList=` A whitespace-separated list of IPv6 route prefixes. Each prefix can optionally take its prefix length after `/`. IPv6 route prefixes supplied via router advertisements in the list are allowed. Note that if `RouteAllowList=` is configured then `RouteDenyList=` is ignored. `DHCPv6Client=` Takes a boolean, or the special value `always`. When true, the DHCPv6 client will be started in `solicit` mode if the RA has the `managed` flag or `information-request` mode if the RA lacks the `managed` flag but has the `other configuration` flag. If set to `always`, the DHCPv6 client will be started in `solicit` mode when an RA is received, even if neither the `managed` nor the `other configuration` flag is set in the RA. This will be ignored when `WithoutRA=` in the \[DHCPv6\] section is enabled, or `UplinkInterface=:self` in the \[DHCPPrefixDelegation\] section is specified. Defaults to true. `NetLabel=` This applies the NetLabel for the addresses received with RA, like `NetLabel=` in \[Address\] section applies it to statically configured addresses. See `NetLabel=` in \[Address\] section for more details. `NFTSet=` This applies the NFT set for the network configuration received with RA, like `NFTSet=` in \[Address\] section applies it to static configuration. See `NFTSet=` in \[Address\] section for more details. For `address` or `prefix` source types, the type of the element used in the NFT filter must be `ipv6_addr`. # \[DHCPRelay\] Section Options The \[DHCPRelay\] section contains per-interface settings for the DHCP relay agent. The settings in this section are only used when `DHCPRelay=` in the \[Network\] section is configured. `AgentAddress=` Takes an IPv4 address. The specified address is used as the source IP address of packets forwarded to the upstream DHCP server. The address may also be used for the Server Identifier Override sub-option and the Link Selection sub-option in the Relay Agent Information option appended to DHCP messages forwarded to the upstream DHCP server. This setting applies to both upstream and downstream interfaces. Defaults to unset. If unset, a statically configured IPv4 address in the .network file is selected automatically. When multiple static IPv4 addresses are configured, it is recommended to specify this setting explicitly. `GatewayAddress=` Takes an IPv4 address. The specified address is set to the `giaddr` field of the DHCP message header when the DHCP message is forwarded to the upstream DHCP server. This is used only when `DHCPRelay=downstream`, and ignored otherwise. Defaults to unset, and the same address specified with `AgentAddress=` will be used. `CircuitId=` Specifies the circuit ID of the downstream interface. This is set as the Circuit ID sub-option in the Relay Agent Information option in the forwarded DHCP message. Takes a data type and data separated with a colon (`type:value`). The type takes one of `uint8`, `uint16`, `uint32`, `ipv4address`, `ipv6address`, or `string`. Special characters in the data string may be escaped using [C-style escapes](https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences). This is used only when `DHCPRelay=downstream`, and ignored otherwise. If unset, the name of the interface will be used. `VirtualSubnetSelection=` Specifies a unique identifier used by the DHCP server to select the downstream subnet independently of giaddr. This value is used as the Virtual Subnet Selection sub-option in the Relay Agent Information option in the forwarded DHCP message. Takes a value in the same format as `CircuitId=`. This is used only when `DHCPRelay=downstream`, and ignored otherwise. Defaults to unset, and the sub-option is not set. `ExtraOption=` Specifies an extra sub-option in the Relay Agent Information option, which is appended to DHCP messages forwarded to the upstream DHCP server. Takes a sub-option code, data type, and data separated with a colon (`code:type:value`). The code is an integer in 1…254. See `CircuitId=` in the above for the acceptable type and data. This setting can be specified multiple times. When an empty string is specified, all previous assignments are cleared. This is used only when `DHCPRelay=downstream`, and ignored otherwise. Defaults to unset, and no extra sub-option will be appended. `InterfacePriority=` Specifies the priority of the upstream interface. Takes an integer value. When the host has multiple upstream interfaces, the upstream interface with the highest (largest) priority will be used for forwarding DHCP messages to the upstream DHCP server. When multiple interfaces have the same priority, which interface is used is unspecified. This is used only when `DHCPRelay=upstream`, and ignored otherwise. Defaults to zero. # \[DHCPServer\] Section Options The \[DHCPServer\] section contains settings for the DHCP server, if enabled via the `DHCPServer=` option described above: `ServerAddress=` Specifies the server address for the DHCP server. Takes an IPv4 address with prefix length separated with a slash, e.g. `192.168.0.1/24`. Defaults to unset, and one of static IPv4 addresses configured in \[Network\] or \[Address\] section will be automatically selected. This setting may be useful when the interface on which the DHCP server is running has multiple static IPv4 addresses. This implies `Address=` in \[Network\] or \[Address\] section with the same address and prefix length. That is, [Network] DHCPServer=yes Address=192.168.0.1/24 Address=192.168.0.2/24 [DHCPServer] ServerAddress=192.168.0.1/24 or [Network] DHCPServer=yes [Address] Address=192.168.0.1/24 [Address] Address=192.168.0.2/24 [DHCPServer] ServerAddress=192.168.0.1/24 are equivalent to the following: [Network] DHCPServer=yes Address=192.168.0.2/24 [DHCPServer] ServerAddress=192.168.0.1/24 Since version 255, like the `Address=` setting in \[Network\] or \[Address\] section, this also supports a null address, e.g. `0.0.0.0/24`, and an unused address will be automatically selected. For more details about the automatic address selection, see `Address=` setting in \[Network\] section in the above. `PoolOffset=`; `PoolSize=` Configures the pool of addresses to hand out. The pool is a contiguous sequence of IP addresses in the subnet configured for the server address, which does not include the subnet nor the broadcast address. `PoolOffset=` takes the offset of the pool from the start of subnet, or zero to use the default value. `PoolSize=` takes the number of IP addresses in the pool or zero to use the default value. By default, the pool starts at the first address after the subnet address and takes up the rest of the subnet, excluding the broadcast address. If the pool includes the server address (the default), this is reserved and not handed out to clients. `DefaultLeaseTimeSec=`; `MaxLeaseTimeSec=` Control the default and maximum DHCP lease time to pass to clients. These settings take time values in seconds or another common time unit, depending on the suffix. The default lease time is used for clients that did not ask for a specific lease time. If a client asks for a lease time longer than the maximum lease time, it is automatically shortened to the specified time. The default lease time defaults to 1h, the maximum lease time to 12h. Shorter lease times are beneficial if the configuration data in DHCP leases changes frequently and clients shall learn the new settings with shorter latencies. Longer lease times reduce the generated DHCP network traffic. `UplinkInterface=` Specifies the name or the index of the uplink interface, or one of the special values `:none` and `:auto`. When emitting DNS, NTP, or SIP servers is enabled but no servers are specified, the servers configured in the uplink interface will be emitted. When `:auto`, the link which has a default gateway with the highest priority will be automatically selected. When `:none`, no uplink interface will be selected. Defaults to `:auto`. `EmitDNS=`; `DNS=` `EmitDNS=` takes a boolean. Configures whether the DHCP leases handed out to clients shall contain DNS server information. Defaults to `yes`. The DNS servers to pass to clients may be configured with the `DNS=` option, which takes a list of IPv4 addresses, or special value `_server_address` which will be converted to the address used by the DHCP server. If the `EmitDNS=` option is enabled but no servers configured, the servers are automatically propagated from an "uplink" interface that has appropriate servers set. The "uplink" interface is determined by the default route of the system with the highest priority. Note that this information is acquired at the time the lease is handed out, and does not take uplink interfaces into account that acquire DNS server information at a later point. If no suitable uplink interface is found the DNS server data from `/etc/resolv.conf` is used. Also, note that the leases are not refreshed if the uplink network configuration changes. To ensure clients regularly acquire the most current uplink DNS server information, it is thus advisable to shorten the DHCP lease time via `MaxLeaseTimeSec=` described above. This setting can be specified multiple times. If an empty string is specified, then all DNS servers specified earlier are cleared. `EmitNTP=`; `NTP=`; `EmitSIP=`; `SIP=`; `EmitPOP3=`; `POP3=`; `EmitSMTP=`; `SMTP=`; `EmitLPR=`; `LPR=` Similar to the `EmitDNS=` and `DNS=` settings described above, these settings configure whether and what server information for the indicate protocol shall be emitted as part of the DHCP lease. The same syntax, propagation semantics and defaults apply as for `EmitDNS=` and `DNS=`. `EmitRouter=`; `Router=` The `EmitRouter=` setting takes a boolean value, and configures whether the DHCP lease should contain the router option. The `Router=` setting takes an IPv4 address, and configures the router address to be emitted. When the `Router=` setting is not specified, then the server address will be used for the router option. When the `EmitRouter=` setting is disabled, the `Router=` setting will be ignored. The `EmitRouter=` setting defaults to true, and the `Router=` setting defaults to unset. `EmitTimezone=`; `Timezone=` Takes a boolean. Configures whether the DHCP leases handed out to clients shall contain timezone information. Defaults to `yes`. The `Timezone=` setting takes a timezone string (such as `Europe/Berlin` or `UTC`) to pass to clients. If no explicit timezone is set, the system timezone of the local host is propagated, as determined by the `/etc/localtime` symlink. `EmitDomain=` Takes a boolean. Configures whether the DHCP leases handed out to clients shall contain domain name information (DHCP option 15). Defaults to `no`. `Domain=` Takes a domain name (such as `example.com`) to pass to DHCP clients. This configures the DNS default domain for DHCP clients. When set, DHCP clients will use this as their DNS search domain. When `EmitDomain=yes` is set but `Domain=` is not configured, the domain name will be automatically derived from the system's fully qualified hostname. For example, if the system's hostname is `host.example.com`, the domain `example.com` will be sent to clients. If the system's hostname does not contain a domain part (e.g., hostname is just `host`), no domain name will be sent to DHCP clients. When empty or unset, defaults to no domain name. `BootServerAddress=` Takes an IPv4 address of the boot server used by e.g. PXE boot systems. When specified, this address is sent in the `siaddr` field of the DHCP message header. See [RFC 2131](https://www.rfc-editor.org/rfc/rfc2131.html) for more details. Defaults to unset. `BootServerName=` Takes a name of the boot server used by e.g. PXE boot systems. When specified, this name is sent in the DHCP option 66 ("TFTP server name"). See [RFC 2132](https://www.rfc-editor.org/rfc/rfc2132.html) for more details. Defaults to unset. Note that typically setting one of `BootServerName=` or `BootServerAddress=` is sufficient, but both can be set too, if desired. `BootFilename=` Takes a path or URL to a file loaded by e.g. a PXE boot loader. When specified, this path is sent in the DHCP option 67 ("Bootfile name"). See [RFC 2132](https://www.rfc-editor.org/rfc/rfc2132.html) for more details. Defaults to unset. `IPv6OnlyPreferredSec=` Takes a timespan. Controls the [RFC 8925](https://tools.ietf.org/html/rfc8925) IPv6-Only Preferred option. Specifies the DHCPv4 option to indicate that a host supports an IPv6-only mode and is willing to forgo obtaining an IPv4 address if the network provides IPv6 connectivity. Defaults to unset, and not send the option. The minimum allowed value is 300 seconds. `SendOption=` Send a raw option with value via DHCPv4 server. Takes a DHCP option number, data type and data (`option:type:value`). The option number is an integer in the range 1…254. The type takes one of `uint8`, `uint16`, `uint32`, `ipv4address`, `ipv6address`, or `string`. Special characters in the data string may be escaped using [C-style escapes](https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences). This setting can be specified multiple times. If an empty string is specified, then all options specified earlier are cleared. Defaults to unset. `SendVendorOption=` Send a vendor option with value via DHCPv4 server. Takes a DHCP option number, data type and data (`option:type:value`). The option number is an integer in the range 1…254. The type takes one of `uint8`, `uint16`, `uint32`, `ipv4address`, or `string`. Special characters in the data string may be escaped using [C-style escapes](https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences). This setting can be specified multiple times. If an empty string is specified, then all options specified earlier are cleared. Defaults to unset. `RapidCommit=` Takes a boolean. When true, the server supports [RFC 4039](https://datatracker.ietf.org/doc/html/rfc4039). When a client sends a DHCPDISCOVER message with the Rapid Commit option to the server, then the server will reply with a DHCPACK message to the client, instead of DHCPOFFER. Defaults to true. `PersistLeases=` Takes a boolean or special value `runtime`. When `yes`, the DHCP server will load and save leases in the persistent storage. When `runtime`, the DHCP server will load and save leases in the runtime storage, hence bound leases will be lost when the runtime storage is cleared by e.g. by calling `systemctl clean systemd-networkd.service` or the system is rebooted. When `no`, the DHCP server will neither load nor save leases in the persistent storage, hence bound leases will be lost when the interface is reconfigured e.g. by `networkctl reconfigure`, or `systemd-networkd.service(8)` is restarted. Using `runtime` and `no` may cause address conflict on the network after the leases are lost. So, please take an extra care when disable this setting. When unspecified, the value specified in the same setting in `networkd.conf(5)`, which defaults to `yes`, will be used. `LocalLeaseDomain=` Takes a DNS domain name as argument. If specified, `systemd-networkd.service(8)` will integrate with `systemd-resolved.service(8)` and ensure that the hostnames associated with each handed out DHCP lease may be resolved to the IP addresses of the lease. The hostnames are suffixed with the specified domain name. Note that this purely about hostname resolution on the local system, i.e. from programs with access to the same `systemd-resolved` instances via D-Bus IPC, Varlink IPC, or the local DNS stub. # \[DHCPServerStaticLease\] Section Options The `[DHCPServerStaticLease]` section configures a static DHCP lease to assign a fixed IPv4 address to a specific device based on its MAC address or client identifier. This section can be specified multiple times. `MACAddress=` The hardware address of a device to match. This key is mandatory when `ClientIdentifier=` is `mac`, and ignored when it is `duid`. `ClientIdentifier=` Specifies how the client identifier (option 61) of a device to match is built, as in the \[DHCPv4\] section. Takes one of `mac` or `duid`. When `mac`, the client identifier is built from `MACAddress=`. As the server falls back to the hardware address of a device when no static lease matches the client identifier the device sends, such a lease matches the device whatever client identifier it sends. When `duid`, the client identifier is built from `IAID=` and the DUID specified by `DUIDType=` and `DUIDRawData=` (RFC 4361), and all of them must be specified. Such a lease matches only a device that sends exactly that client identifier. This is useful e.g. to tell apart hosts that share a hardware address, like ipvlan interfaces in L2 mode. Defaults to `mac`. `IAID=` The IAID of a device to match, a 32-bit unsigned integer, as in the \[DHCPv4\] section of the client. Used only when `ClientIdentifier=duid`. `DUIDType=`; `DUIDRawData=` The DUID of a device to match, as in the \[DHCPv4\] section of the client. See `networkd.conf(5)` for the format. As the DUID cannot be generated on the server side, both must be specified when `ClientIdentifier=duid`, and they are ignored otherwise. `Address=` The IPv4 address that should be assigned to the device that was matched with `MACAddress=` or `ClientIdentifier=`. This key is mandatory. `Hostname=` The hostname to send to the client in DHCP replies. This can be either a simple hostname (e.g., `mydevice`) or a fully qualified domain name (e.g., `mydevice.example.com`), following RFC 1123 naming conventions. Each label can be up to 63 characters, with a total maximum length of 253 characters for FQDNs. When this option is set, the DHCP server will include the hostname in DHCP replies (both OFFER and ACK) to the client with the matched MAC address or client identifier. The server automatically selects the appropriate DHCP option based on the hostname format: simple hostnames (single DNS label) are sent via option 12 (Host Name) per RFC 2132, while FQDNs with multiple labels are sent via option 81 (Client FQDN) per RFC 4702 using DNS wire format encoding. The configured hostname is sent unconditionally, any hostname requested by the client in its DHCP message is ignored. # \[IPv6SendRA\] Section Options The \[IPv6SendRA\] section contains settings for sending IPv6 Router Advertisements and whether to act as a router, if enabled via the `IPv6SendRA=` option described above. IPv6 network prefixes or routes are defined with one or more \[IPv6Prefix\] or \[IPv6RoutePrefix\] sections. `Managed=`; `OtherInformation=` Takes a boolean. Controls whether a DHCPv6 server is used to acquire IPv6 addresses on the network link when `Managed=` is set to `true` or if only additional network information can be obtained via DHCPv6 for the network link when `OtherInformation=` is set to `true`. Both settings default to `false`, which means that a DHCPv6 server is not being used. `RouterLifetimeSec=` Takes a timespan. Configures the IPv6 router lifetime in seconds. The value must be 0 seconds, or between 4 seconds and 9000 seconds. When set to 0, the host is not acting as a router. Defaults to 1800 seconds (30 minutes). `ReachableTimeSec=` Configures the time, used in the Neighbor Unreachability Detection algorithm, for which clients can assume a neighbor is reachable after having received a reachability confirmation. Takes a time span in the range 0…4294967295 ms. When 0, clients will handle it as if the value was not specified. Defaults to 0. `RetransmitSec=` Configures the time, used in the Neighbor Unreachability Detection algorithm, for which clients can use as retransmit time on address resolution and the Neighbor Unreachability Detection algorithm. Takes a time span in the range 0…4294967295 ms. When 0, clients will handle it as if the value wasn't specified. Defaults to 0. `RouterPreference=` Configures IPv6 router preference if `RouterLifetimeSec=` is non-zero. Valid values are `high`, `medium` and `low`, with `normal` and `default` added as synonyms for `medium` just to make configuration easier. See [RFC 4191](https://tools.ietf.org/html/rfc4191) for details. Defaults to `medium`. `HopLimit=` Configures hop limit. Takes an integer in the range 0…255. See also `IPv6HopLimit=`. `UplinkInterface=` Specifies the name or the index of the uplink interface, or one of the special values `:none` and `:auto`. When emitting DNS servers or search domains is enabled but no servers are specified, the servers configured in the uplink interface will be emitted. When `:auto`, the value specified to the same setting in the \[DHCPPrefixDelegation\] section will be used if `DHCPPrefixDelegation=` is enabled, otherwise the link which has a default gateway with the highest priority will be automatically selected. When `:none`, no uplink interface will be selected. Defaults to `:auto`. `EmitDNS=`; `DNS=` `DNS=` specifies a list of recursive DNS server IPv6 addresses that are distributed via Router Advertisement messages when `EmitDNS=` is true. `DNS=` also takes special value `_link_local`; in that case the IPv6 link-local address is distributed. If `DNS=` is empty, DNS servers are read from the \[Network\] section. If the \[Network\] section does not contain any DNS servers either, DNS servers from the uplink interface specified in `UplinkInterface=` will be used. When `EmitDNS=` is false, no DNS server information is sent in Router Advertisement messages. `EmitDNS=` defaults to true. `EmitDomains=`; `Domains=` A list of DNS search domains distributed via Router Advertisement messages when `EmitDomains=` is true. If `Domains=` is empty, DNS search domains are read from the \[Network\] section. If the \[Network\] section does not contain any DNS search domains either, DNS search domains from the uplink interface specified in `UplinkInterface=` will be used. When `EmitDomains=` is false, no DNS search domain information is sent in Router Advertisement messages. `EmitDomains=` defaults to true. `DNSLifetimeSec=` Lifetime in seconds for the DNS server addresses listed in `DNS=` and search domains listed in `Domains=`. Defaults to 3600 seconds (one hour). `HomeAgent=` Takes a boolean. Specifies that IPv6 router advertisements indicate to hosts that the router acts as a Home Agent and includes a Home Agent option. Defaults to false. See [RFC 6275](https://tools.ietf.org/html/rfc6275) for further details. `HomeAgentLifetimeSec=` Takes a timespan. Specifies the lifetime of the Home Agent. An integer, the default unit is seconds, in the range 1…65535. Defaults to the value set to `RouterLifetimeSec=`. `HomeAgentPreference=` Configures IPv6 Home Agent preference. Takes an integer in the range 0…65535. Defaults to 0. # \[IPv6Prefix\] Section Options One or more \[IPv6Prefix\] sections contain the IPv6 prefixes that are announced via Router Advertisements. See [RFC 4861](https://tools.ietf.org/html/rfc4861) for further details. `AddressAutoconfiguration=`; `OnLink=` Takes a boolean to specify whether IPv6 addresses can be autoconfigured with this prefix and whether the prefix can be used for onlink determination. Both settings default to `true` in order to ease configuration. `Prefix=` The IPv6 prefix that is to be distributed to hosts. Similarly to configuring static IPv6 addresses, the setting is configured as an IPv6 prefix and its prefix length, separated by a `/` character. Use multiple \[IPv6Prefix\] sections to configure multiple IPv6 prefixes since prefix lifetimes, address autoconfiguration and onlink status may differ from one prefix to another. `PreferredLifetimeSec=`; `ValidLifetimeSec=` Preferred and valid lifetimes for the prefix measured in seconds. `PreferredLifetimeSec=` defaults to 1800 seconds (30 minutes) and `ValidLifetimeSec=` defaults to 3600 seconds (one hour). `Assign=` Takes a boolean. When true, adds an address from the prefix. Default to false. `Token=` Specifies an optional address generation mode for assigning an address in each prefix. This accepts the same syntax as `Token=` in the \[IPv6AcceptRA\] section. If `Assign=` is set to false, then this setting will be ignored. Defaults to unset, which means the EUI-64 algorithm will be used. `RouteMetric=` The metric of the prefix route. Takes an unsigned integer in the range 0…4294967295. When unset or set to 0, the kernel's default value is used. This setting is ignored when `Assign=` is false. # \[IPv6RoutePrefix\] Section Options One or more \[IPv6RoutePrefix\] sections contain the IPv6 prefix routes that are announced via Router Advertisements. See [RFC 4191](https://tools.ietf.org/html/rfc4191) for further details. `Route=` The IPv6 route that is to be distributed to hosts. Similarly to configuring static IPv6 routes, the setting is configured as an IPv6 prefix routes and its prefix route length, separated by a `/` character. Use multiple \[IPv6RoutePrefix\] sections to configure multiple IPv6 prefix routes. `LifetimeSec=` Lifetime for the route prefix measured in seconds. `LifetimeSec=` defaults to 3600 seconds (one hour). `Preference=` Specifies the preference of the route option. Takes one of `high`, `medium`, or `low`. Defaults to `medium`. # \[IPv6PREF64Prefix\] Section Options One or more \[IPv6PREF64Prefix\] sections contain the IPv6 PREF64 (or NAT64) prefixes that are announced via Router Advertisements. See [RFC 8781](https://tools.ietf.org/html/rfc8781) for further details. `Prefix=` The IPv6 PREF64 (or NAT64) prefix that is to be distributed to hosts. The setting holds an IPv6 prefix that should be set up for NAT64 translation (PLAT) to allow 464XLAT on the network segment. Use multiple \[IPv6PREF64Prefix\] sections to configure multiple IPv6 prefixes since prefix lifetime may differ from one prefix to another. The prefix is an address with a prefix length, separated by a slash `/` character. Valid NAT64 prefix length are 96, 64, 56, 48, 40, and 32 bits. `LifetimeSec=` Lifetime for the prefix measured in seconds. Should be greater than or equal to `RouterLifetimeSec=`. `LifetimeSec=` defaults to 1800 seconds. # \[Bridge\] Section Options The \[Bridge\] section accepts the following keys: `UnicastFlood=` Takes a boolean. Controls whether the bridge should flood traffic for which an FDB entry is missing and the destination is unknown through this port. When unset, the kernel's default will be used. `MulticastFlood=` Takes a boolean. Controls whether the bridge should flood traffic for which an MDB entry is missing and the destination is unknown through this port. When unset, the kernel's default will be used. `MulticastToUnicast=` Takes a boolean. Multicast to unicast works on top of the multicast snooping feature of the bridge. Which means unicast copies are only delivered to hosts which are interested in it. When unset, the kernel's default will be used. `NeighborSuppression=` Takes a boolean. Configures whether ARP and ND neighbor suppression is enabled for this port. When unset, the kernel's default will be used. `Learning=` Takes a boolean. Configures whether MAC address learning is enabled for this port. When unset, the kernel's default will be used. `HairPin=` Takes a boolean. Configures whether traffic may be sent back out of the port on which it was received. When this flag is false, then the bridge will not forward traffic back out of the receiving port. When unset, the kernel's default will be used. `Isolated=` Takes a boolean. Configures whether this port is isolated or not. Within a bridge, isolated ports can only communicate with non-isolated ports. When set to true, this port can only communicate with other ports whose Isolated setting is false. When set to false, this port can communicate with any other ports. When unset, the kernel's default will be used. `UseBPDU=` Takes a boolean. Configures whether STP Bridge Protocol Data Units will be processed by the bridge port. When unset, the kernel's default will be used. `FastLeave=` Takes a boolean. This flag allows the bridge to immediately stop multicast traffic on a port that receives an IGMP Leave message. It is only used with IGMP snooping if enabled on the bridge. When unset, the kernel's default will be used. `AllowPortToBeRoot=` Takes a boolean. Configures whether a given port is allowed to become a root port. Only used when STP is enabled on the bridge. When unset, the kernel's default will be used. `ProxyARP=` Takes a boolean. Configures whether proxy ARP to be enabled on this port. When unset, the kernel's default will be used. `ProxyARPWiFi=` Takes a boolean. Configures whether proxy ARP to be enabled on this port which meets extended requirements by IEEE 802.11 and Hotspot 2.0 specifications. When unset, the kernel's default will be used. `MulticastRouter=` Configures this port for having multicast routers attached. A port with a multicast router will receive all multicast traffic. Takes one of `no` to disable multicast routers on this port, `query` to let the system detect the presence of routers, `permanent` to permanently enable multicast traffic forwarding on this port, or `temporary` to enable multicast routers temporarily on this port, not depending on incoming queries. When unset, the kernel's default will be used. `Cost=` Sets the "cost" of sending packets of this interface. Each port in a bridge may have a different speed and the cost is used to decide which link to use. Faster interfaces should have lower costs. It is an integer value between 1 and 65535. `Priority=` Sets the "priority" of sending packets on this interface. Each port in a bridge may have a different priority which is used to decide which link to use. Lower value means higher priority. It is an integer value between 0 to 63. `systemd-networkd` does not set any default, meaning the kernel default value of 32 is used. `Locked=`; `MACAuthenticationBypass=` Takes a boolean. Configures whether the port is "locked" and does not allow traffic forwarded until fully authenticated, e.g. via 802.1x. When unset, the kernel's default will be used. Takes a boolean. Configures whether a locked port has "MAC Authentication Bypass" enabled and creates newly learned fdb entries in a "locked" state. User space can authenticate these entries by clearing the locked flag. Requires Learning to be enabled. When unset, the kernel's default will be used. `VLANTunnel=` Takes a boolean. Configures whether vlan tunnel mode is to be enabled on this port. When unset, the kernel's default will be used. # \[BridgeFDB\] Section Options The \[BridgeFDB\] section manages the forwarding database table of a port and accepts the following keys. Specify several \[BridgeFDB\] sections to configure several static MAC table entries. `MACAddress=` As in the \[Network\] section. This key is mandatory. `Destination=` Takes an IP address of the destination VXLAN tunnel endpoint. `VLANId=` The VLAN ID for the new static MAC table entry. If omitted, no VLAN ID information is appended to the new static MAC table entry. `VNI=` The VXLAN Network Identifier (or VXLAN Segment ID) to use to connect to the remote VXLAN tunnel endpoint. Takes a number in the range 1…16777215. Defaults to unset. `AssociatedWith=` Specifies where the address is associated with. Takes one of `use`, `self`, `master` or `router`. `use` means the address is in use. User space can use this option to indicate to the kernel that the fdb entry is in use. `self` means the address is associated with the port drivers fdb. Usually hardware. `master` means the address is associated with master devices fdb. `router` means the destination address is associated with a router. Note that it is valid if the referenced device is a VXLAN type device and has route shortcircuit enabled. Defaults to `self`. `OutgoingInterface=` Specifies the name or index of the outgoing interface for the VXLAN device driver to reach the remote VXLAN tunnel endpoint. Defaults to unset. # \[BridgeMDB\] Section Options The \[BridgeMDB\] section manages the multicast membership entries forwarding database table of a port and accepts the following keys. Specify several \[BridgeMDB\] sections to configure several permanent multicast membership entries. `MulticastGroupAddress=` Specifies the IPv4, IPv6, or L2 MAC multicast group address to add. This setting is mandatory. `VLANId=` The VLAN ID for the new entry. Valid ranges are 0 (no VLAN) to 4094. Optional, defaults to 0. # \[LLDP\] Section Options The \[LLDP\] section manages the Link Layer Discovery Protocol (LLDP) and accepts the following keys: `MUDURL=` When configured, the specified Manufacturer Usage Descriptions (MUD) URL will be sent in LLDP packets. The syntax and semantics are the same as for `MUDURL=` in the \[DHCPv4\] section described above. The MUD URLs received via LLDP packets are saved and can be read using the `sd_lldp_neighbor_get_mud_url()` function. # \[CAN\] Section Options The \[CAN\] section manages the Controller Area Network (CAN bus) and accepts the following keys: `BitRate=` The bitrate of CAN device in bits per second. The usual SI prefixes (K, M) with the base of 1000 can be used here. Takes a number in the range 1…4294967295. `SamplePoint=` Optional sample point in percent with one decimal (e.g. `75%`, `87.5%`) or permille (e.g. `875‰`). This will be ignored when `BitRate=` is unspecified. `TimeQuantaNSec=`; `PropagationSegment=`; `PhaseBufferSegment1=`; `PhaseBufferSegment2=`; `SyncJumpWidth=` Specifies the time quanta, propagation segment, phase buffer segment 1 and 2, and the synchronization jump width, which allow one to define the CAN bit-timing in a hardware independent format as proposed by the Bosch CAN 2.0 Specification. `TimeQuantaNSec=` takes a timespan in nanoseconds. `PropagationSegment=`, `PhaseBufferSegment1=`, `PhaseBufferSegment2=`, and `SyncJumpWidth=` take number of time quantum specified in `TimeQuantaNSec=` and must be an unsigned integer in the range 0…4294967295. These settings except for `SyncJumpWidth=` will be ignored when `BitRate=` is specified. `DataBitRate=`; `DataSamplePoint=` The bitrate and sample point for the data phase, if CAN-FD is used. These settings are analogous to the `BitRate=` and `SamplePoint=` keys. `DataTimeQuantaNSec=`; `DataPropagationSegment=`; `DataPhaseBufferSegment1=`; `DataPhaseBufferSegment2=`; `DataSyncJumpWidth=` Specifies the time quanta, propagation segment, phase buffer segment 1 and 2, and the synchronization jump width for the data phase, if CAN-FD is used. These settings are analogous to the `TimeQuantaNSec=` or related settings. `FDMode=` Takes a boolean. When `yes`, CAN-FD mode is enabled for the interface. Note, that a bitrate and optional sample point should also be set for the CAN-FD data phase using the `DataBitRate=` and `DataSamplePoint=` keys, or `DataTimeQuanta=` and related settings. `FDNonISO=` Takes a boolean. When `yes`, non-ISO CAN-FD mode is enabled for the interface. When unset, the kernel's default will be used. `RestartSec=` Automatic restart delay time. If set to a non-zero value, a restart of the CAN controller will be triggered automatically in case of a bus-off condition after the specified delay time. Subsecond delays can be specified using decimals (e.g. `0.1s`) or a `ms` or `us` postfix. Using `infinity` or `0` will turn the automatic restart off. By default, automatic restart is disabled. `Termination=` Takes a boolean or a termination resistor value in ohm in the range 0…65535. When `yes`, the termination resistor is set to 120 ohm. When `no` or `0` is set, the termination resistor is disabled. When unset, the kernel's default will be used. `TripleSampling=` Takes a boolean. When `yes`, three samples (instead of one) are used to determine the value of a received bit by majority rule. When unset, the kernel's default will be used. `BusErrorReporting=` Takes a boolean. When `yes`, reporting of CAN bus errors is activated (those include single bit, frame format, and bit stuffing errors, unable to send dominant bit, unable to send recessive bit, bus overload, active error announcement, error occurred on transmission). When unset, the kernel's default will be used. Note: in case of a CAN bus with a single CAN device, sending a CAN frame may result in a huge number of CAN bus errors. `ListenOnly=` Takes a boolean. When `yes`, listen-only mode is enabled. When the interface is in listen-only mode, the interface neither transmit CAN frames nor send ACK bit. Listen-only mode is important to debug CAN networks without interfering with the communication or acknowledge the CAN frame. When unset, the kernel's default will be used. `Loopback=` Takes a boolean. When `yes`, loopback mode is enabled. When the loopback mode is enabled, the interface treats messages transmitted by itself as received messages. The loopback mode is important to debug CAN networks. When unset, the kernel's default will be used. `OneShot=` Takes a boolean. When `yes`, one-shot mode is enabled. When unset, the kernel's default will be used. `PresumeACK=` Takes a boolean. When `yes`, the interface will ignore missing CAN ACKs. When unset, the kernel's default will be used. `ClassicDataLengthCode=` Takes a boolean. When `yes`, the interface will handle the 4bit data length code (DLC). When unset, the kernel's default will be used. # \[IPoIB\] Section Options The \[IPoIB\] section manages the IP over Infiniband and accepts the following keys: # \[QDisc\] Section Options The \[QDisc\] section manages the traffic control queueing discipline (qdisc). `Parent=` Specifies the parent Queueing Discipline (qdisc). Takes one of `clsact` or `ingress`. This is mandatory. # \[NetworkEmulator\] Section Options The \[NetworkEmulator\] section manages the queueing discipline (qdisc) of the network emulator. It can be used to configure the kernel packet scheduler and simulate packet delay and loss for UDP or TCP applications, or limit the bandwidth usage of a particular service to simulate internet connections. `DelaySec=` Specifies the fixed amount of delay to be added to all packets going out of the interface. Defaults to unset. `DelayJitterSec=` Specifies the chosen delay to be added to the packets outgoing to the network interface. Defaults to unset. `PacketLimit=` Specifies the maximum number of packets the qdisc may hold queued at a time. An unsigned integer in the range 0…4294967294. Defaults to 1000. `LossRate=` Specifies an independent loss probability to be added to the packets outgoing from the network interface. Takes a percentage value, suffixed with "%". Defaults to unset. `DuplicateRate=` Specifies that the chosen percent of packets is duplicated before queuing them. Takes a percentage value, suffixed with "%". Defaults to unset. # \[TokenBucketFilter\] Section Options The \[TokenBucketFilter\] section manages the queueing discipline (qdisc) of token bucket filter (tbf). `LatencySec=` Specifies the latency parameter, which specifies the maximum amount of time a packet can sit in the Token Bucket Filter (TBF). Defaults to unset. `LimitBytes=` Takes the number of bytes that can be queued waiting for tokens to become available. When the size is suffixed with K, M, or G, it is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to unset. `BurstBytes=` Specifies the size of the bucket. This is the maximum amount of bytes that tokens can be available for instantaneous transfer. When the size is suffixed with K, M, or G, it is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to unset. `Rate=` Specifies the device specific bandwidth. When suffixed with K, M, or G, the specified bandwidth is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000. Defaults to unset. `MPUBytes=` The Minimum Packet Unit (MPU) determines the minimal token usage (specified in bytes) for a packet. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to zero. `PeakRate=` Takes the maximum depletion rate of the bucket. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000. Defaults to unset. `MTUBytes=` Specifies the size of the peakrate bucket. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to unset. # \[PIE\] Section Options The \[PIE\] section manages the queueing discipline (qdisc) of Proportional Integral controller-Enhanced (PIE). `PacketLimit=` Specifies the hard limit on the queue size in number of packets. When this limit is reached, incoming packets are dropped. An unsigned integer in the range 1…4294967294. Defaults to unset and kernel's default is used. # \[FlowQueuePIE\] Section Options The `[FlowQueuePIE]` section manages the queueing discipline (qdisc) of Flow Queue Proportional Integral controller-Enhanced (fq_pie). `PacketLimit=` Specifies the hard limit on the queue size in number of packets. When this limit is reached, incoming packets are dropped. An unsigned integer ranges 1 to 4294967294. Defaults to unset and kernel's default is used. # \[StochasticFairBlue\] Section Options The \[StochasticFairBlue\] section manages the queueing discipline (qdisc) of stochastic fair blue (sfb). `PacketLimit=` Specifies the hard limit on the queue size in number of packets. When this limit is reached, incoming packets are dropped. An unsigned integer in the range 0…4294967294. Defaults to unset and kernel's default is used. # \[StochasticFairnessQueueing\] Section Options The \[StochasticFairnessQueueing\] section manages the queueing discipline (qdisc) of stochastic fairness queueing (sfq). `PerturbPeriodSec=` Specifies the interval in seconds for queue algorithm perturbation. Defaults to unset. # \[BFIFO\] Section Options The \[BFIFO\] section manages the queueing discipline (qdisc) of Byte limited Packet First In First Out (bfifo). `LimitBytes=` Specifies the hard limit in bytes on the FIFO buffer size. The size limit prevents overflow in case the kernel is unable to dequeue packets as quickly as it receives them. When this limit is reached, incoming packets are dropped. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to unset and kernel default is used. # \[PFIFO\] Section Options The \[PFIFO\] section manages the queueing discipline (qdisc) of Packet First In First Out (pfifo). `PacketLimit=` Specifies the hard limit on the number of packets in the FIFO queue. The size limit prevents overflow in case the kernel is unable to dequeue packets as quickly as it receives them. When this limit is reached, incoming packets are dropped. An unsigned integer in the range 0…4294967294. Defaults to unset and kernel's default is used. # \[PFIFOHeadDrop\] Section Options The \[PFIFOHeadDrop\] section manages the queueing discipline (qdisc) of Packet First In First Out Head Drop (pfifo_head_drop). `PacketLimit=` As in \[PFIFO\] section. # \[PFIFOFast\] Section Options The \[PFIFOFast\] section manages the queueing discipline (qdisc) of Packet First In First Out Fast (pfifo_fast). # \[CAKE\] Section Options The \[CAKE\] section manages the queueing discipline (qdisc) of Common Applications Kept Enhanced (CAKE). `Bandwidth=` Specifies the shaper bandwidth. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000. Defaults to unset and kernel's default is used. `AutoRateIngress=` Takes a boolean value. Enables automatic capacity estimation based on traffic arriving at this qdisc. This is most likely to be useful with cellular links, which tend to change quality randomly. If this setting is enabled, the `Bandwidth=` setting is used as an initial estimate. Defaults to unset, and the kernel's default is used. `OverheadBytes=` Specifies that bytes to be addeded to the size of each packet. Bytes may be negative. Takes an integer in the range -64…256. Defaults to unset and kernel's default is used. `MPUBytes=` Rounds each packet (including overhead) up to the specified bytes. Takes an integer in the range 1…256. Defaults to unset and kernel's default is used. `CompensationMode=` Takes one of `none`, `atm`, or `ptm`. Specifies the compensation mode for overhead calculation. When `none`, no compensation is taken into account. When `atm`, enables the compensation for ATM cell framing, which is normally found on ADSL links. When `ptm`, enables the compensation for PTM encoding, which is normally found on VDSL2 links and uses a 64b/65b encoding scheme. Defaults to unset and the kernel's default is used. `UseRawPacketSize=` Takes a boolean value. When true, the packet size reported by the Linux kernel will be used, instead of the underlying IP packet size. Defaults to unset, and the kernel's default is used. `FlowIsolationMode=` CAKE places packets from different flows into different queues, then packets from each queue are delivered fairly. This specifies whether the fairness is based on source address, destination address, individual flows, or any combination of those. The available values are: `none` The flow isolation is disabled, and all traffic passes through a single queue. `src-host` Flows are defined only by source address. Equivalent to the `srchost` option for `tc qdisc` command. See also `tc-cake(8)`. `dst-host` Flows are defined only by destination address. Equivalent to the `dsthost` option for `tc qdisc` command. See also `tc-cake(8)`. `hosts` Flows are defined by source-destination host pairs. Equivalent to the same option for `tc qdisc` command. See also `tc-cake(8)`. `flows` Flows are defined by the entire 5-tuple of source address, destination address, transport protocol, source port and destination port. Equivalent to the same option for `tc qdisc` command. See also `tc-cake(8)`. `dual-src-host` Flows are defined by the 5-tuple (see `flows` in the above), and fairness is applied first over source addresses, then over individual flows. Equivalent to the `dual-srchost` option for `tc qdisc` command. See also `tc-cake(8)`. `dual-dst-host` Flows are defined by the 5-tuple (see `flows` in the above), and fairness is applied first over destination addresses, then over individual flows. Equivalent to the `dual-dsthost` option for `tc qdisc` command. See also `tc-cake(8)`. `triple` Flows are defined by the 5-tuple (see `flows`), and fairness is applied over source and destination addresses, and also over individual flows. Equivalent to the `triple-isolate` option for `tc qdisc` command. See also `tc-cake(8)`. Defaults to unset and the kernel's default is used. `NAT=` Takes a boolean value. When true, CAKE performs a NAT lookup before applying flow-isolation rules, to determine the true addresses and port numbers of the packet, to improve fairness between hosts inside the NAT. This has no practical effect when `FlowIsolationMode=` is `none` or `flows`, or if NAT is performed on a different host. Defaults to unset, and the kernel's default is used. `PriorityQueueingPreset=` CAKE divides traffic into `tins`, and each tin has its own independent set of flow-isolation queues, bandwidth threshold, and priority. This specifies the preset of tin profiles. The available values are: `besteffort` Disables priority queueing by placing all traffic in one tin. `precedence` Enables priority queueing based on the legacy interpretation of TOS `Precedence` field. Use of this preset on the modern Internet is firmly discouraged. `diffserv8` Enables priority queueing based on the Differentiated Service (`DiffServ`) field with eight tins: Background Traffic, High Throughput, Best Effort, Video Streaming, Low Latency Transactions, Interactive Shell, Minimum Latency, and Network Control. `diffserv4` Enables priority queueing based on the Differentiated Service (`DiffServ`) field with four tins: Background Traffic, Best Effort, Streaming Media, and Latency Sensitive. `diffserv3` Enables priority queueing based on the Differentiated Service (`DiffServ`) field with three tins: Background Traffic, Best Effort, and Latency Sensitive. Defaults to unset, and the kernel's default is used. `FirewallMark=` Takes an integer in the range 1…4294967295. When specified, firewall-mark-based overriding of CAKE's tin selection is enabled. Defaults to unset, and the kernel's default is used. `Wash=` Takes a boolean value. When true, CAKE clears the DSCP fields, except for ECN bits, of any packet passing through CAKE. Defaults to unset, and the kernel's default is used. `SplitGSO=` Takes a boolean value. When true, CAKE will split General Segmentation Offload (GSO) super-packets into their on-the-wire components and dequeue them individually. Defaults to unset, and the kernel's default is used. `RTTSec=` Specifies the RTT for the filter. Takes a timespan. Typical values are e.g. 100us for extremely high-performance 10GigE+ networks like datacentre, 1ms for non-WiFi LAN connections, 100ms for typical internet connections. Defaults to unset, and the kernel's default will be used. `AckFilter=` Takes a boolean value, or special value `aggressive`. If enabled, ACKs in each flow are queued and redundant ACKs to the upstream are dropped. If yes, the filter will always keep at least two redundant ACKs in the queue, while in `aggressive` mode, it will filter down to a single ACK. This may improve download throughput on links with very asymmetrical rate limits. Defaults to unset, and the kernel's default will be used. # \[ControlledDelay\] Section Options The \[ControlledDelay\] section manages the queueing discipline (qdisc) of controlled delay (CoDel). `PacketLimit=` Specifies the hard limit on the queue size in number of packets. When this limit is reached, incoming packets are dropped. An unsigned integer in the range 0…4294967294. Defaults to unset and kernel's default is used. `TargetSec=` Takes a timespan. Specifies the acceptable minimum standing/persistent queue delay. Defaults to unset and kernel's default is used. `IntervalSec=` Takes a timespan. This is used to ensure that the measured minimum delay does not become too stale. Defaults to unset and kernel's default is used. `ECN=` Takes a boolean. This can be used to mark packets instead of dropping them. Defaults to unset and kernel's default is used. `CEThresholdSec=` Takes a timespan. This sets a threshold above which all packets are marked with ECN Congestion Experienced (CE). Defaults to unset and kernel's default is used. # \[DeficitRoundRobinScheduler\] Section Options The \[DeficitRoundRobinScheduler\] section manages the queueing discipline (qdisc) of Deficit Round Robin Scheduler (DRR). # \[DeficitRoundRobinSchedulerClass\] Section Options The \[DeficitRoundRobinSchedulerClass\] section manages the traffic control class of Deficit Round Robin Scheduler (DRR). `QuantumBytes=` Specifies the amount of bytes a flow is allowed to dequeue before the scheduler moves to the next class. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to the MTU of the interface. # \[EnhancedTransmissionSelection\] Section Options The \[EnhancedTransmissionSelection\] section manages the queueing discipline (qdisc) of Enhanced Transmission Selection (ETS). `Bands=` Specifies the number of bands. An unsigned integer in the range 1…16. This value has to be at least large enough to cover the strict bands specified through the `StrictBands=` and bandwidth-sharing bands specified in `QuantumBytes=`. `StrictBands=` Specifies the number of bands that should be created in strict mode. An unsigned integer in the range 1…16. `QuantumBytes=` Specifies the white-space separated list of quantum used in band-sharing bands. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. This setting can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. `PriorityMap=` The priority map maps the priority of a packet to a band. The argument is a whitespace separated list of numbers. The first number indicates which band the packets with priority 0 should be put to, the second is for priority 1, and so on. There can be up to 16 numbers in the list. If there are fewer, the default band that traffic with one of the unmentioned priorities goes to is the last one. Each band number must be in the range 0…255. This setting can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. # \[GenericRandomEarlyDetection\] Section Options The \[GenericRandomEarlyDetection\] section manages the queueing discipline (qdisc) of Generic Random Early Detection (GRED). `VirtualQueues=` Specifies the number of virtual queues. Takes an integer in the range 1…16. Defaults to unset and kernel's default is used. `DefaultVirtualQueue=` Specifies the number of default virtual queue. This must be less than `VirtualQueue=`. Defaults to unset and kernel's default is used. `GenericRIO=` Takes a boolean. It turns on the RIO-like buffering scheme. Defaults to unset and kernel's default is used. # \[FairQueueingControlledDelay\] Section Options The \[FairQueueingControlledDelay\] section manages the queueing discipline (qdisc) of fair queuing controlled delay (FQ-CoDel). `PacketLimit=` Specifies the hard limit on the real queue size. When this limit is reached, incoming packets are dropped. Defaults to unset and kernel's default is used. `MemoryLimitBytes=` Specifies the limit on the total number of bytes that can be queued in this FQ-CoDel instance. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to unset and kernel's default is used. `Flows=` Specifies the number of flows into which the incoming packets are classified. Defaults to unset and kernel's default is used. `TargetSec=` Takes a timespan. Specifies the acceptable minimum standing/persistent queue delay. Defaults to unset and kernel's default is used. `IntervalSec=` Takes a timespan. This is used to ensure that the measured minimum delay does not become too stale. Defaults to unset and kernel's default is used. `QuantumBytes=` Specifies the number of bytes used as the "deficit" in the fair queuing algorithm timespan. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to unset and kernel's default is used. `ECN=` Takes a boolean. This can be used to mark packets instead of dropping them. Defaults to unset and kernel's default is used. `CEThresholdSec=` Takes a timespan. This sets a threshold above which all packets are marked with ECN Congestion Experienced (CE). Defaults to unset and kernel's default is used. # \[FairQueueing\] Section Options The \[FairQueueing\] section manages the queueing discipline (qdisc) of fair queue traffic policing (FQ). `PacketLimit=` Specifies the hard limit on the real queue size. When this limit is reached, incoming packets are dropped. Defaults to unset and kernel's default is used. `FlowLimit=` Specifies the hard limit on the maximum number of packets queued per flow. Defaults to unset and kernel's default is used. `QuantumBytes=` Specifies the credit per dequeue RR round, i.e. the amount of bytes a flow is allowed to dequeue at once. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to unset and kernel's default is used. `InitialQuantumBytes=` Specifies the initial sending rate credit, i.e. the amount of bytes a new flow is allowed to dequeue initially. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to unset and kernel's default is used. `MaximumRate=` Specifies the maximum sending rate of a flow. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000. Defaults to unset and kernel's default is used. `Buckets=` Specifies the size of the hash table used for flow lookups. Defaults to unset and kernel's default is used. `OrphanMask=` Takes an unsigned integer. For packets not owned by a socket, fq is able to mask a part of hash and reduce number of buckets associated with the traffic. Defaults to unset and kernel's default is used. `Pacing=` Takes a boolean, and enables or disables flow pacing. Defaults to unset and kernel's default is used. `CEThresholdSec=` Takes a timespan. This sets a threshold above which all packets are marked with ECN Congestion Experienced (CE). Defaults to unset and kernel's default is used. # \[TrivialLinkEqualizer\] Section Options The \[TrivialLinkEqualizer\] section manages the queueing discipline (qdisc) of trivial link equalizer (teql). `Id=` Specifies the interface ID `N` of teql. Defaults to `0`. Note that when teql is used, currently, the module `sch_teql` with `max_equalizers=N+1` option must be loaded before `systemd-networkd` is started. # \[HierarchyTokenBucket\] Section Options The \[HierarchyTokenBucket\] section manages the queueing discipline (qdisc) of hierarchy token bucket (htb). `DefaultClass=` Takes the minor id in hexadecimal of the default class. Unclassified traffic gets sent to the class. Defaults to unset. `RateToQuantum=` Takes an unsigned integer. The DRR quantums are calculated by dividing the value configured in `Rate=` by `RateToQuantum=`. # \[HierarchyTokenBucketClass\] Section Options The \[HierarchyTokenBucketClass\] section manages the traffic control class of hierarchy token bucket (htb). `Priority=` Specifies the priority of the class. In the round-robin process, classes with the lowest priority field are tried for packets first. `QuantumBytes=` Specifies how many bytes to serve from leaf at once. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. `MTUBytes=` Specifies the maximum packet size we create. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. `OverheadBytes=` Takes an unsigned integer which specifies per-packet size overhead used in rate computations. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. `Rate=` Specifies the maximum rate this class and all its children are guaranteed. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000. This setting is mandatory. `CeilRate=` Specifies the maximum rate at which a class can send, if its parent has bandwidth to spare. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000. When unset, the value specified with `Rate=` is used. `BufferBytes=` Specifies the maximum bytes burst which can be accumulated during idle period. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. `CeilBufferBytes=` Specifies the maximum bytes burst for ceil which can be accumulated during idle period. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. # \[ClassfulMultiQueueing\] Section Options The \[ClassfulMultiQueueing\] section manages the queueing discipline (qdisc) of Classful Multi Queueing (mq). # \[BandMultiQueueing\] Section Options The \[BandMultiQueueing\] section manages the queueing discipline (qdisc) of Band Multi Queueing (multiq). # \[HeavyHitterFilter\] Section Options The \[HeavyHitterFilter\] section manages the queueing discipline (qdisc) of Heavy Hitter Filter (hhf). `PacketLimit=` Specifies the hard limit on the queue size in number of packets. When this limit is reached, incoming packets are dropped. An unsigned integer in the range 0…4294967294. Defaults to unset and kernel's default is used. # \[QuickFairQueueing\] Section Options The \[QuickFairQueueing\] section manages the queueing discipline (qdisc) of Quick Fair Queueing (QFQ). # \[QuickFairQueueingClass\] Section Options The \[QuickFairQueueingClass\] section manages the traffic control class of Quick Fair Queueing (qfq). `Weight=` Specifies the weight of the class. Takes an integer in the range 1…1023. Defaults to unset in which case the kernel default is used. `MaxPacketBytes=` Specifies the maximum packet size in bytes for the class. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. When unset, the kernel default is used. # \[BridgeVLAN\] Section Options The \[BridgeVLAN\] section manages the VLAN ID configuration of a bridge master or enslaved device. To make the settings in this section take an effect, `VLANFiltering=` option has to be enabled on the bridge master, see the \[Bridge\] section in `systemd.netdev(5)`, and each enslaved device needs to define the relevant VLAN IDs in its own \[BridgeVLAN\] section, which it has in common with the bridge master. All assigned VLAN IDs on the interface that are not configured in the .network file will be removed. If VLAN IDs on an interface need to be managed by other tools, then the settings in this section cannot be used in the matching .network file and `VLANFiltering=` needs to be disabled on the bridge master. `VLAN=` The VLAN ID allowed on the port. This can be either a single ID or a range M-N. Takes an integer in the range 1…4094. This setting can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. `EgressUntagged=` The VLAN ID specified here will be used to untag frames on egress. Configuring `EgressUntagged=` implicates the use of `VLAN=` above and will enable the VLAN ID for ingress as well. This can be either a single ID or a range M-N. This setting can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared. `PVID=` The port VLAN ID specified here is assigned to all untagged frames at ingress. Takes an VLAN ID or negative boolean value (e.g. `no`). When false, the currently assigned port VLAN ID will be dropped. Configuring `PVID=` implicates the use of `VLAN=` setting in the above and will enable the VLAN ID for ingress as well. Defaults to unset, and will keep the assigned port VLAN ID if exists. # \[MobileNetwork\] Section Options This section configures the default setting of the ModemManager integration. See [](https://modemmanager.org/docs/modemmanager/) for more information about ModemManager. Regardless of the \[MobileNetwork\] section settings consider using the following for LTE modems (take into account that LTE modems do not typically support LLDP because LLDP is a Layer 2 protocol for Ethernet networks and an LTE modem connects to a cellular network, not a local Ethernet LAN): [Network] LLDP=no LinkLocalAddressing=no IPv6AcceptRA=no The following options are available in the \[MobileNetwork\] section: `APN=` An Access Point Name (APN) is the name of a gateway between a mobile network (GSM, GPRS, 3G, 4G and 5G) and another computer network. Required in 3GPP. Defaults to unset and no attempt to establish the connection is made. `AllowedAuthenticationMechanisms=` Authentication method to use. Specifies the white-space separated list of `none`, `pap`, `chap`, `mschap`, `mschapv2`, or `eap` methods. Optional in 3GPP. Defaults to unset and an automatically picked authentication method will be used. `User=` User name (if any) required by the network. Optional in 3GPP. Defaults to unset. `Password=` Password (if any) required by the network. Optional in 3GPP. Defaults to unset. `IPFamily=` Addressing type. Takes one of `ipv4`, `ipv6`, `both`, or `any`. Optional in 3GPP and CDMA. Defaults to unset and automatically selected. `AllowRoaming=` A boolean. When true, connection is allowed during roaming. When false, connection is not allowed during roaming. Optional in 3GPP. Defaults to `yes`. `PIN=` SIM-PIN unlock code. Defaults to unset. `OperatorId=` ETSI MCC-MNC of a network to force registration. Defaults to unset. `RouteMetric=` Set the routing metric for routes specified by the mobile network (including the prefix route added for the specified prefix). Takes an unsigned integer in the range 0…4294967295. When unset or set to 0, the kernel's default value will be used. `UseGateway=` When true (the default), the router address will be configured as the default gateway. # Examples
Static network configuration
# /etc/systemd/network/50-static.network [Match] Name=enp2s0 [Network] Address=192.168.0.15/24 Gateway=192.168.0.1 This brings interface `enp2s0` up with a static address. The specified gateway will be used for a default route.
DHCP on ethernet links
# /etc/systemd/network/60-dhcp.network [Match] Name=en* [Network] DHCP=yes This will enable DHCPv4 and DHCPv6 on all interfaces with names starting with `en` (i.e. ethernet interfaces).
IPv6 Prefix Delegation (DHCPv6 PD)
# /etc/systemd/network/55-dhcpv6-pd-upstream.network [Match] Name=enp1s0 [Network] DHCP=ipv6 # The lines below are optional, to also assign an address in the delegated prefix # to the upstream interface. Uncomment the lines below if necessary. #[Network] #DHCPPrefixDelegation=yes #[DHCPPrefixDelegation] #UplinkInterface=:self #SubnetId=0 #Announce=no # If the upstream network does not provides any Router Advertisement (RA) messages, # then uncomment the lines below to make the DHCPv6 client forcibly started in the # managed mode. #[Network] #IPv6AcceptRA=no #[DHCPv6] #WithoutRA=solicit # If the upstream network provides Router Advertisement (RA) messages with the # Managed bit unset, then uncomment the lines below to make the DHCPv6 client # forcibly started in the managed mode when an RA is received. #[DHCPv6] #UseAddress=no #[IPv6AcceptRA] #DHCPv6Client=always # /etc/systemd/network/55-dhcpv6-pd-downstream.network [Match] Name=enp2s0 [Network] DHCPPrefixDelegation=yes IPv6SendRA=yes # It is expected that the host is acting as a router. So, usually it is not # necessary to receive Router Advertisement from other hosts in the downstream network. IPv6AcceptRA=no [DHCPPrefixDelegation] UplinkInterface=enp1s0 SubnetId=1 Announce=yes This will enable DHCPv6-PD on the interface enp1s0 as an upstream interface where the DHCPv6 client is running and enp2s0 as a downstream interface where the prefix is delegated to. The delegated prefixes are distributed by IPv6 Router Advertisement on the downstream network.
IPv6 Prefix Delegation (DHCPv4 6RD)
# /etc/systemd/network/55-dhcpv4-6rd-upstream.network [Match] Name=enp1s0 [Network] DHCP=ipv4 # When DHCPv4-6RD is used, the upstream network does not support IPv6. # Hence, it is not necessary to wait for Router Advertisement, which is enabled by default. IPv6AcceptRA=no [DHCPv4] Use6RD=yes # /etc/systemd/network/55-dhcpv4-6rd-downstream.network [Match] Name=enp2s0 [Network] DHCPPrefixDelegation=yes IPv6SendRA=yes # It is expected that the host is acting as a router. So, usually it is not # necessary to receive Router Advertisement from other hosts in the downstream network. IPv6AcceptRA=no [DHCPPrefixDelegation] UplinkInterface=enp1s0 SubnetId=1 Announce=yes This will enable DHCPv4-6RD on the interface enp1s0 as an upstream interface where the DHCPv4 client is running and enp2s0 as a downstream interface where the prefix is delegated to. The delegated prefixes are distributed by IPv6 Router Advertisement on the downstream network.
A bridge with two enslaved links
# /etc/systemd/network/25-bridge-static.netdev [NetDev] Name=bridge0 Kind=bridge # /etc/systemd/network/25-bridge-static.network [Match] Name=bridge0 [Network] Address=192.168.0.15/24 Gateway=192.168.0.1 DNS=192.168.0.1 # /etc/systemd/network/25-bridge-slave-interface-1.network [Match] Name=enp2s0 [Network] Bridge=bridge0 # /etc/systemd/network/25-bridge-slave-interface-2.network [Match] Name=wlp3s0 [Network] Bridge=bridge0 This creates a bridge and attaches devices `enp2s0` and `wlp3s0` to it. The bridge will have the specified static address and network assigned, and a default route via the specified gateway will be added. The specified DNS server will be added to the global list of DNS resolvers.
Bridge port with VLAN forwarding
# /etc/systemd/network/25-bridge-slave-interface-1.network [Match] Name=enp2s0 [Network] Bridge=bridge0 [BridgeVLAN] VLAN=1-32 PVID=42 EgressUntagged=42 [BridgeVLAN] VLAN=100-299 [BridgeVLAN] EgressUntagged=300-400 This overrides the configuration specified in the previous example for the interface `enp2s0`, and enables VLAN on that bridge port. VLAN IDs 1-32, 42, 100-400 will be allowed. Packets tagged with VLAN IDs 42, 300-400 will be untagged when they leave on this interface. Untagged packets which arrive on this interface will be assigned VLAN ID 42.
Various tunnels
/etc/systemd/network/25-tunnels.network [Match] Name=ens1 [Network] Tunnel=ipip-tun Tunnel=sit-tun Tunnel=gre-tun Tunnel=vti-tun /etc/systemd/network/25-tunnel-ipip.netdev [NetDev] Name=ipip-tun Kind=ipip /etc/systemd/network/25-tunnel-sit.netdev [NetDev] Name=sit-tun Kind=sit /etc/systemd/network/25-tunnel-gre.netdev [NetDev] Name=gre-tun Kind=gre /etc/systemd/network/25-tunnel-vti.netdev [NetDev] Name=vti-tun Kind=vti This will bring interface `ens1` up and create an IPIP tunnel, a SIT tunnel, a GRE tunnel, and a VTI tunnel using it.
A bond device
# /etc/systemd/network/30-bond1.network [Match] Name=bond1 [Network] DHCP=ipv6 # /etc/systemd/network/30-bond1.netdev [NetDev] Name=bond1 Kind=bond # /etc/systemd/network/30-bond1-dev1.network [Match] MACAddress=52:54:00:e9:64:41 [Network] Bond=bond1 # /etc/systemd/network/30-bond1-dev2.network [Match] MACAddress=52:54:00:e9:64:42 [Network] Bond=bond1 This will create a bond device `bond1` and enslave the two devices with MAC addresses 52:54:00:e9:64:41 and 52:54:00:e9:64:42 to it. IPv6 DHCP will be used to acquire an address.
Virtual Routing and Forwarding (VRF)
Add the `bond1` interface to the VRF master interface `vrf1`. This will redirect routes generated on this interface to be within the routing table defined during VRF creation. For kernels before 4.8 traffic will not be redirected towards the VRFs routing table unless specific ip-rules are added. # /etc/systemd/network/25-vrf.network [Match] Name=bond1 [Network] VRF=vrf1
MacVTap
This brings up a network interface `macvtap-test` and attaches it to `enp0s25`. # /usr/lib/systemd/network/25-macvtap.network [Match] Name=enp0s25 [Network] MACVTAP=macvtap-test
A Xfrm interface with physical underlying device.
# /etc/systemd/network/27-xfrm.netdev [NetDev] Name=xfrm0 Kind=xfrm [Xfrm] InterfaceId=7 # /etc/systemd/network/27-eth0.network [Match] Name=eth0 [Network] Xfrm=xfrm0 This creates a `xfrm0` interface and binds it to the `eth0` device. This allows hardware based ipsec offloading to the `eth0` nic. If offloading is not needed, xfrm interfaces can be assigned to the `lo` device.
Connecting to a cellular network with ModemManager
# /etc/systemd/network/27-wwan0.network [Match] Name=wwan0 [Network] LLDP=no LinkLocalAddressing=no IPv6AcceptRA=no [MobileNetwork] APN=internet AllowedAuthenticationMechanisms=none pap chap User=user Password=pass IPFamily=both AllowRoaming=no PIN=1111 OperatorId=25503 RouteMetric=30 UseGateway=yes This connects a cellular modem to a broadband network matched with the network interface `wwan0`, with APN name `internet`, allowed authentication `none`, `pcap`, or `chap`, user name `user`, their password `pass`, allows both IPv4 and IPv6, does not allow roaming, SIM card pin unlock code `1111`, only allows connecting to operator with MCC `25503`, and sets up a default gateway with route metric of 30.
# See Also `systemd(1)`, `systemd-networkd.service(8)`, `systemd.link(5)`, `systemd.netdev(5)`, `systemd-network-generator.service(8)`, `systemd-resolved.service(8)` # systemd.nspawn systemd systemd.nspawn 5 systemd.nspawn Container settings `/etc/systemd/nspawn/machine.nspawn`, `/run/systemd/nspawn/machine.nspawn`, `/var/lib/machines/machine.nspawn` # Description An nspawn container settings file (suffix `.nspawn`) contains runtime configuration for a local container, and is used by `systemd-nspawn(1)`. Files of this type are named after the containers they define settings for. They are optional, and only required for containers whose execution environment shall differ from the defaults. Files of this type mostly contain settings that may also be set on the `systemd-nspawn` command line, and make it easier to persistently attach specific settings to specific containers. The syntax of these files is inspired by `.desktop` files, similarly to other configuration files supported by the systemd project. See `systemd.syntax(7)` for an overview. # `.nspawn` File Discovery Files are searched for by appending the `.nspawn` suffix to the machine name of the container, as specified with the `--machine=` switch of `systemd-nspawn`, or derived from the directory or image file name. This file is first searched for in `/etc/systemd/nspawn/` and `/run/systemd/nspawn/`. If found there, the settings are read and all of them take full effect (but may still be overridden by corresponding command line arguments). Otherwise, the file will then be searched for next to the image file or in the immediate parent of the root directory of the container. If the file is found there, only a subset of the settings will take effect however. All settings that possibly elevate privileges or grant additional access to resources of the host (such as files or directories) are ignored. To which options this applies is documented below. Persistent settings files created and maintained by the administrator (and thus trusted) should be placed in `/etc/systemd/nspawn/`, while automatically downloaded (and thus potentially untrusted) settings files are placed in `/var/lib/machines/` instead (next to the container images), where their security impact is limited. In order to add privileged settings to `.nspawn` files acquired from the image vendor, it is recommended to copy the settings files into `/etc/systemd/nspawn/` and edit them there, so that the privileged options become available. The precise algorithm for how the files are searched and interpreted may be configured with `systemd-nspawn`'s `--settings=` switch, see `systemd-nspawn(1)` for details. # \[Exec\] Section Options Settings files may include an \[Exec\] section, which carries various execution parameters: `Boot=` Takes a boolean argument, which defaults to off. If enabled, `systemd-nspawn` will automatically search for an `init` executable and invoke it. In this case, the specified parameters using `Parameters=` are passed as additional arguments to the `init` process. This setting corresponds to the `--boot` switch on the `systemd-nspawn` command line. This option may not be combined with `ProcessTwo=yes`. This option is specified by default in the `systemd-nspawn@.service` template unit. `Ephemeral=` Takes a boolean argument, which defaults to off, If enabled, the container is run with a temporary snapshot of its file system that is removed immediately when the container terminates. This is equivalent to the `--ephemeral` command line switch. See `systemd-nspawn(1)` for details about the specific options supported. `ProcessTwo=` Takes a boolean argument, which defaults to off. If enabled, the specified program is run as PID 2. A stub init process is run as PID 1. This setting corresponds to the `--as-pid2` switch on the `systemd-nspawn` command line. This option may not be combined with `Boot=yes`. `Parameters=` Takes a whitespace-separated list of arguments. Single (`'`) and double (`"`) quotes may be used around arguments with whitespace. This is either a command line, beginning with the binary name to execute, or – if `Boot=` is enabled – the list of arguments to pass to the init process. This setting corresponds to the command line parameters passed on the `systemd-nspawn` command line. Note: `Boot=no`, `Parameters=a b "c c"` is the same as `systemd-nspawn a b "c c"`, and `Boot=yes`, `Parameters=b 'c c'` is the same as `systemd-nspawn --boot b 'c c'`. `Environment=` Takes an environment variable assignment consisting of key and value, separated by `=`. Sets an environment variable for the main process invoked in the container. This setting may be used multiple times to set multiple environment variables. It corresponds to the `--setenv=` command line switch. `User=` Takes a UNIX user name. Specifies the user name to invoke the main process of the container as. This user must be known in the container's user database. This corresponds to the `--user=` command line switch. `WorkingDirectory=` Selects the working directory for the process invoked in the container. Expects an absolute path in the container's file system namespace. This corresponds to the `--chdir=` command line switch. `PivotRoot=` Selects a directory to pivot to `/` inside the container when starting up. Takes a single path, or a pair of two paths separated by a colon. Both paths must be absolute, and are resolved in the container's file system namespace. This corresponds to the `--pivot-root=` command line switch. `Capability=`; `DropCapability=` Takes a space-separated list of Linux process capabilities (see `capabilities(7)` for details). The `Capability=` setting specifies additional capabilities to pass on top of the default set of capabilities. The `DropCapability=` setting specifies capabilities to drop from the default set. These settings correspond to the `--capability=` and `--drop-capability=` command line switches. Note that `Capability=` is a privileged setting, and only takes effect in `.nspawn` files in `/etc/systemd/nspawn/` and `/run/system/nspawn/` (see above). On the other hand, `DropCapability=` takes effect in all cases. If the special value `all` is passed, all capabilities are retained (or dropped). These settings change the bounding set of capabilities which also limits the ambient capabilities as given with the `AmbientCapability=`. `AmbientCapability=` Takes a space-separated list of Linux process capabilities (see `capabilities(7)` for details). The `AmbientCapability=` setting specifies capabilities which will be passed to the started program in the inheritable and ambient capability sets. This will grant these capabilities to this process. This setting correspond to the `--ambient-capability=` command line switch. The value `all` is not supported for this setting. The setting of `AmbientCapability=` must be covered by the bounding set settings which were established by `Capability=` and `DropCapability=`. Note that `AmbientCapability=` is a privileged setting (see above). `NoNewPrivileges=` Takes a boolean argument that controls the `PR_SET_NO_NEW_PRIVS` flag for the container payload. This is equivalent to the `--no-new-privileges=` command line switch. See `systemd-nspawn(1)` for details. `KillSignal=` Specify the process signal to send to the container's PID 1 when nspawn itself receives SIGTERM, in order to trigger an orderly shutdown of the container. Defaults to SIGRTMIN+3 if `Boot=` is used (on systemd-compatible init systems SIGRTMIN+3 triggers an orderly shutdown). For a list of valid signals, see `signal(7)`. `Personality=` Configures the kernel personality for the container. This is equivalent to the `--personality=` switch. `MachineID=` Configures the 128-bit machine ID (UUID) to pass to the container. This is equivalent to the `--uuid=` command line switch. This option is privileged (see above). `PrivateUsers=` Configures support for usernamespacing. This is equivalent to the `--private-users=` command line switch, and takes the same options. This option is privileged (see above). This option is the default if the `systemd-nspawn@.service` template unit file is used. `PrivateUsersDelegate=` Takes a non-negative integer. Configures delegation of additional 64K UID/GID ranges into the container's user namespace for use by nested containers. When set to a value greater than zero, the `systemd-nsresourced.service(8)` varlink socket will be bind-mounted into the container so that processes inside the container can allocate further user namespaces from the delegated ranges. This is equivalent to the `--private-users-delegate=` command line switch. Requires `PrivateUsers=managed`. Defaults to 0. See `systemd-nspawn(1)` for details. `NotifyReady=` Configures support for notifications from the container's init process. This is equivalent to the `--notify-ready=` command line switch, and takes the same parameters. See `systemd-nspawn(1)` for details about the specific options supported. `SystemCallFilter=` Configures the system call filter applied to containers. This is equivalent to the `--system-call-filter=` command line switch, and takes the same list parameter. See `systemd-nspawn(1)` for details. `RestrictAddressFamilies=` Restricts the socket address families accessible to the container. This is equivalent to the `--restrict-address-families=` command line switch, and takes the same list parameter. See `systemd-nspawn(1)` for details. `SetCredential=`; `LoadCredential=` Pass a credential to the container. These settings are equivalent to the `--set-credential=` and `--load-credential=` command line switches, and take \:\ and \:\ respectively, where \ is either an absolute path or the name of a credential passed to `systemd-nspawn` itself. Each may be specified more than once to pass multiple credentials. If the same credential ID is assigned more than once by the same setting, the last assignment takes effect. If the empty string is assigned, the list of credentials set by the respective setting so far is reset. Credentials from the settings file and from the command line are not combined: if any credential is passed on the command line, these settings are ignored, unless `--settings=override` is used, in which case the credentials from the settings file replace those from the command line. See `systemd-nspawn(1)` for details. As with the settings of the same names in unit files (see `systemd.exec(5)`), if the same credential ID is specified with both settings, `LoadCredential=` takes priority, and `SetCredential=` acts as a fallback if the file does not exist. A credential that is to be inherited from `systemd-nspawn` itself, i.e. if \ is a credential name, is skipped if it was not passed. In both of these cases, a missing credential is not considered fatal. `LoadCredential=` is privileged (see above), as it reads files on the host. For example, the credentials of `systemd-nspawn@.service` may be propagated to the container with `LoadCredential=ID:ID` in a settings file in `/etc/systemd/nspawn/`. Do not use `SetCredential=` for secret data, as settings files are usually readable by unprivileged users. Use `LoadCredential=` instead. `LimitCPU=`; `LimitFSIZE=`; `LimitDATA=`; `LimitSTACK=`; `LimitCORE=`; `LimitRSS=`; `LimitNOFILE=`; `LimitAS=`; `LimitNPROC=`; `LimitMEMLOCK=`; `LimitLOCKS=`; `LimitSIGPENDING=`; `LimitMSGQUEUE=`; `LimitNICE=`; `LimitRTPRIO=`; `LimitRTTIME=` Configures various types of resource limits applied to containers. This is equivalent to the `--rlimit=` command line switch, and takes the same arguments. See `systemd-nspawn(1)` for details. `OOMScoreAdjust=` Configures the OOM score adjustment value. This is equivalent to the `--oom-score-adjust=` command line switch, and takes the same argument. See `systemd-nspawn(1)` for details. `CPUAffinity=` Configures the CPU affinity. This is equivalent to the `--cpu-affinity=` command line switch, and takes the same argument. See `systemd-nspawn(1)` for details. `Hostname=` Configures the kernel hostname set for the container. This is equivalent to the `--hostname=` command line switch, and takes the same argument. See `systemd-nspawn(1)` for details. `ResolvConf=` Configures how `/etc/resolv.conf` in the container shall be handled. This is equivalent to the `--resolv-conf=` command line switch, and takes the same argument. See `systemd-nspawn(1)` for details. `Timezone=` Configures how `/etc/localtime` in the container shall be handled. This is equivalent to the `--timezone=` command line switch, and takes the same argument. See `systemd-nspawn(1)` for details. `LinkJournal=` Configures how to link host and container journal setups. This is equivalent to the `--link-journal=` command line switch, and takes the same parameter. See `systemd-nspawn(1)` for details. `SuppressSync=` Configures whether to suppress disk synchronization for the container payload. This is equivalent to the `--suppress-sync=` command line switch, and takes the same parameter. See `systemd-nspawn(1)` for details. # \[Files\] Section Options Settings files may include a \[Files\] section, which carries various parameters configuring the file system of the container: `ReadOnly=` Takes a boolean argument, which defaults to off. If specified, the container will be run with a read-only file system. This setting corresponds to the `--read-only` command line switch. `Volatile=` Takes a boolean argument, or the special value `state`. This configures whether to run the container with volatile state and/or configuration. This option is equivalent to `--volatile=`, see `systemd-nspawn(1)` for details about the specific options supported. `Bind=`; `BindReadOnly=` Adds a bind mount from the host into the container. Takes a single path, a pair of two paths separated by a colon, or a triplet of two paths plus an option string separated by colons. This option may be used multiple times to configure multiple bind mounts. This option is equivalent to the command line switches `--bind=` and `--bind-ro=`, see `systemd-nspawn(1)` for details about the specific options supported. This setting is privileged (see above). `BindUser=` Binds a user from the host into the container. This option is equivalent to the command line switch `--bind-user=`, see `systemd-nspawn(1)` for details about the specific options supported. This setting is privileged (see above). `BindUserShell=` When used with `BindUser`, specifies the shell that is included in the user record of users bound from the host into the container. This option is equivalent to the command line switch `--bind-user-shell=`, see `systemd-nspawn(1)` for details about the specific options supported. This setting is privileged (see above). `TemporaryFileSystem=` Adds a `tmpfs` mount to the container. Takes a path or a pair of path and option string, separated by a colon. This option may be used multiple times to configure multiple `tmpfs` mounts. This option is equivalent to the command line switch `--tmpfs=`, see `systemd-nspawn(1)` for details about the specific options supported. This setting is privileged (see above). `Inaccessible=` Masks the specified file or directory in the container, by over-mounting it with an empty file node of the same type with the most restrictive access mode. Takes a file system path as argument. This option may be used multiple times to mask multiple files or directories. This option is equivalent to the command line switch `--inaccessible=`, see `systemd-nspawn(1)` for details about the specific options supported. This setting is privileged (see above). `Overlay=`; `OverlayReadOnly=` Adds an overlay mount point. Takes a colon-separated list of paths. This option may be used multiple times to configure multiple overlay mounts. This option is equivalent to the command line switches `--overlay=` and `--overlay-ro=`, see `systemd-nspawn(1)` for details about the specific options supported. This setting is privileged (see above). `PrivateUsersOwnership=` Configures whether the ownership of the files and directories in the container tree shall be adjusted to the UID/GID range used, if necessary. This is equivalent to the `--private-users-ownership=` command line switch. This option is privileged (see above). Defaults to `auto` if `PrivateUsers=pick` or `PrivateUsers=managed` is used. This option has no effect if user namespacing is not used. # \[Network\] Section Options Settings files may include a \[Network\] section, which carries various parameters configuring the network connectivity of the container: `Private=` Takes a boolean argument, which defaults to off. If enabled, the container will run in its own network namespace and not share network interfaces and configuration with the host. This setting corresponds to the `--private-network` command line switch. `NamespacePath=` Takes the path to a file representing a kernel network namespace that the container shall run in. The specified path should refer to a (possibly bind-mounted) network namespace file, as exposed by the kernel below `/proc/$PID/ns/net`. This makes the container enter the given network namespace. One of the typical use cases is to give a network namespace under `/run/netns` created by `ip-netns(8)`, for example, `NamespacePath=/run/netns/foo`. Note that this option cannot be used together with other network-related options, such as `Private=` or `Interface=`. This option corresponds to the `--network-namespace-path` command line switch. `VirtualEthernet=` Takes a boolean argument. Configures whether to create a virtual Ethernet connection (`veth`) between host and the container. This setting implies `Private=yes`. This setting corresponds to the `--network-veth` command line switch. This option is the default if the `systemd-nspawn@.service` template unit file is used. `VirtualEthernetExtra=` Takes a colon-separated pair of interface names. Configures an additional virtual Ethernet connection (`veth`) between host and the container. The first specified name is the interface name on the host, the second the interface name in the container. The latter may be omitted in which case it is set to the same name as the host side interface. This setting implies `Private=yes`. This setting corresponds to the `--network-veth-extra=` command line switch, and may be used multiple times. It is independent of `VirtualEthernet=`. Note that this option is unrelated to the `Bridge=` setting below, and thus any connections created this way are not automatically added to any bridge device on the host side. This option is privileged (see above). `Interface=` Takes a space-separated list of interfaces to add to the container. The interface object is defined either by a single interface name, referencing the name on the host, or a colon-separated pair of interfaces, in which case the first one references the name on the host, and the second one the name in the container. This option corresponds to the `--network-interface=` command line switch and implies `Private=yes`. This option is privileged (see above). `MACVLAN=`; `IPVLAN=` Takes a space-separated list of interfaces to add MACLVAN or IPVLAN interfaces to, which are then added to the container. The interface object is defined either by a single interface name, referencing the name on the host, or a colon-separated pair of interfaces, in which case the first one references the name on the host, and the second one the name in the container. These options correspond to the `--network-macvlan=` and `--network-ipvlan=` command line switches and imply `Private=yes`. These options are privileged (see above). `Bridge=` Takes an interface name. This setting implies `VirtualEthernet=yes` and `Private=yes` and has the effect that the host side of the created virtual Ethernet link is connected to the specified bridge interface. This option corresponds to the `--network-bridge=` command line switch. This option is privileged (see above). `Zone=` Takes a network zone name. This setting implies `VirtualEthernet=yes` and `Private=yes` and has the effect that the host side of the created virtual Ethernet link is connected to an automatically managed bridge interface named after the passed argument, prefixed with `vz-`. This option corresponds to the `--network-zone=` command line switch. This option is privileged (see above). `Port=` Exposes a TCP or UDP port of the container on the host. This option corresponds to the `--port=` command line switch, see `systemd-nspawn(1)` for the precise syntax of the argument this option takes. This option is privileged (see above). # See Also `systemd(1)`, `systemd-nspawn(1)`, `systemd.directives(7)` # systemd.offline-updates systemd systemd.offline-updates 7 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](https://wiki.gnome.org/Design/OS/SoftwareUpdates). 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)` # systemd.path systemd systemd.path 5 systemd.path Path unit configuration `path.path` # Description A unit configuration file whose name ends in `.path` encodes information about a path monitored by systemd, for path-based activation. This man page lists the configuration options specific to this unit type. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. The path specific configuration options are configured in the \[Path\] section. For each path file, a matching unit file must exist, describing the unit to activate when the path changes. By default, a service by the same name as the path (except for the suffix) is activated. Example: a path file `foo.path` activates a matching service `foo.service`. The unit to activate may be controlled by `Unit=` (see below). Internally, path units use the `inotify(7)` API to monitor file systems. Due to that, it suffers by the same limitations as inotify, and for example cannot be used to monitor files or directories changed by other machines on remote NFS file systems. When a service unit triggered by a path unit terminates (regardless whether it exited successfully or failed), monitored paths are checked immediately again, and the service accordingly restarted instantly. As protection against busy looping in this trigger/start cycle, a start rate limit is enforced on the service unit, see `StartLimitIntervalSec=` and `StartLimitBurst=` in `systemd.unit(5)`. Unlike other service failures, the error condition that the start rate limit is hit is propagated from the service unit to the path unit and causes the path unit to fail as well, thus ending the loop. # Automatic Dependencies ## Implicit Dependencies The following dependencies are implicitly added: - If a path unit is beneath another mount unit in the file system hierarchy, both a requirement and an ordering dependency between both units are created automatically. - An implicit `Before=` dependency is added between a path unit and the unit it is supposed to activate. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - Path units will automatically have dependencies of type `Before=` on `paths.target`, dependencies of type `After=` and `Requires=` on `sysinit.target`, and have dependencies of type `Conflicts=` and `Before=` on `shutdown.target`. These ensure that path units are terminated cleanly prior to system shutdown. Only path units involved with early boot or late system shutdown should disable `DefaultDependencies=` option. # Options Path unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. Path unit files must include a \[Path\] section, which carries information about the path or paths it monitors. The options specific to the \[Path\] section of path units are the following: `PathExists=`; `PathExistsGlob=`; `PathChanged=`; `PathModified=`; `DirectoryNotEmpty=` Defines paths to monitor for certain changes: `PathExists=` may be used to watch the mere existence of a file or directory. If the file specified exists, the configured unit is activated. `PathExistsGlob=` works similarly, but checks for the existence of at least one file matching the globbing pattern specified. `PathChanged=` may be used to watch a file or directory and activate the configured unit whenever it changes. It is not activated on every write to the watched file but it is activated if the file which was open for writing gets closed. `PathModified=` is similar, but additionally it is activated also on simple writes to the watched file. `DirectoryNotEmpty=` may be used to watch a directory and activate the configured unit whenever it contains at least one file. The arguments of these directives must be absolute file system paths. Multiple directives may be combined, of the same and of different types, to watch multiple paths. If the empty string is assigned to any of these options, the list of paths to watch is reset, and any prior assignments of these options will not have any effect. If a path already exists (in case of `PathExists=` and `PathExistsGlob=`) or a directory already is not empty (in case of `DirectoryNotEmpty=`) at the time the path unit is activated, then the configured unit is immediately activated as well. Something similar does not apply to `PathChanged=` and `PathModified=`. If the path itself or any of the containing directories are not accessible, `systemd` will watch for permission changes and notice that conditions are satisfied when permissions allow that. Note that files whose name starts with a dot (i.e. hidden files) are generally ignored when monitoring these paths. `Unit=` The unit to activate when any of the configured paths changes. The argument is a unit name, whose suffix is not `.path`. If not specified, this value defaults to a service that has the same name as the path unit, except for the suffix. (See above.) It is recommended that the unit name that is activated and the unit name of the path unit are named identical, except for the suffix. `MakeDirectory=` Takes a boolean argument. If true, the directories to watch are created before watching. This option is ignored for `PathExists=` settings. Defaults to `false`. `DirectoryMode=` If `MakeDirectory=` is enabled, use the mode specified here to create the directories in question. Takes an access mode in octal notation. Defaults to `0755`. `TriggerLimitIntervalSec=`; `TriggerLimitBurst=` Configures a limit on how often this path unit may be activated within a specific time interval. The `TriggerLimitIntervalSec=` may be used to configure the length of the time interval in the usual time units `us`, `ms`, `s`, `min`, `h`, … and defaults to 2s. See `systemd.time(7)` for details on the various time units understood. The `TriggerLimitBurst=` setting takes a positive integer value and specifies the number of permitted activations per time interval, and defaults to 200. Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the unit is placed into a failure mode, and will not watch the paths anymore until restarted. Note that this limit is enforced before the service activation is enqueued. # See Also Environment variables with details on the trigger will be set for triggered units. See the section `Environment Variables Set or Propagated by the Service Manager` in `systemd.exec(5)` for more details. `systemd(1)`, `systemctl(1)`, `systemd.unit(5)`, `systemd.service(5)`, `inotify(7)`, `systemd.directives(7)` # systemd.pcrlock systemd systemd.pcrlock 5 systemd.pcrlock systemd.pcrlock.d PCR measurement prediction files `/etc/pcrlock.d/*.pcrlock`, `/etc/pcrlock.d/*.pcrlock.d/*.pcrlock`, `/run/pcrlock.d/*.pcrlock`, `/run/pcrlock.d/*.pcrlock.d/*.pcrlock`, `/var/lib/pcrlock.d/*.pcrlock`, `/var/lib/pcrlock.d/*.pcrlock.d/*.pcrlock`, `/usr/local/lib/pcrlock.d/*.pcrlock`, `/usr/local/lib/pcrlock.d/*.pcrlock.d/*.pcrlock`, `/usr/lib/pcrlock.d/*.pcrlock`, `/usr/lib/pcrlock.d/*.pcrlock.d/*.pcrlock` # Description `*.pcrlock` files define expected TPM2 PCR measurements of components involved in the boot process. `systemd-pcrlock(8)` uses such pcrlock files to analyze and predict TPM2 PCR measurements. The pcrlock files are JSON arrays that follow a subset of the [TCG Canonical Event Log Format (CEL-JSON)](https://trustedcomputinggroup.org/resource/canonical-event-log-format/) specification. Specifically the `recnum`, `content`, and `content_type` record fields are not used and ignored if present. Each pcrlock file defines one set of expected, ordered PCR measurements of a specific component of the boot. \*.pcrlock files may be placed in various `.d/` drop-in directories (see above for a full list). All matching files discovered in these directories are sorted alphabetically by their file name (without taking the actual directory they were found in into account): pcrlock files with alphabetically earlier names are expected to cover measurements done before those with alphabetically later names. In order to make positioning pcrlock files in the boot process convenient the files are expected (by convention, this is not enforced) to be named `NNN-component.pcrlock` (where \ is a three-digit decimal number), for example `750-enter-initrd.pcrlock`. For various components of the boot process more than one alternative pcrlock file shall be supported (i.e. "variants"). For example to cover multiple kernels installed in parallel in the access policy, or multiple versions of the boot loader. This can be done by placing `*.pcrlock.d/*.pcrlock` in the drop-in dirs, i.e. a common directory for a specific component, that contains one or more pcrlock files each covering one *variant* of the component. Example: `650-kernel.pcrlock.d/6.5.5-200.fc38.x86_64.pcrlock` and `650-kernel.pcrlock.d/6.5.7-100.fc38.x86_64.pcrlock` Use `systemd-pcrlock list-components` to list all pcrlock files currently installed. Use the various `lock-*` commands of `systemd-pcrlock` to automatically generate suitable pcrlock files for various types of resources. # Well-known Components Components of the boot process may be defined freely by the administrator or OS vendor. The following components are well-known however, and are defined by systemd. The list below is useful for ordering local pcrlock files properly against these components of the boot. `240-secureboot-policy.pcrlock` The SecureBoot policy, as recorded to PCR 7. May be generated via `systemd-pcrlock lock-secureboot-policy`. `250-firmware-code-early.pcrlock` Firmware code measurements, as recorded to PCR 0 and 2, up to the separator measurement (see `400-secureboot-separator.pcrlock` below). May be generated via `systemd-pcrlock lock-firmware-code`. `250-firmware-config-early.pcrlock` Firmware configuration measurements, as recorded to PCR 1 and 3, up to the separator measurement (see `400-secureboot-separator.pcrlock` below). May be generated via `systemd-pcrlock lock-firmware-config`. `350-action-efi-application.pcrlock` The EFI "Application" measurement done once by the firmware. Statically defined. `400-secureboot-separator.pcrlock` The EFI "separator" measurement on PCR 7 done once by the firmware to indicate where firmware control transitions into boot loader/OS control. Statically defined. `500-separator.pcrlock` The EFI "separator" measurements on PCRs 0-6 done once by the firmware to indicate where firmware control transitions into boot loader/OS control. Statically defined. `550-firmware-code-late.pcrlock` Firmware code measurements, as recorded to PCR 0 and 2, after the separator measurement (see `400-secureboot-separator.pcrlock` above). May be generated via `systemd-pcrlock lock-firmware-code`. `550-firmware-config-late.pcrlock` Firmware configuration measurements, as recorded to PCR 1 and 3, after the separator measurement (see `400-secureboot-separator.pcrlock` above). May be generated via `systemd-pcrlock lock-firmware-config`. `600-gpt.pcrlock` The GPT partition table of the booted medium, as recorded to PCR 5 by the firmware. May be generated via `systemd-pcrlock lock-gpt`. `620-secureboot-authority.pcrlock` The SecureBoot authority, as recorded to PCR 7. May be generated via `systemd-pcrlock lock-secureboot-authority`. `700-action-efi-exit-boot-services.pcrlock` The EFI action generated when `ExitBootServices()` is generated, i.e. when the UEFI environment is left and the OS takes over. Covers the PCR 5 measurement. Statically defined. `710-kernel-cmdline.pcrlock` The kernel command line, as measured by the Linux kernel to PCR 9. May be generated via `systemd-pcrlock lock-kernel-cmdline`. `720-kernel-initrd.pcrlock` The kernel initrd, as measured by the Linux kernel to PCR 9. May be generated via `systemd-pcrlock lock-kernel-initrd`. `750-enter-initrd.pcrlock` The measurement to PCR 11 `systemd-pcrphase-initrd.service(8)` makes when the initrd initializes. Statically defined. `800-leave-initrd.pcrlock` The measurement to PCR 11 `systemd-pcrphase-initrd.service(8)` makes when the initrd finishes. Statically defined. `820-machine-id.pcrlock` The measurement to PCR 15 `systemd-pcrmachine.service(8)` makes at boot, covering `/etc/machine-id` contents. May be generated via `systemd-pcrlock lock-machine-id`. `830-root-file-system.pcrlock` The measurement to PCR 15 `systemd-pcrfs-root.service(8)` makes at boot, covering the root file system identity. May be generated via `systemd-pcrlock lock-file-system`. `850-sysinit.pcrlock` The measurement to PCR 11 `systemd-pcrphase-sysinit.service(8)` makes when the main userspace did basic initialization and will now proceed to start regular system services. Statically defined. `900-ready.pcrlock` The measurement to PCR 11 `systemd-pcrphase.service(8)` makes when the system fully booted up. Statically defined. `950-shutdown.pcrlock` The measurement to PCR 11 `systemd-pcrphase.service(8)` makes when the system begins shutdown. Statically defined. `990-final.pcrlock` The measurement to PCR 11 `systemd-pcrphase-sysinit.service(8)` makes when the system is close to finishing shutdown. Statically defined. # See Also `systemd(1)`, `systemd-pcrlock(8)` # systemd.preset systemd systemd.preset 5 systemd.preset Service enablement presets `/etc/systemd/system-preset/*.preset`, `/run/systemd/system-preset/*.preset`, `/usr/local/lib/systemd/system-preset/*.preset`, `/usr/lib/systemd/system-preset/*.preset`, `/etc/systemd/user-preset/*.preset`, `/run/systemd/user-preset/*.preset`, `/usr/local/lib/systemd/user-preset/*.preset`, `/usr/lib/systemd/user-preset/*.preset`, `/etc/systemd/initrd-preset/*.preset`, `/run/systemd/initrd-preset/*.preset`, `/usr/local/lib/systemd/initrd-preset/*.preset`, `/usr/lib/systemd/initrd-preset/*.preset` # Description Preset files may be used to encode policy which units shall be enabled by default and which ones shall be disabled. They are read by `systemctl preset` which uses this information to enable or disable a unit. Depending on that policy, `systemctl preset` is identical to `systemctl enable` or `systemctl disable`. `systemctl preset` is used by the post install scriptlets of rpm packages (or other OS package formats), to enable/disable specific units by default on package installation, enforcing distribution, spin, or administrator preset policy. This allows choosing a certain set of units to be enabled/disabled even before installing the actual package. For more information, see `systemctl(1)`. It is not recommended to ship preset files within the respective software packages implementing the units, but rather centralize them in a distribution or spin default policy, which can be amended by administrator policy, see below. If no preset files exist, preset operations will enable all units that are installed by default. If this is not desired and all units shall rather be disabled, it is necessary to ship a preset file with a single, catchall "`disable *`" line. (See example 1, below.) When the machine is booted for the first time, `systemd(1)` will enable/disable all units according to preset policy, similarly to `systemctl preset-all`. Also see `ConditionFirstBoot=` in `systemd.unit(5)` and "First Boot Semantics" in `machine-id(5)`. # Preset File Format The preset files contain a list of directives, one per line. Empty lines and lines whose first non-whitespace character is `#` or `;` are ignored. Each directive consists of one of the words `enable`, `disable`, or `ignore`, followed by whitespace and a unit name. The unit name may contain shell-style wildcards. For the enable directive for template units, one or more instance names may be specified as a space-separated list after the unit name. In this case, those instances will be enabled instead of the instance specified via DefaultInstance= in the unit. Presets must refer to the "real" unit file, and not to any aliases. See `systemd.unit(5)` for a description of unit aliasing. Three different directives are understood: `enable` may be used to enable units by default, `disable` to disable units by default, and `ignore` to ignore units and leave existing configuration intact. If multiple lines apply to a unit name, the first matching one takes precedence over all others. Each preset file shall be named in the style of `-.preset`. Files in `/etc/` override files with the same name in `/usr/lib/` and `/run/`. Files in `/run/` override files with the same name in `/usr/lib/`. Packages should install their preset files in `/usr/lib/`. Files in `/etc/` are reserved for the local administrator, who may use this logic to override the preset files installed by vendor packages. All preset files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in. If multiple files specify the same unit name, the entry in the file with the lexicographically earliest name will be applied. It is recommended to prefix all filenames with a two-digit number and a dash, to simplify the ordering of the files. If the administrator wants to disable a preset file supplied by the vendor, the recommended way is to place a symlink to `/dev/null` in `/etc/systemd/system-preset/` bearing the same filename. # Examples
Default to off
# /usr/lib/systemd/system-preset/99-default.preset disable *
This disables all units. Due to the filename prefix `99-`, it will be read last and hence can easily be overridden by spin or administrator preset policy.
Enable multiple template instances
# /usr/lib/systemd/system-preset/80-dirsrv.preset enable dirsrv@.service foo bar baz
This enables all three of `dirsrv@foo.service`, `dirsrv@bar.service` and `dirsrv@baz.service`.
A GNOME spin
# /usr/lib/systemd/system-preset/50-gnome.preset enable gdm.service enable colord.service enable accounts-daemon.service enable avahi-daemon.*
This enables the three mentioned units, plus all `avahi-daemon` regardless of which unit type. A file like this could be useful for inclusion in a GNOME spin of a distribution. It will ensure that the units necessary for GNOME are properly enabled as they are installed. It leaves all other units untouched, and subject to other (later) preset files, for example like the one from the first example above.
Administrator policy
# /etc/systemd/system-preset/00-lennart.preset enable httpd.service enable sshd.service enable postfix.service disable *
This enables three specific services and disables all others. This is useful for administrators to specifically select the units to enable, and disable all others. Due to the filename prefix `00-` it will be read early and override all other preset policy files. # Motivation for the preset logic Different distributions have different policies on which services shall be enabled by default when the package they are shipped in is installed. On Fedora all services stay off by default, so that installing a package will not cause a service to be enabled (with some exceptions). On Debian all services are immediately enabled by default, so that installing a package will cause its services to be enabled right-away. Even within a single distribution, different spins (flavours, remixes, whatever you might want to call them) of a distribution also have different policies on what services to enable, and what services to leave off. For example, Fedora Workstation will enable `gdm` as display manager by default, while the Fedora KDE spin will enable `sddm` instead. Different sites might also have different policies what to turn on by default and what to turn off. For example, one administrator would prefer to enforce the policy of "`sshd` should be always on, but everything else off", while another one might say "`snmpd` always on, and for everything else use the distribution policy defaults". Traditionally, policy about which services shall be enabled were implemented in each package individually. This made it cumbersome to implement different policies per spin or per site, or to create software packages that do the right thing on more than one distribution. The enablement mechanism was also encoding the enablement policy. The preset mechanism allows clean separation of the enablement mechanism (inside the package scriptlets, by invoking `systemctl preset`) and enablement policy (centralized in the preset files), and lifts the configuration out of individual packages. Preset files may be written for specific distributions, for specific spins or for specific sites, in order to enforce different policies as needed. It is recommended to apply the policy encoded in preset files in package installation scriptlets. # See Also `systemd(1)`, `systemctl(1)`, `systemd-delta(1)` `daemon(7)` has a discussion of packaging scriptlets. Fedora page introducing the use of presets: [Features/PackagePresets](https://fedoraproject.org/wiki/Features/PackagePresets). # systemd.resource-control systemd systemd.resource-control 5 systemd.resource-control Resource control unit settings `slice.slice`, `scope.scope`, `service.service`, `socket.socket`, `mount.mount`, `swap.swap` # Description Unit configuration files for services, slices, scopes, sockets, mount points, and swap devices share a subset of configuration options for resource control of spawned processes. Internally, this relies on the Linux Control Groups (cgroups) kernel concept for organizing processes in a hierarchical tree of named groups for the purpose of resource management. This man page lists the configuration options shared by those six unit types. See `systemd.unit(5)` for the common options of all unit configuration files, and `systemd.slice(5)`, `systemd.scope(5)`, `systemd.service(5)`, `systemd.socket(5)`, `systemd.mount(5)`, and `systemd.swap(5)` for more information on the specific unit configuration files. The resource control configuration options are configured in the \[Slice\], \[Scope\], \[Service\], \[Socket\], \[Mount\], or \[Swap\] sections, depending on the unit type. In addition, options which control resources available to programs *executed* by systemd are listed in `systemd.exec(5)`. Those options complement options listed here. ## Enabling and disabling controllers Controllers in the cgroup hierarchy are hierarchical, and resource control is realized by distributing resource assignments between siblings in branches of the cgroup hierarchy. There is no need to explicitly *enable* a cgroup controller for a unit. `systemd` will instruct the kernel to enable a controller for a given unit when this unit has configuration for a given controller. For example, when `CPUWeight=` is set, the `cpu` controller will be enabled, and when `TasksMax=` are set, the `pids` controller will be enabled. In addition, various controllers may be also be enabled explicitly via the `MemoryAccounting=`/`TasksAccounting=`/`IOAccounting=` settings. Because of how the cgroup hierarchy works, controllers will be automatically enabled for all parent units and for any sibling units starting with the lowest level at which a controller is enabled. Units for which a controller is enabled may be subject to resource control even if they do not have any explicit configuration. Setting `Delegate=` enables any delegated controllers for that unit (see below). The delegatee may then enable controllers for its children as appropriate. In particular, if the delegatee is `systemd` (in the `user@.service` unit), it will repeat the same logic as the system instance and enable controllers for user units which have resource limits configured, and their siblings and parents and parents' siblings. Controllers may be *disabled* for parts of the cgroup hierarchy with `DisableControllers=` (see below).
Enabling and disabling controllers
-.slice / \ /-----/ \--------------\ / \ system.slice user.slice / \ / \ / \ / \ / \ user@42.service user@1000.service / \ Delegate= Delegate=yes a.service b.slice / \ CPUWeight=20 DisableControllers=cpu / \ / \ app.slice session.slice / \ CPUWeight=100 CPUWeight=100 / \ b1.service b2.service CPUWeight=1000 In this hierarchy, the `cpu` controller is enabled for all units shown except `b1.service` and `b2.service`. Because there is no explicit configuration for `system.slice` and `user.slice`, CPU resources will be split equally between them. Similarly, resources are allocated equally between children of `user.slice` and between the child slices beneath `user@1000.service`. Assuming that there is no further configuration of resources or delegation below slices `app.slice` or `session.slice`, the `cpu` controller would not be enabled for units in those slices and CPU resources would be further allocated using other mechanisms, e.g. based on nice levels. The manager for user 42 has delegation enabled without any controllers, i.e. it can manipulate its subtree of the cgroup hierarchy, but without resource control. In the slice `system.slice`, CPU resources are split 1:6 for service `a.service`, and 5:6 for slice `b.slice`, because slice `b.slice` gets the default value of 100 for `cpu.weight` when `CPUWeight=` is not set. `CPUWeight=` setting in service `b2.service` is neutralized by `DisableControllers=` in slice `b.slice`, so the `cpu` controller would not be enabled for services `b1.service` and `b2.service`, and CPU resources would be further allocated using other mechanisms, e.g. based on nice levels.
## Setting resource controls for a group of related units As described in `systemd.unit(5)`, the settings listed here may be set through the main file of a unit and drop-in snippets in `*.d/` directories. The list of directories searched for drop-ins includes names formed by repeatedly truncating the unit name after all dashes. This is particularly convenient to set resource limits for a group of units with similar names. For example, every user gets their own slice `user-nnn.slice`. Drop-ins with local configuration that affect user 1000 may be placed in `/etc/systemd/system/user-1000.slice`, `/etc/systemd/system/user-1000.slice.d/*.conf`, but also `/etc/systemd/system/user-.slice.d/*.conf`. This last directory applies to all user slices. ## See the [New Control Group Interfaces](https://systemd.io/CONTROL_GROUP_INTERFACE) for an introduction on how to make use of resource control APIs from programs. # Implicit Dependencies The following dependencies are implicitly added: - Units with the `Slice=` setting set automatically acquire `Requires=` and `After=` dependencies on the specified slice unit. # Options Units of the types listed above can have settings for resource control configuration: ## CPU Control `CPUWeight=weight`; `StartupCPUWeight=weight` These settings control the `cpu` controller in the unified hierarchy. These options accept an integer value or the special string "idle": - If set to an integer value, assign the specified CPU time weight to the processes executed, if the unified control group hierarchy is used on the system. These options control the `cpu.weight` control group attribute. The allowed range is 1 to 10000. Defaults to unset, but the kernel default is 100. For details about this control group attribute, see [Control Groups v2](https://docs.kernel.org/admin-guide/cgroup-v2.html) and [CFS Scheduler](https://docs.kernel.org/scheduler/sched-design-CFS.html). The available CPU time is split up among all units within one slice relative to their CPU time weight. A higher weight means more CPU time, a lower weight means less. - If set to the special string "idle", mark the cgroup for "idle scheduling", which means that it will get CPU resources only when there are no processes not marked in this way to execute in this cgroup or its siblings. This setting corresponds to the `cpu.idle` cgroup attribute. Note that this value only has an effect on cgroup-v2, for cgroup-v1 it is equivalent to the minimum weight. While `StartupCPUWeight=` applies to the startup and shutdown phases of the system, `CPUWeight=` applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases. Using `StartupCPUWeight=` allows prioritizing specific services at boot-up and shutdown differently than during normal runtime. In addition to the resource allocation performed by the `cpu` controller, the kernel may automatically divide resources based on session-id grouping, see "The autogroup feature" in `sched(7)`. The effect of this feature is similar to the `cpu` controller with no explicit configuration, so users should be careful to not mistake one for the other. `CPUQuota=` This setting controls the `cpu` controller in the unified hierarchy. Assign the specified CPU time quota to the processes executed. Takes a percentage value, suffixed with "%". The percentage specifies how much CPU time the unit shall get at maximum, relative to the total CPU time available on one CPU. Use values \> 100% for allotting CPU time on more than one CPU. This controls the `cpu.max` attribute on the unified control group hierarchy and `cpu.cfs_quota_us` on legacy. For details about these control group attributes, see [Control Groups v2](https://docs.kernel.org/admin-guide/cgroup-v2.html) and [CFS Bandwidth Control](https://docs.kernel.org/scheduler/sched-bwc.html). Setting `CPUQuota=` to an empty value unsets the quota. Example: `CPUQuota=20%` ensures that the executed processes will never get more than 20% CPU time on one CPU. `CPUQuotaPeriodSec=` This setting controls the `cpu` controller in the unified hierarchy. Assign the duration over which the CPU time quota specified by `CPUQuota=` is measured. Takes a time duration value in seconds, with an optional suffix such as "ms" for milliseconds (or "s" for seconds.) The default setting is 100ms. The period is clamped to the range supported by the kernel, which is \[1ms, 1000ms\]. Additionally, the period is adjusted up so that the quota interval is also at least 1ms. Setting `CPUQuotaPeriodSec=` to an empty value resets it to the default. This controls the second field of `cpu.max` attribute on the unified control group hierarchy and `cpu.cfs_period_us` on legacy. For details about these control group attributes, see [Control Groups v2](https://docs.kernel.org/admin-guide/cgroup-v2.html) and [CFS Scheduler](https://docs.kernel.org/scheduler/sched-design-CFS.html). Example: `CPUQuotaPeriodSec=10ms` to request that the CPU quota is measured in periods of 10ms. `AllowedCPUs=`; `StartupAllowedCPUs=` This setting controls the `cpuset` controller in the unified hierarchy. Restrict processes to be executed on specific CPUs. Takes a list of CPU indices or ranges separated by either whitespace or commas. CPU ranges are specified by the lower and upper CPU indices separated by a dash. Setting `AllowedCPUs=` or `StartupAllowedCPUs=` does not guarantee that all of the CPUs will be used by the processes as it may be limited by parent units. The effective configuration is reported as `EffectiveCPUs=`. While `StartupAllowedCPUs=` applies to the startup and shutdown phases of the system, `AllowedCPUs=` applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases. Using `StartupAllowedCPUs=` allows prioritizing specific services at boot-up and shutdown differently than during normal runtime. This setting is supported only with the unified control group hierarchy. ## Memory Accounting and Control `MemoryAccounting=` This setting controls the `memory` controller in the unified hierarchy. Turn on process and kernel memory accounting for this unit. Takes a boolean argument. Note that turning on memory accounting for one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein. The system default for this setting may be controlled with `DefaultMemoryAccounting=` in `systemd-system.conf(5)`. `MemoryMin=bytes`, `MemoryLow=bytes`; `StartupMemoryLow=bytes` These settings control the `memory` controller in the unified hierarchy. Specify the memory usage protection of the executed processes in this unit. When reclaiming memory, the unit is treated as if it was using less memory resulting in memory to be preferentially reclaimed from unprotected units. Using `MemoryLow=` results in a weaker protection where memory may still be reclaimed to avoid invoking the OOM killer in case there is no other reclaimable memory. For a protection to be effective, it is generally required to set a corresponding allocation on all ancestors, which is then distributed between children (with the exception of the root slice). Any `MemoryMin=` or `MemoryLow=` allocation that is not explicitly distributed to specific children is used to create a shared protection for all children. As this is a shared protection, the children will freely compete for the memory. Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system. If assigned the special value `infinity`, all available memory is protected, which may be useful in order to always inherit all of the protection afforded by ancestors. This controls the `memory.min` or `memory.low` control group attribute. For details about this control group attribute, see [Memory Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files). While `StartupMemoryLow=` applies to the startup and shutdown phases of the system, `MemoryMin=` applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases. Using `StartupMemoryLow=` allows prioritizing specific services at boot-up and shutdown differently than during normal runtime. `MemoryHigh=bytes`; `StartupMemoryHigh=bytes` These settings control the `memory` controller in the unified hierarchy. Specify the throttling limit on memory usage of the executed processes in this unit. Memory usage may go above the limit if unavoidable, but the processes are heavily slowed down and memory is taken away aggressively in such cases. This is the main mechanism to control memory usage of a unit. Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system. If assigned the special value `infinity`, no memory throttling is applied. This controls the `memory.high` control group attribute. For details about this control group attribute, see [Memory Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files). The effective configuration is reported as `EffectiveMemoryHigh=` (see also `EffectiveMemoryMax=`). While `StartupMemoryHigh=` applies to the startup and shutdown phases of the system, `MemoryHigh=` applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases. Using `StartupMemoryHigh=` allows prioritizing specific services at boot-up and shutdown differently than during normal runtime. `MemoryMax=bytes`; `StartupMemoryMax=bytes` These settings control the `memory` controller in the unified hierarchy. Specify the absolute limit on memory usage of the executed processes in this unit. If memory usage cannot be contained under the limit, out-of-memory killer is invoked inside the unit. It is recommended to use `MemoryHigh=` as the main control mechanism and use `MemoryMax=` as the last line of defense. Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system. If assigned the special value `infinity`, no memory limit is applied. This controls the `memory.max` control group attribute. For details about this control group attribute, see [Memory Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files). The effective configuration is reported as `EffectiveMemoryMax=` (the value is the most stringent limit of the unit and parent slices and it is capped by physical memory). While `StartupMemoryMax=` applies to the startup and shutdown phases of the system, `MemoryMax=` applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases. Using `StartupMemoryMax=` allows prioritizing specific services at boot-up and shutdown differently than during normal runtime. `MemorySwapMax=bytes`; `StartupMemorySwapMax=bytes` These settings control the `memory` controller in the unified hierarchy. Specify the absolute limit on swap usage of the executed processes in this unit. Takes a swap size in bytes. If the value is suffixed with K, M, G or T, the specified swap size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the specified swap size on the system. If assigned the special value `infinity`, no swap limit is applied. These settings control the `memory.swap.max` control group attribute. For details about this control group attribute, see [Memory Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files). While `StartupMemorySwapMax=` applies to the startup and shutdown phases of the system, `MemorySwapMax=` applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases. Using `StartupMemorySwapMax=` allows prioritizing specific services at boot-up and shutdown differently than during normal runtime. `MemoryZSwapMax=bytes`; `StartupMemoryZSwapMax=bytes` These settings control the `memory` controller in the unified hierarchy. Specify the absolute limit on zswap usage of the processes in this unit. Zswap is a lightweight compressed cache for swap pages. It takes pages that are in the process of being swapped out and attempts to compress them into a dynamically allocated RAM-based memory pool. If the limit specified is hit, no entries from this unit will be stored in the pool until existing entries are faulted back or written out to disk. See the kernel's [Zswap](https://docs.kernel.org/admin-guide/mm/zswap.html) documentation for more details. Takes a size in bytes. If the value is suffixed with K, M, G or T, the specified size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If assigned the special value `infinity`, no limit is applied. These settings control the `memory.zswap.max` control group attribute. For details about this control group attribute, see [Memory Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files). While `StartupMemoryZSwapMax=` applies to the startup and shutdown phases of the system, `MemoryZSwapMax=` applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases. Using `StartupMemoryZSwapMax=` allows prioritizing specific services at boot-up and shutdown differently than during normal runtime. `MemoryZSwapWriteback=` This setting controls the `memory` controller in the unified hierarchy. Takes a boolean argument. Defaults to true if `DefaultMemoryZSwapWriteback=` is not set. When true, pages stored in the Zswap cache are permitted to be written to the backing storage, false otherwise. This allows disabling writeback of swap pages for IO-intensive applications, while retaining the ability to store compressed pages in Zswap. See the kernel's [Zswap](https://docs.kernel.org/admin-guide/mm/zswap.html) documentation for more details. The system default for this setting may be controlled with `DefaultMemoryZSwapWriteback=` in `systemd-system.conf(5)`. `AllowedMemoryNodes=`; `StartupAllowedMemoryNodes=` These settings control the `cpuset` controller in the unified hierarchy. Restrict processes to be executed on specific memory NUMA nodes. Takes a list of memory NUMA nodes indices or ranges separated by either whitespace or commas. Memory NUMA nodes ranges are specified by the lower and upper NUMA nodes indices separated by a dash. Setting `AllowedMemoryNodes=` or `StartupAllowedMemoryNodes=` does not guarantee that all of the memory NUMA nodes will be used by the processes as it may be limited by parent units. The effective configuration is reported as `EffectiveMemoryNodes=`. While `StartupAllowedMemoryNodes=` applies to the startup and shutdown phases of the system, `AllowedMemoryNodes=` applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases. Using `StartupAllowedMemoryNodes=` allows prioritizing specific services at boot-up and shutdown differently than during normal runtime. This setting is supported only with the unified control group hierarchy. `CPUSetPartition=` Sets the `cpuset` partition type for the executed processes. Takes one of `member`, `root`, or `isolated`. This setting controls the `cpuset.cpus.partition` cgroup attribute. When set to `member`, the cpuset operates in normal mode. `root` creates a partition root, which can further divide CPUs among child cgroups. `isolated` provides full CPU isolation, useful for real-time workloads that require dedicated CPU resources without interference from other processes. Defaults to the kernel default, which is `member`. For more details about this control group attribute, see [ Control Groups v2](https://docs.kernel.org/admin-guide/cgroup-v2.html). This setting requires `AllowedCPUs=` to also be set. ## Process Accounting and Control `TasksAccounting=` This setting controls the `pids` controller in the unified hierarchy. Turn on task accounting for this unit. Takes a boolean argument. If enabled, the kernel will keep track of the total number of tasks in the unit and its children. This number includes both kernel threads and userspace processes, with each thread counted individually. Note that turning on tasks accounting for one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein. The system default for this setting may be controlled with `DefaultTasksAccounting=` in `systemd-system.conf(5)`. `TasksMax=N` This setting controls the `pids` controller in the unified hierarchy. Specify the maximum number of tasks that may be created in the unit. This ensures that the number of tasks accounted for the unit (see above) stays below a specific limit. This either takes an absolute number of tasks or a percentage value that is taken relative to the configured maximum number of tasks on the system. If assigned the special value `infinity`, no tasks limit is applied. This controls the `pids.max` control group attribute. For details about this control group attribute, see the [pids controller ](https://docs.kernel.org/admin-guide/cgroup-v2.html#pid). The effective configuration is reported as `EffectiveTasksMax=`. The system default for this setting may be controlled with `DefaultTasksMax=` in `systemd-system.conf(5)`. ## IO Accounting and Control `IOAccounting=` This setting controls the `io` controller in the unified hierarchy. Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly turn it on for all units contained in the same slice and all for its parent slices and the units contained therein. The system default for this setting may be controlled with `DefaultIOAccounting=` in `systemd-system.conf(5)`. `IOWeight=weight`; `StartupIOWeight=weight` These settings control the `io` controller in the unified hierarchy. Set the default overall block I/O weight for the executed processes, if the unified control group hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block I/O weight. This controls the `io.weight` control group attribute, which defaults to 100. For details about this control group attribute, see [IO Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#io-interface-files). The available I/O bandwidth is split up among all units within one slice relative to their block I/O weight. A higher weight means more I/O bandwidth, a lower weight means less. While `StartupIOWeight=` applies to the startup and shutdown phases of the system, `IOWeight=` applies to the later runtime of the system, and if the former is not set also to the startup and shutdown phases. This allows prioritizing specific services at boot-up and shutdown differently than during runtime. `IODeviceWeight=device weight` This setting controls the `io` controller in the unified hierarchy. Set the per-device overall block I/O weight for the executed processes, if the unified control group hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify the device specific weight value, between 1 and 10000. (Example: `/dev/sda 1000`). The file path may be specified as path to a block device node or as any other file, in which case the backing block device of the file system of the file is determined. This controls the `io.weight` control group attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. For details about this control group attribute, see [IO Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#io-interface-files). The specified device node should reference a block device that has an I/O scheduler associated, i.e. should not refer to partition or loopback block devices, but to the originating, physical device. When a path to a regular file or directory is specified it is attempted to discover the correct originating device backing the file system of the specified path. This works correctly only for simpler cases, where the file system is directly placed on a partition or physical block device, or where simple 1:1 encryption using dm-crypt/LUKS is used. This discovery does not cover complex storage and in particular RAID and volume management storage devices. `IOReadBandwidthMax=device bytes`; `IOWriteBandwidthMax=device bytes` These settings control the `io` controller in the unified hierarchy. Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified control group hierarchy is used on the system. This limit is not work-conserving and the executed processes are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of a file path and a bandwidth value (in bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device node, or as any other file in which case the backing block device of the file system of the file is used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the `io.max` control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details about this control group attribute, see [IO Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#io-interface-files). Similar restrictions on block device discovery as for `IODeviceWeight=` apply, see above. `IOReadIOPSMax=device IOPS`; `IOWriteIOPSMax=device IOPS` These settings control the `io` controller in the unified hierarchy. Set the per-device overall block I/O IOs-Per-Second maximum limit for the executed processes, if the unified control group hierarchy is used on the system. This limit is not work-conserving and the executed processes are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of a file path and an IOPS value to specify the device specific IOPS. The file path may be a path to a block device node, or as any other file in which case the backing block device of the file system of the file is used. If the IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS, GigaIOPS, or TeraIOPS, respectively, to the base of 1000. (Example: "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the `io.max` control group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about this control group attribute, see [IO Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#io-interface-files). Similar restrictions on block device discovery as for `IODeviceWeight=` apply, see above. `IODeviceLatencyTargetSec=device target` This setting controls the `io` controller in the unified hierarchy. Set the per-device average target I/O latency for the executed processes, if the unified control group hierarchy is used on the system. Takes a file path and a timespan separated by a space to specify the device specific latency target. (Example: "/dev/sda 25ms"). The file path may be specified as path to a block device node or as any other file, in which case the backing block device of the file system of the file is determined. This controls the `io.latency` control group attribute. Use this option multiple times to set latency target for multiple devices. For details about this control group attribute, see [IO Interface Files](https://docs.kernel.org/admin-guide/cgroup-v2.html#io-interface-files). Implies `IOAccounting=yes`. These settings are supported only if the unified control group hierarchy is used. Similar restrictions on block device discovery as for `IODeviceWeight=` apply, see above. ## Network Accounting and Control `IPAccounting=` Takes a boolean argument. If true, turns on IPv4 and IPv6 network traffic accounting for packets sent or received by the unit. When this option is turned on, all IPv4 and IPv6 sockets created by any process of the unit are accounted for. When this option is used in socket units, it applies to all IPv4 and IPv6 sockets associated with it (including both listening and connection sockets where this applies). Note that for socket-activated services, this configuration setting and the accounting data of the service unit and the socket unit are kept separate, and displayed separately. No propagation of the setting and the collected statistics is done, in either direction. Moreover, any traffic sent or received on any of the socket unit's sockets is accounted to the socket unit — and never to the service unit it might have activated, even if the socket is used by it. The system default for this setting may be controlled with `DefaultIPAccounting=` in `systemd-system.conf(5)`. Note that this functionality is currently only available for system services, not for per-user services. `IPAddressAllow=ADDRESS[/PREFIXLENGTH]…`; `IPAddressDeny=ADDRESS[/PREFIXLENGTH]…` Turn on network traffic filtering for IP packets sent and received over `AF_INET` and `AF_INET6` sockets. Both directives take a space separated list of IPv4 or IPv6 addresses, each optionally suffixed with an address prefix length in bits after a `/` character. If the suffix is omitted, the address is considered a host address, i.e. the filter covers the whole address (32 bits for IPv4, 128 bits for IPv6). The access lists configured with this option are applied to all sockets created by processes of this unit (or in the case of socket units, associated with it). The lists are implicitly combined with any lists configured for any of the parent slice units this unit might be a member of. By default, both access lists are empty. Both ingress and egress traffic is filtered by these settings. In case of ingress traffic the source IP address is checked against these access lists, in case of egress traffic the destination IP address is checked. The following rules are applied in turn: - Access is granted when the checked IP address matches an entry in the `IPAddressAllow=` list. - Otherwise, access is denied when the checked IP address matches an entry in the `IPAddressDeny=` list. - Otherwise, access is granted. In order to implement an allow-listing IP firewall, it is recommended to use a `IPAddressDeny=``any` setting on an upper-level slice unit (such as the root slice `-.slice` or the slice containing all system services `system.slice` – see `systemd.special(7)` for details on these slice units), plus individual per-service `IPAddressAllow=` lines permitting network access to relevant services, and only them. Note that for socket-activated services, the IP access list configured on the socket unit applies to all sockets associated with it directly, but not to any sockets created by the ultimately activated services for it. Conversely, the IP access list configured for the service is not applied to any sockets passed into the service via socket activation. Thus, it is usually a good idea to replicate the IP access lists on both the socket and the service unit. Nevertheless, it may make sense to maintain one list more open and the other one more restricted, depending on the use case. If these settings are used multiple times in the same unit the specified lists are combined. If an empty string is assigned to these settings the specific access list is reset and all previous settings undone. In place of explicit IPv4 or IPv6 address and prefix length specifications a small set of symbolic names may be used. The following names are defined: | Symbolic Name | Definition | Meaning | |---------------|--------------------------|-------------------------------------| | `any` | 0.0.0.0/0 ::/0 | Any host | | `localhost` | 127.0.0.0/8 ::1/128 | All addresses on the local loopback | | `link-local` | 169.254.0.0/16 fe80::/64 | All link-local IP addresses | | `multicast` | 224.0.0.0/4 ff00::/8 | All IP multicasting addresses | Special address/network names Note that these settings might not be supported on some systems (for example if eBPF control group support is not enabled in the underlying kernel or container manager). These settings will have no effect in that case. If compatibility with such systems is desired it is hence recommended to not exclusively rely on them for IP security. `SocketBindAllow=bind-rule`; `SocketBindDeny=bind-rule` Configures restrictions on the ability of unit processes to invoke `bind(2)` on a socket. Both allow and deny rules to be defined that restrict which addresses a socket may be bound to. \ describes socket properties such as \, \ and \. \ := { \[\`:`\]\[\`:`\]\[\\] \| `any` } \ := { `ipv4` \| `ipv6` } \ := { `tcp` \| `udp` } \ := { \ \| \ } An optional \ expects `ipv4` or `ipv6` values. If not specified, a rule will be matched for both IPv4 and IPv6 addresses and applied depending on other socket fields, e.g. \, \. An optional \ expects `tcp` or `udp` transport protocol names. If not specified, a rule will be matched for any transport protocol. An optional \ value must lie within 1…65535 interval inclusively, i.e. dynamic port `0` is not allowed. A range of sequential ports is described by \ := \`-`\, where \ is smaller than or equal to \ and both are within 1…65535 inclusively. A special value `any` can be used to apply a rule to any address family, transport protocol and any port with a positive value. To allow multiple rules assign `SocketBindAllow=` or `SocketBindDeny=` multiple times. To clear the existing assignments pass an empty `SocketBindAllow=` or `SocketBindDeny=` assignment. For each of `SocketBindAllow=` and `SocketBindDeny=`, maximum allowed number of assignments is `128`. - Binding to a socket is allowed when a socket address matches an entry in the `SocketBindAllow=` list. - Otherwise, binding is denied when the socket address matches an entry in the `SocketBindDeny=` list. - Otherwise, binding is allowed. The feature is implemented with `cgroup/bind4` and `cgroup/bind6` cgroup-bpf hooks. Note that these settings apply to any `bind(2)` system call invocation by the unit processes, regardless in which network namespace they are placed. Or in other words: changing the network namespace is not a suitable mechanism for escaping these restrictions on `bind()`. Examples: … # Allow binding IPv6 socket addresses with a port greater than or equal to 10000. [Service] SocketBindAllow=ipv6:10000-65535 SocketBindDeny=any … # Allow binding IPv4 and IPv6 socket addresses with 1234 and 4321 ports. [Service] SocketBindAllow=1234 SocketBindAllow=4321 SocketBindDeny=any … # Deny binding IPv6 socket addresses. [Service] SocketBindDeny=ipv6 … # Deny binding IPv4 and IPv6 socket addresses. [Service] SocketBindDeny=any … # Allow binding only over TCP [Service] SocketBindAllow=tcp SocketBindDeny=any … # Allow binding only over IPv6/TCP [Service] SocketBindAllow=ipv6:tcp SocketBindDeny=any … # Allow binding ports within 10000-65535 range over IPv4/UDP. [Service] SocketBindAllow=ipv4:udp:10000-65535 SocketBindDeny=any … `RestrictNetworkInterfaces=` Takes a comma- or space-separated list of network interface names. This option restricts the network interfaces that processes of this unit can use. By default, processes can only use the network interfaces listed (allow-list). If the first character of the rule is `~`, the effect is inverted: the processes can only use network interfaces not listed (deny-list). Note: to specify an interface with a comma in the name, use quotes. This option can appear multiple times, in which case the network interface names are merged. If the empty string is assigned the set is reset, all prior assignments will have not effect. If you specify both types of this option (i.e. allow-listing and deny-listing), the first encountered will take precedence and will dictate the default action (allow vs deny). Then the next occurrences of this option will add or delete the listed network interface names from the set, depending of its type and the default action. The loopback interface ("lo") is not treated in any special way, you have to configure it explicitly in the unit file. Example 1: allow-list RestrictNetworkInterfaces=eth1 RestrictNetworkInterfaces=eth2 Programs in the unit will be only able to use the eth1 and eth2 network interfaces. Example 2: deny-list RestrictNetworkInterfaces=~eth1 eth2 Programs in the unit will be able to use any network interface but eth1 and eth2. Example 3: mixed RestrictNetworkInterfaces=eth1 eth2 RestrictNetworkInterfaces=~eth1 Programs in the unit will be only able to use the eth2 network interface. `BindNetworkInterface=` Takes the name of a network interface. This option causes every socket created by processes of this unit to be bound to the specified network interface. It is specially useful to confine a process to a VRF, when the program does not offer native support for it. It is equivalent to running the program using `ip vrf exec`. In systems using `nss-resolve`, the interface used for DNS resolution can be chosen by using the `SYSTEMD_NSS_RESOLVE_IFINDEX` environment variable. The feature is implemented with `cgroup/sock_create` cgroup-bpf hooks. Example: [Service] BindNetworkInterface=vrf-mgmt `NFTSet=`\:\:\ This setting provides a method for integrating dynamic cgroup, user and group IDs into firewall rules with [NFT](https://netfilter.org/projects/nftables/index.html) sets. The benefit of using this setting is to be able to use the IDs as selectors in firewall rules easily and this in turn allows more fine grained filtering. NFT rules for cgroup matching use numeric cgroup IDs, which change every time a service is restarted, making them hard to use in systemd environment otherwise. Dynamic and random IDs used by `DynamicUser=` can be also integrated with this setting. This option expects a whitespace separated list of NFT set definitions. Each definition consists of a colon-separated tuple of source type (one of `cgroup`, `user` or `group`), NFT address family (one of `arp`, `bridge`, `inet`, `ip`, `ip6`, or `netdev`), table name and set name. The names of tables and sets must conform to lexicographic restrictions of NFT table names. The type of the element used in the NFT filter must match the type implied by the directive (`cgroup`, `user` or `group`) as shown in the table below. When a control group or a unit is realized, the corresponding ID will be appended to the NFT sets and it will be be removed when the control group or unit is removed. `systemd` only inserts elements to (or removes from) the sets, so the related NFT rules, tables and sets must be prepared elsewhere in advance. Failures to manage the sets will be ignored. | Source type | Description | Corresponding NFT type name | |-------------|------------------|-----------------------------| | `cgroup` | control group ID | `cgroupsv2` | | `user` | user ID | `meta skuid` | | `group` | group ID | `meta skgid` | Defined `source type` values If the firewall rules are reinstalled so that the contents of NFT sets are destroyed, command `systemctl daemon-reload` can be used to refill the sets. Example: [Service] NFTSet=cgroup:inet:filter:my_service user:inet:filter:serviceuser Corresponding NFT rules: table inet filter { set my_service { type cgroupsv2 } set serviceuser { typeof meta skuid } chain x { socket cgroupv2 level 2 @my_service accept drop } chain y { meta skuid @serviceuser accept drop } } ## BPF Programs `IPIngressFilterPath=BPF_FS_PROGRAM_PATH`; `IPEgressFilterPath=BPF_FS_PROGRAM_PATH` Add custom network traffic filters implemented as BPF programs, applying to all IP packets sent and received over `AF_INET` and `AF_INET6` sockets. Takes an absolute path to a pinned BPF program in the BPF virtual filesystem (`/sys/fs/bpf/`). The filters configured with this option are applied to all sockets created by processes of this unit (or in the case of socket units, associated with it). The filters are loaded in addition to filters any of the parent slice units this unit might be a member of as well as any `IPAddressAllow=` and `IPAddressDeny=` filters in any of these units. By default, there are no filters specified. If these settings are used multiple times in the same unit all the specified programs are attached. If an empty string is assigned to these settings the program list is reset and all previous specified programs ignored. If the path \ in `IPIngressFilterPath=` assignment is already being handled by `BPFProgram=` ingress hook, e.g. `BPFProgram=``ingress`:\, the assignment will be still considered valid and the program will be attached to a cgroup. Same for `IPEgressFilterPath=` path and `egress` hook. Note that for socket-activated services, the IP filter programs configured on the socket unit apply to all sockets associated with it directly, but not to any sockets created by the ultimately activated services for it. Conversely, the IP filter programs configured for the service are not applied to any sockets passed into the service via socket activation. Thus, it is usually a good idea, to replicate the IP filter programs on both the socket and the service unit, however it often makes sense to maintain one configuration more open and the other one more restricted, depending on the use case. Note that these settings might not be supported on some systems (for example if eBPF control group support is not enabled in the underlying kernel or container manager). These settings will have no effect in that case. If compatibility with such systems is desired it is hence recommended to attach your filter manually (requires `Delegate=``yes`) instead of using this setting. `BPFProgram=type:program-path` `BPFProgram=` allows attaching custom BPF programs to the cgroup of a unit. (This generalizes the functionality exposed via `IPEgressFilterPath=` and `IPIngressFilterPath=` for other hooks.) Cgroup-bpf hooks in the form of BPF programs loaded to the BPF filesystem are attached with cgroup-bpf attach flags determined by the unit. For details about attachment types and flags see [`bpf.h`](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/include/uapi/linux/bpf.h). Also refer to the general [BPF documentation](https://docs.kernel.org/bpf/). The specification of BPF program consists of a pair of BPF program type and program path in the file system, with `:` as the separator: \:\. The BPF program type is equivalent to the BPF attach type used in `bpftool(8)` It may be one of `egress`, `ingress`, `sock_create`, `sock_ops`, `device`, `bind4`, `bind6`, `connect4`, `connect6`, `post_bind4`, `post_bind6`, `sendmsg4`, `sendmsg6`, `sysctl`, `recvmsg4`, `recvmsg6`, `getsockopt`, or `setsockopt`. The specified program path must be an absolute path referencing a BPF program inode in the bpffs file system (which generally means it must begin with `/sys/fs/bpf/`). If a specified program does not exist (i.e. has not been uploaded to the BPF subsystem of the kernel yet), it will not be installed but unit activation will continue (a warning will be printed to the logs). Setting `BPFProgram=` to an empty value makes previous assignments ineffective. Multiple assignments of the same program type/path pair have the same effect as a single assignment: the program will be attached just once. If BPF `egress` pinned to \ path is already being handled by `IPEgressFilterPath=`, `BPFProgram=` assignment will be considered valid and `BPFProgram=` will be attached to a cgroup. Similarly for `ingress` hook and `IPIngressFilterPath=` assignment. BPF programs passed with `BPFProgram=` are attached to the cgroup of a unit with BPF attach flag `multi`, that allows further attachments of the same \ within cgroup hierarchy topped by the unit cgroup. Examples: BPFProgram=egress:/sys/fs/bpf/egress-hook BPFProgram=bind6:/sys/fs/bpf/sock-addr-hook ## Device Access `DeviceAllow=` Control access to specific device nodes by the executed processes. Takes two space-separated strings: a device node specifier followed by a combination of `r`, `w`, `m` to control *r*eading, *w*riting, or creation of the specific device nodes by the unit (*m*knod), respectively. This functionality is implemented using eBPF filtering. When access to *all* physical devices should be disallowed, `PrivateDevices=` may be used instead. See `systemd.exec(5)`. The device node specifier is either a path to a device node in the file system, starting with `/dev/`, or a string starting with either `char-` or `block-` followed by a device group name, as listed in `/proc/devices`. The latter is useful to allow-list all current and future devices belonging to a specific device group at once. The device group is matched according to filename globbing rules, you may hence use the `*` and `?` wildcards. (Note that such globbing wildcards are not available for device node path specifications!) In order to match device nodes by numeric major/minor, use device node paths in the `/dev/char/` and `/dev/block/` directories. However, matching devices by major/minor is generally not recommended as assignments are neither stable nor portable between systems or different kernel versions. Examples: `/dev/sda5` is a path to a device node, referring to an ATA or SCSI block device. `char-pts` and `char-alsa` are specifiers for all pseudo TTYs and all ALSA sound devices, respectively. `char-cpu/*` is a specifier matching all CPU related device groups. Note that allow lists defined this way should only reference device groups which are resolvable at the time the unit is started. Any device groups not resolvable then are not added to the device allow list. In order to work around this limitation, consider extending service units with a pair of `After=modprobe@xyz.service` and `Wants=modprobe@xyz.service` lines that load the necessary kernel module implementing the device group if missing. Example: … [Unit] Wants=modprobe@loop.service After=modprobe@loop.service [Service] DeviceAllow=block-loop DeviceAllow=/dev/loop-control … `DevicePolicy=auto|closed|strict` Control the policy for allowing device access: `strict` means to only allow types of access that are explicitly specified. `closed` in addition, allows access to standard pseudo devices including `/dev/null`, `/dev/zero`, `/dev/full`, `/dev/random`, and `/dev/urandom`. `auto` in addition, allows access to all devices if no explicit `DeviceAllow=` is present. This is the default. ## Control Group Management `Slice=` The name of the slice unit to place the unit in. Defaults to `system.slice` for all non-instantiated units of all unit types (except for slice units themselves see below). Instance units are by default placed in a subslice of `system.slice` that is named after the template name. This option may be used to arrange systemd units in a hierarchy of slices each of which might have resource settings applied. For units of type slice, the only accepted value for this setting is the parent slice. Since the name of a slice unit implies the parent slice, it is hence redundant to ever set this parameter directly for slice units. Special care should be taken when relying on the default slice assignment in templated service units that have `DefaultDependencies=no` set, see `systemd.service(5)`, section "Default Dependencies" for details. `Delegate=` Turns on delegation of further resource control partitioning to processes of the unit. Units where this is enabled may create and manage their own private subhierarchy of control groups below the control group of the unit itself. For unprivileged services (i.e. those using the `User=` setting) the unit's control group will be made accessible to the relevant user. When enabled the service manager will refrain from manipulating control groups or moving processes below the unit's control group, so that a clear concept of ownership is established: the control group tree at the level of the unit's control group and above (i.e. towards the root control group) is owned and managed by the service manager of the host, while the control group tree below the unit's control group is owned and managed by the unit itself. Takes either a boolean argument or a (possibly empty) list of control group controller names. If true, delegation is turned on, and all supported controllers are enabled for the unit, making them available to the unit's processes for management. If false, delegation is turned off entirely (and no additional controllers are enabled). If set to a list of controllers, delegation is turned on, and the specified controllers are enabled for the unit. Assigning the empty string will enable delegation, but reset the list of controllers, and all assignments prior to this will have no effect. Note that additional controllers other than the ones specified might be made available as well, depending on configuration of the containing slice unit or other units contained in it. Defaults to false. Note that controller delegation to less privileged code is only safe on the unified control group hierarchy. Accordingly, access to the specified controllers will not be granted to unprivileged services on the legacy hierarchy, even when requested. Not all of these controllers are available on all kernels however, and some are specific to the unified hierarchy while others are specific to the legacy hierarchy. Also note that the kernel might support further controllers, which are not covered here yet, as delegation is either not supported at all for them or not defined cleanly. Note that because of the hierarchical nature of cgroup hierarchy, any controllers that are delegated will be enabled for the parent and sibling units of the unit with delegation. For further details on the delegation model consult [Control Group APIs and Delegation](https://systemd.io/CGROUP_DELEGATION). `DelegateSubgroup=` Place unit processes in the specified subgroup of the unit's control group. Takes a valid control group name (not a path!) as parameter, or an empty string to turn this feature off. Defaults to off. The control group name must be usable as filename and avoid conflicts with the kernel's control group attribute files (i.e. `cgroup.procs` is not an acceptable name, since the kernel exposes a native control group attribute file by that name). This option has no effect unless control group delegation is turned on via `Delegate=`, see above. Note that this setting only applies to "main" processes of a unit, i.e. for services to `ExecStart=`, but not for `ExecReload=` and similar. If delegation is enabled, the latter are always placed inside a subgroup named `.control`. The specified subgroup is automatically created (and potentially ownership is passed to the unit's configured user/group) when a process is started in it. This option is useful to avoid manually moving the invoked process into a subgroup after it has been started. Since no processes should live in inner nodes of the control group tree it is almost always necessary to run the main ("supervising") process of a unit that has delegation turned on in a subgroup. `DisableControllers=` Disables controllers from being enabled for a unit's children. If a controller listed is already in use in its subtree, the controller will be removed from the subtree. This can be used to avoid configuration in child units from being able to implicitly or explicitly enable a controller. Defaults to empty. Multiple controllers may be specified, separated by spaces. You may also pass `DisableControllers=` multiple times, in which case each new instance adds another controller to disable. Passing `DisableControllers=` by itself with no controller name present resets the disabled controller list. It may not be possible to disable a controller after units have been started, if the unit or any child of the unit in question delegates controllers to its children, as any delegated subtree of the cgroup hierarchy is unmanaged by systemd. ## Memory Pressure Control `ManagedOOMSwap=auto|kill`; `ManagedOOMMemoryPressure=auto|kill` Specifies how `systemd-oomd.service(8)` will act on this unit's cgroups. Defaults to `auto`. When set to `kill`, the unit becomes a candidate for monitoring by `systemd-oomd`. If the cgroup passes the limits set by `oomd.conf(5)` or the unit configuration, `systemd-oomd` will select a descendant cgroup and send `SIGKILL` to all of the processes under it. You can find more details on candidates and kill behavior at `systemd-oomd.service(8)` and `oomd.conf(5)`. Setting either of these properties to `kill` will also result in `After=` and `Wants=` dependencies on `systemd-oomd.service` unless `DefaultDependencies=no`. When set to `auto`, `systemd-oomd` will not actively use this cgroup's data for monitoring and detection. However, if an ancestor cgroup has one of these properties set to `kill`, a unit with `auto` can still be a candidate for `systemd-oomd` to terminate. `ManagedOOMMemoryPressureLimit=` Overrides the default memory pressure limit set by `oomd.conf(5)` for the cgroup of this unit. Takes a percentage value between 0% and 100%, inclusive. Defaults to 0%, which means to use the default set by `oomd.conf(5)`. This property is ignored unless `ManagedOOMMemoryPressure=``kill`. `ManagedOOMMemoryPressureDurationSec=` Overrides the default memory pressure duration set by `oomd.conf(5)` for the cgroup of this unit. The specified value supports a time unit such as `ms` or `μs`, see `systemd.time(7)` for details on the permitted syntax. Must be set to either empty or a value of at least 1s. Defaults to empty, which means to use the default set by `oomd.conf(5)`. This property is ignored unless `ManagedOOMMemoryPressure=``kill`. `ManagedOOMPreference=none|avoid|omit` Allows deprioritizing or omitting this unit's cgroup as a candidate when `systemd-oomd` needs to act. Requires support for extended attributes (see `xattr(7)`) in order to use `avoid` or `omit`. When calculating candidates to relieve swap usage, `systemd-oomd` will only respect these extended attributes if the unit's cgroup is owned by root. When calculating candidates to relieve memory pressure, `systemd-oomd` will only respect these extended attributes if the unit's cgroup is owned by root, or if the unit's cgroup owner, and the owner of the monitored ancestor cgroup are the same. For example, if `systemd-oomd` is calculating candidates for `-.slice`, then extended attributes set on descendants of `/user.slice/user-1000.slice/user@1000.service/` will be ignored because the descendants are owned by UID 1000, and `-.slice` is owned by UID 0. But, if calculating candidates for `/user.slice/user-1000.slice/user@1000.service/`, then extended attributes set on the descendants would be respected. If this property is set to `avoid`, the service manager will convey this to `systemd-oomd`, which will only select this cgroup if there are no other viable candidates. If this property is set to `omit`, the service manager will convey this to `systemd-oomd`, which will ignore this cgroup as a candidate and will not perform any actions on it. It is recommended to use `avoid` and `omit` sparingly, as it can adversely affect `systemd-oomd`'s kill behavior. Also note that these extended attributes are not applied recursively to cgroups under this unit's cgroup. Defaults to `none` which means `systemd-oomd` will rank this unit's cgroup as defined in `systemd-oomd.service(8)` and `oomd.conf(5)`. `OOMRules=` Takes a space-separated list of OOM ruleset names. The rulesets are defined in `.oomrule` files placed in `/etc/systemd/oomd/rules.d/`, `/run/systemd/oomd/rules.d/`, `/usr/local/lib/systemd/oomd/rules.d/`, or `/usr/lib/systemd/oomd/rules.d/`. When set, `systemd-oomd.service(8)` will monitor this unit's cgroup and evaluate the specified rulesets against it. Each ruleset defines conditions (such as memory pressure or swap usage thresholds) and an action to take when those conditions are met. See `oomd.conf(5)` for details on the available ruleset options. Setting this property will also result in `After=` and `Wants=` dependencies on `systemd-oomd.service` unless `DefaultDependencies=no`. Defaults to an empty list, which means no rulesets are applied. Note that each monitored cgroup incurs a per-interval walk of its descendant cgroup tree, so monitoring very large numbers of cgroups via `OOMRules=` may have a measurable performance impact. `MemoryPressureWatch=` Controls memory pressure monitoring for invoked processes. Takes a boolean or one of `auto` and `skip`. If `no`, tells the service not to watch for memory pressure events, by setting the `$MEMORY_PRESSURE_WATCH` environment variable to the literal string `/dev/null`. If `yes`, tells the service to watch for memory pressure events. This enables memory accounting for the service, and ensures the `memory.pressure` cgroup attribute file is accessible for reading and writing by the service's user. It then sets the `$MEMORY_PRESSURE_WATCH` environment variable for processes invoked by the unit to the file system path to this file. The threshold information configured with `MemoryPressureThresholdSec=` is encoded in the `$MEMORY_PRESSURE_WRITE` environment variable. If the `auto` value is set the protocol is enabled if memory accounting is anyway enabled for the unit, and disabled otherwise. If set to `skip` the logic is neither enabled, nor disabled and the two environment variables are not set. Note that services are free to use the two environment variables, but it is unproblematic if they ignore them. Memory pressure handling must be implemented individually in each service, and usually means different things for different software. For further details on memory pressure handling see [Resource Pressure Handling in systemd](https://systemd.io/PRESSURE). Services implemented using `sd-event(3)` may use `sd_event_add_memory_pressure(3)` to watch for and handle memory pressure events. If not explicit set, defaults to the `DefaultMemoryPressureWatch=` setting in `systemd-system.conf(5)`. `MemoryPressureThresholdSec=` Sets the memory pressure threshold time for memory pressure monitor as configured via `MemoryPressureWatch=`. Specifies the maximum allocation latency before a memory pressure event is signalled to the service, per 2s window. If not specified, defaults to the `DefaultMemoryPressureThresholdSec=` setting in `systemd-system.conf(5)` (which in turn defaults to 200ms). The specified value expects a time unit such as `ms` or `μs`, see `systemd.time(7)` for details on the permitted syntax. `CPUPressureWatch=` Controls CPU pressure monitoring for invoked processes. Takes a boolean or one of `auto` and `skip`. If `no`, tells the service not to watch for CPU pressure events, by setting the `$CPU_PRESSURE_WATCH` environment variable to the literal string `/dev/null`. If `yes`, tells the service to watch for CPU pressure events. This ensures the `cpu.pressure` cgroup attribute file is accessible for reading and writing by the service's user. It then sets the `$CPU_PRESSURE_WATCH` environment variable for processes invoked by the unit to the file system path to this file. The threshold information configured with `CPUPressureThresholdSec=` is encoded in the `$CPU_PRESSURE_WRITE` environment variable. If the `auto` value is set the protocol is enabled if CPU resource controls are configured for the unit (e.g. because `CPUWeight=` or `CPUQuota=` is set), and disabled otherwise. If set to `skip` the logic is neither enabled, nor disabled and the two environment variables are not set. Note that services are free to use the two environment variables, but it is unproblematic if they ignore them. CPU pressure handling must be implemented individually in each service, and usually means different things for different software. Services implemented using `sd-event(3)` may use `sd_event_add_cpu_pressure(3)` to watch for and handle CPU pressure events. If not explicitly set, defaults to the `DefaultCPUPressureWatch=` setting in `systemd-system.conf(5)`. `CPUPressureThresholdSec=` Sets the CPU pressure threshold time for CPU pressure monitor as configured via `CPUPressureWatch=`. Specifies the maximum CPU stall time before a CPU pressure event is signalled to the service, per 2s window. If not specified, defaults to the `DefaultCPUPressureThresholdSec=` setting in `systemd-system.conf(5)` (which in turn defaults to 200ms). The specified value expects a time unit such as `ms` or `μs`, see `systemd.time(7)` for details on the permitted syntax. `IOPressureWatch=` Controls IO pressure monitoring for invoked processes. Takes a boolean or one of `auto` and `skip`. If `no`, tells the service not to watch for IO pressure events, by setting the `$IO_PRESSURE_WATCH` environment variable to the literal string `/dev/null`. If `yes`, tells the service to watch for IO pressure events. This enables IO accounting for the service, and ensures the `io.pressure` cgroup attribute file is accessible for reading and writing by the service's user. It then sets the `$IO_PRESSURE_WATCH` environment variable for processes invoked by the unit to the file system path to this file. The threshold information configured with `IOPressureThresholdSec=` is encoded in the `$IO_PRESSURE_WRITE` environment variable. If the `auto` value is set the protocol is enabled if IO accounting is anyway enabled for the unit (e.g. because `IOWeight=` or `IODeviceWeight=` is set), and disabled otherwise. If set to `skip` the logic is neither enabled, nor disabled and the two environment variables are not set. Note that services are free to use the two environment variables, but it is unproblematic if they ignore them. IO pressure handling must be implemented individually in each service, and usually means different things for different software. Services implemented using `sd-event(3)` may use `sd_event_add_io_pressure(3)` to watch for and handle IO pressure events. If not explicitly set, defaults to the `DefaultIOPressureWatch=` setting in `systemd-system.conf(5)`. `IOPressureThresholdSec=` Sets the IO pressure threshold time for IO pressure monitor as configured via `IOPressureWatch=`. Specifies the maximum IO stall time before an IO pressure event is signalled to the service, per 2s window. If not specified, defaults to the `DefaultIOPressureThresholdSec=` setting in `systemd-system.conf(5)` (which in turn defaults to 200ms). The specified value expects a time unit such as `ms` or `μs`, see `systemd.time(7)` for details on the permitted syntax. ## Coredump Control `CoredumpReceive=` Takes a boolean argument. This setting is used to enable coredump forwarding for containers that belong to this unit's cgroup. Units with `CoredumpReceive=yes` must also be configured with `Delegate=yes`. Defaults to false. When `systemd-coredump` is handling a coredump for a process from a container, if the container's leader process is a descendant of a cgroup with `CoredumpReceive=yes` and `Delegate=yes`, then `systemd-coredump` will attempt to forward the coredump to `systemd-coredump` within the container. See also `systemd-coredump(8)`. # History systemd 252 Options for controlling the Legacy Control Group Hierarchy ([Control Groups version 1](https://docs.kernel.org/admin-guide/cgroup-v1/index.html)) are now fully deprecated: `CPUShares=weight`, `StartupCPUShares=weight`, `MemoryLimit=bytes`, `BlockIOAccounting=`, `BlockIOWeight=weight`, `StartupBlockIOWeight=weight`, `BlockIODeviceWeight=device weight`, `BlockIOReadBandwidth=device bytes`, `BlockIOWriteBandwidth=device bytes`. Please switch to the unified cgroup hierarchy. systemd 258 `CPUAccounting=` setting is deprecated, because it is always available on the unified cgroup hierarchy and such setting has no effect. # See Also `systemd(1)`, `systemd-system.conf(5)`, `systemd.unit(5)`, `systemd.service(5)`, `systemd.slice(5)`, `systemd.scope(5)`, `systemd.socket(5)`, `systemd.mount(5)`, `systemd.swap(5)`, `systemd.exec(5)`, `systemd.directives(7)`, `systemd.special(7)`, `systemd-oomd.service(8)`, The documentation for control groups and specific controllers in the Linux kernel: [Control Groups v2](https://docs.kernel.org/admin-guide/cgroup-v2.html) # systemd.rr systemd systemd.rr 5 systemd.rr Local static DNS resource record definitions `/etc/systemd/resolve/static.d/*.rr`, `/run/systemd/resolve/static.d/*.rr`, `/usr/local/lib/systemd/resolve/static.d/*.rr`, `/usr/lib/systemd/resolve/static.d/*.rr` # Description `*.rr` files may be used to define resource record sets ("RRsets") that shall be resolvable locally, similar in style to address records defined by `/etc/hosts` (see `hosts(5)` for details). These files are read by `systemd-resolved.service(8)`, and are used to synthesize local responses to local queries matching the defined resource record set. These drop-in files are in JSON format. Each file may either contain a single top-level DNS RR object, or an array of one or more DNS RR objects. Each RR object has at least a `key` subobject consisting of a `name` string field and a `type` integer field (which contains the RR type in numeric form). Depending on the chosen type the RR object also has the following fields: - For A/AAAA RRs, the RR object should have an `address` field set to either an IP address formatted as string, or an array consisting of 4 or 16 8-bit unsigned integers for the IP address. - For PTR/NS/CNAME/DNAME RRs, the RR object should have a `name` field set to the name the record shall point to. This JSON serialization of DNS RRs matches the one returned by `resolvectl`. Currently no other RR types are supported. # Examples
Simple A Record
To make local address lookups for `foobar.example.com` resolve to the 192.168.100.1 IPv4 address, create `/run/systemd/resolve/static.d/foobar_example_com.rr`: { "key" : { "type" : 1, "name" : "foobar.example.com" }, "address" : [ 192, 168, 100, 1 ] }
# See Also `systemd(1)`, `systemd-resolved.service(8)`, `resolved.conf(5)`, `hosts(5)`, `resolvectl(1)` # systemd.scope systemd systemd.scope 5 systemd.scope Scope unit configuration `scope.scope` # Description Scope units are not configured via unit configuration files, but are only created programmatically using the bus interfaces of systemd. They are named similar to filenames. A unit whose name ends in `.scope` refers to a scope unit. Scope units manage a set of system processes. Unlike service units, scope units manage externally created processes, and do not fork off processes on their own. The main purpose of scope units is grouping worker processes of a system service for organization and for managing resources. `systemd-run --scope` may be used to easily launch a command in a new scope unit from the command line. See the [New Control Group Interfaces](https://systemd.io/CONTROL_GROUP_INTERFACE) for an introduction on how to make use of scope units from programs. Note that, unlike service units, scope units have no "main" process: all processes in the scope are equivalent. The lifecycle of the scope unit is thus not bound to the lifetime of one specific process, but to the existence of at least one process in the scope. This also means that the exit statuses of these processes are not relevant for the scope unit failure state. Scope units may still enter a failure state, for example due to resource exhaustion or stop timeouts being reached, but not due to programs inside of them terminating uncleanly. Since processes managed as scope units generally remain children of the original process that forked them off, it is also the job of that process to collect their exit statuses and act on them as needed. # Automatic Dependencies ## Implicit Dependencies Implicit dependencies may be added as result of resource control parameters as documented in `systemd.resource-control(5)`. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - Scope units will automatically have dependencies of type `Conflicts=` and `Before=` on `shutdown.target`. These ensure that scope units are removed prior to system shutdown. Only scope units involved with early boot or late system shutdown should disable `DefaultDependencies=` option. # Options Scope files may include a \[Unit\] section, which is described in `systemd.unit(5)`. Scope files may include a \[Scope\] section, which carries information about the scope and the units it contains. A number of options that may be used in this section are shared with other unit types. These options are documented in `systemd.kill(5)` and `systemd.resource-control(5)`. The options specific to the \[Scope\] section of scope units are the following: `OOMPolicy=` `RuntimeMaxSec=` Configures a maximum time for the scope to run. If this is used and the scope has been active for longer than the specified time it is terminated and put into a failure state. Pass `infinity` (the default) to configure no runtime limit. `RuntimeRandomizedExtraSec=` This option modifies `RuntimeMaxSec=` by increasing the maximum runtime by an evenly distributed duration between 0 and the specified value (in seconds). If `RuntimeMaxSec=` is unspecified, then this feature will be disabled. # See Also `systemd(1)`, `systemd-run(1)`, `systemd.unit(5)`, `systemd.resource-control(5)`, `systemd.service(5)`, `systemd.directives(7)`. # systemd.service systemd systemd.service 5 systemd.service Service unit configuration `service.service` # Description A unit configuration file whose name ends in `.service` encodes information about a process controlled and supervised by systemd. This man page lists the configuration options specific to this unit type. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. The service specific configuration options are configured in the \[Service\] section. Additional options are listed in `systemd.exec(5)`, which define the execution environment the commands are executed in, and in `systemd.kill(5)`, which define the way the processes of the service are terminated, and in `systemd.resource-control(5)`, which configure resource control settings for the processes of the service. The `systemd-run(1)` command allows creating `.service` and `.scope` units dynamically and transiently from the command line. # Service Templates It is possible for `systemd` services to take a single argument via the `service@argument.service` syntax. Such services are called "instantiated" services, while the unit definition without the \ parameter is called a "template". An example could be a `dhcpcd@.service` service template which takes a network interface as a parameter to form an instantiated service. Within the service file, this parameter or "instance name" can be accessed with %-specifiers. See `systemd.unit(5)` for details. # Automatic Dependencies ## Implicit Dependencies The following dependencies are implicitly added: - Services with `Type=dbus` set automatically acquire dependencies of type `Requires=` and `After=` on `dbus.socket`. - Socket activated services are automatically ordered after their activating `.socket` units via an automatic `After=` dependency. Services also pull in all `.socket` units listed in `Sockets=` via automatic `Wants=` and `After=` dependencies. Additional implicit dependencies may be added as result of execution and resource control parameters as documented in `systemd.exec(5)` and `systemd.resource-control(5)`. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - Service units will have dependencies of type `Requires=` and `After=` on `sysinit.target`, a dependency of type `After=` on `basic.target` as well as dependencies of type `Conflicts=` and `Before=` on `shutdown.target`. These ensure that normal service units pull in basic system initialization, and are terminated cleanly prior to system shutdown. Only services involved with early boot or late system shutdown should disable this option. - Instanced service units (i.e. service units with an `@` in their name) are assigned by default a per-template slice unit (see `systemd.slice(5)`), named after the template unit, containing all instances of the specific template. This slice is normally stopped at shutdown, together with all template instances. If that is not desired, set `DefaultDependencies=no` in the template unit, and either define your own per-template slice unit file that also sets `DefaultDependencies=no`, or set `Slice=system.slice` (or another suitable slice) in the template unit. Also see `systemd.resource-control(5)`. # Options Service unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. Service unit files must include a \[Service\] section, which carries information about the service and the process it supervises. A number of options that may be used in this section are shared with other unit types. These options are documented in `systemd.exec(5)`, `systemd.kill(5)` and `systemd.resource-control(5)`. The options specific to the \[Service\] section of service units are the following: `Type=` Configures the mechanism via which the service notifies the manager that the service start-up has finished. One of `simple`, `exec`, `forking`, `oneshot`, `dbus`, `notify`, `notify-reload`, or `idle`: - If set to `simple` (the default if `ExecStart=` is specified but neither `Type=` nor `BusName=` are, and credentials are not used), the service manager will consider the unit started immediately after the main service process has been forked off (i.e. immediately after `fork()`, and before various process attributes have been configured and in particular before the new process has called `execve()` to invoke the actual service binary). Typically, `Type=``exec` is the better choice, see below. It is expected that the process configured with `ExecStart=` is the main process of the service. In this mode, if the process offers functionality to other processes on the system, its communication channels should be installed before the service is started up (e.g. sockets set up by systemd, via socket activation), as the service manager will immediately proceed starting follow-up units, right after creating the main service process, and before executing the service's binary. Note that this means `systemctl start` command lines for `simple` services will report success even if the service's binary cannot be invoked successfully (for example because the selected `User=` does not exist, or the service binary is missing). - The `exec` type is similar to `simple`, but the service manager will consider the unit started immediately after the main service binary has been executed. The service manager will delay starting of follow-up units until that point. (Or in other words: `simple` proceeds with further jobs right after `fork()` returns, while `exec` will not proceed before both `fork()` and `execve()` in the service process succeeded.) Note that this means `systemctl start` command lines for `exec` services will report failure when the service's binary cannot be invoked successfully (for example because the selected `User=` does not exist, or the service binary is missing). This type is implied if credentials are used (refer to `LoadCredential=` in `systemd.exec(5)` for details). - If set to `forking`, the manager will consider the unit started immediately after the binary that forked off by the manager exits. *The use of this type is discouraged, use `notify`, `notify-reload`, or `dbus` instead.* It is expected that the process configured with `ExecStart=` will call `fork()` as part of its start-up. The parent process is expected to exit when start-up is complete and all communication channels are set up. The child continues to run as the main service process, and the service manager will consider the unit started when the parent process exits. This is the behavior of traditional UNIX services. If this setting is used, it is recommended to also use the `PIDFile=` option, so that systemd can reliably identify the main process of the service. The manager will proceed with starting follow-up units after the parent process exits. - Behavior of `oneshot` is similar to `exec`; however, the service manager will consider the unit up after the main process exits. It will then start follow-up units. `RemainAfterExit=` is particularly useful for this type of service. `Type=``oneshot` is the implied default if neither `Type=` nor `ExecStart=` are specified. Note that if this option is used without `RemainAfterExit=` the service will never enter `active` unit state, but will directly transition from `activating` to `deactivating` or `dead`, since no process is configured that shall run continuously. In particular this means that after a service of this type ran (and which has `RemainAfterExit=` not set) it will not show up as started afterwards, but as dead. - Behavior of `dbus` is similar to `simple`; however, units of this type must have the `BusName=` specified and the service manager will consider the unit up when the specified bus name has been acquired. This type is the default if `BusName=` is specified. Service units with this option configured implicitly gain dependencies on the `dbus.socket` unit. A service unit of this type is considered to be in the activating state until the specified bus name is acquired. It is considered activated while the bus name is taken. Once the bus name is released the service is considered being no longer functional which has the effect that the service manager attempts to terminate any remaining processes belonging to the service. Services that drop their bus name as part of their shutdown logic thus should be prepared to receive a `SIGTERM` (or whichever signal is configured in `KillSignal=`) as result. - Behavior of `notify` is similar to `exec`; however, it is expected that the service sends a `READY=1` notification message via `sd_notify(3)` or an equivalent call when it has finished starting up. systemd will proceed with starting follow-up units after this notification message has been sent. If this option is used, `NotifyAccess=` (see below) should be set to open access to the notification socket provided by systemd. If `NotifyAccess=` is missing or set to `none`, it will be forcibly set to `main`. If the service supports reloading, and uses a signal to start the reload, using `notify-reload` instead is recommended. - Behavior of `notify-reload` is similar to `notify`, with one difference: the `SIGHUP` UNIX process signal is sent to the service's main process when the service is asked to reload and the manager will wait for a notification about the reload being finished. When initiating the reload process the service is expected to reply with a notification message via `sd_notify(3)` that contains the `RELOADING=1` field in combination with `MONOTONIC_USEC=` set to the current monotonic time (i.e. `CLOCK_MONOTONIC` in `clock_gettime(2)`) in μs, formatted as decimal string. Once reloading is complete another notification message must be sent, containing `READY=1`. Using this service type and implementing this reload protocol is an efficient alternative to providing an `ExecReload=` command for reloading of the service's configuration. The signal to send can be tweaked via `ReloadSignal=`, see below. For `notify-reload` services, systemd verifies that the service's main process has actually installed a handler for the configured reload signal (by default `SIGHUP`). This verification checks for both traditional signal handlers (via `sigaction(2)`) and blocked signals that are typically handled via `signalfd(2)`. This verification is performed at two points: 1. When the service first sends `READY=1` during initial startup. If no signal handler is detected at this point, the service startup is aborted. 2. Immediately before sending the reload signal. If the handler is no longer present, systemd logs a warning but the reload signal is still sent. This prevents accidentally starting services that lack the required signal handler. Services using `notify-reload` must install their reload signal handler before sending the initial `READY=1` notification. - Behavior of `idle` is very similar to `simple`; however, actual execution of the service program is delayed until all active jobs are dispatched. This may be used to avoid interleaving of output of shell services with the status output on the console. Note that this type is useful only to improve console output, it is not useful as a general unit ordering tool, and the effect of this service type is subject to a 5s timeout, after which the service program is invoked anyway. It is recommended to use `Type=``exec` for long-running services, as it ensures that process setup errors (e.g. errors such as a missing service executable, or missing user) are properly tracked. However, as this service type will not propagate the failures in the service's own startup code (as opposed to failures in the preparatory steps the service manager executes before `execve()`) and does not allow ordering of other units against completion of initialization of the service code itself (which for example is useful if clients need to connect to the service through some form of IPC, and the IPC channel is only established by the service itself — in contrast to doing this ahead of time through socket or bus activation or similar), it might not be sufficient for many cases. If so, `notify`, `notify-reload`, or `dbus` (the latter only in case the service provides a D-Bus interface) are the preferred options as they allow service program code to precisely schedule when to consider the service started up successfully and when to proceed with follow-up units. The `notify`/`notify-reload` service types require explicit support in the service codebase (as `sd_notify()` or an equivalent API needs to be invoked by the service at the appropriate time) — if it is not supported, then `forking` is an alternative: it supports the traditional heavy-weight UNIX service start-up protocol. Note that using any type other than `simple` possibly delays the boot process, as the service manager needs to wait for at least some service initialization to complete. (Also note it is generally not recommended to use `idle` or `oneshot` for long-running services.) Note that various service settings (e.g. `User=`, `Group=` through libc NSS) might result in "hidden" blocking IPC calls to other services when used. Sometimes it might be advisable to use the `simple` service type to ensure that the service manager's transaction logic is not affected by such potentially slow operations and hidden dependencies, as this is the only service type where the service manager will not wait for such service execution setup operations to complete before proceeding. `ExitType=` Specifies when the manager should consider the service to be finished. One of `main` or `cgroup`: - If set to `main` (the default), the service manager will consider the unit stopped when the main process, which is determined according to the `Type=`, exits. - If set to `cgroup`, the service will be considered running as long as at least one process in the cgroup has not exited. This option cannot be used with `Type=``oneshot`. It is generally recommended to use `ExitType=``main` when a service has a known forking model and a main process can reliably be determined. `ExitType=` `cgroup` is meant for applications whose forking model is not known ahead of time and which might not have a specific main process. It is well suited for transient or automatically generated services, such as graphical applications inside of a desktop environment. `RemainAfterExit=` Takes a boolean value that specifies whether the service shall be considered active even when all its processes exited. Defaults to `no`. `GuessMainPID=` Takes a boolean value that specifies whether systemd should try to guess the main PID of a service if it cannot be determined reliably. This option is ignored unless `Type=forking` is set and `PIDFile=` is unset because for the other types or with an explicitly configured PID file, the main PID is always known. The guessing algorithm might come to incorrect conclusions if a daemon consists of more than one process. If the main PID cannot be determined, failure detection and automatic restarting of a service will not work reliably. Defaults to `yes`. `PIDFile=` Takes a path referring to the PID file of the service. Usage of this option is recommended for services where `Type=` is set to `forking`. The path specified typically points to a file below `/run/`. If a relative path is specified for system service, then it is hence prefixed with `/run/`, and prefixed with `$XDG_RUNTIME_DIR` if specified in a user service. The service manager will read the PID of the main process of the service from this file after start-up of the service. The service manager will not write to the file configured here, although it will remove the file after the service has shut down if it still exists. The PID file does not need to be owned by a privileged user, but if it is owned by an unprivileged user additional safety restrictions are enforced: the file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and the PID file must refer to a process already belonging to the service. Note that PID files should be avoided in modern projects. Use `Type=notify`, `Type=notify-reload` or `Type=simple` where possible, which does not require use of PID files to determine the main process of a service and avoids needless forking. `BusName=` Takes a D-Bus destination name that this service shall use. This option is mandatory for services where `Type=` is set to `dbus`. It is recommended to always set this property if known to make it easy to map the service name to the D-Bus destination. In particular, `systemctl service-log-level/service-log-target` verbs make use of this. `ExecStart=` Commands that are executed when this service is started. Unless `Type=` is `oneshot`, exactly one command must be given. When `Type=oneshot` is used, this setting may be used multiple times to define multiple commands to execute. If the empty string is assigned to this option, the list of commands to start is reset, prior assignments of this option will have no effect. If no `ExecStart=` is specified, then the service must have `RemainAfterExit=yes` and at least one `ExecStop=` line set. (Services lacking both `ExecStart=` and `ExecStop=` are not valid.) If more than one command is configured, the commands are invoked sequentially in the order they appear in the unit file. If one of the commands fails (and is not prefixed with `-`), other lines are not executed, and the unit is considered failed. Unless `Type=forking` is set, the process started via this command line will be considered the main process of the daemon. `ExecStartPre=`; `ExecStartPost=` Additional commands that are executed before or after the command in `ExecStart=`, respectively. Syntax is the same as for `ExecStart=`. Multiple command lines are allowed, regardless of the service type (i.e. `Type=`), and the commands are executed one after the other, serially. If any of those commands (not prefixed with `-`) fail, the rest are not executed and the unit is considered failed. `ExecStart=` commands are only run after all `ExecStartPre=` commands that were not prefixed with a `-` exit successfully. `ExecStartPost=` commands are only run after the commands specified in `ExecStart=` have been invoked successfully, as determined by `Type=` (i.e. the process has been started for `Type=simple` or `Type=idle`, the last `ExecStart=` process exited successfully for `Type=oneshot`, the initial process exited successfully for `Type=forking`, `READY=1` is sent for `Type=notify`/`Type=notify-reload`, or the `BusName=` has been taken for `Type=dbus`). Note that `ExecStartPre=` may not be used to start long-running processes. All processes forked off by processes invoked via `ExecStartPre=` will be killed before the next service process is run. Note that if any of the commands specified in `ExecStartPre=`, `ExecStart=`, or `ExecStartPost=` fail (and are not prefixed with `-`, see above) or time out before the service is fully up, execution continues with commands specified in `ExecStopPost=`, the commands in `ExecStop=` are skipped. Note that the execution of `ExecStartPost=` is taken into account for the purpose of `Before=`/`After=` ordering constraints. `ExecCondition=` Optional commands that are executed before the commands in `ExecStartPre=`. Syntax is the same as for `ExecStart=`. Multiple command lines are allowed, regardless of the service type (i.e. `Type=`), and the commands are executed one after the other, serially. The behavior is like an `ExecStartPre=` and condition check hybrid: when an `ExecCondition=` command exits with exit code 1 through 254 (inclusive), the remaining commands are skipped and the unit is *not* marked as failed. However, if an `ExecCondition=` command exits with 255 or abnormally (e.g. timeout, killed by a signal, etc.), the unit will be considered failed (and remaining commands will be skipped). Exit code of 0 or those matching `SuccessExitStatus=` will continue execution to the next commands. Note that an `ExecCondition=` skip is *not* equivalent to a unit-level `Condition…=` or `Assert…=` check failing. Because `ExecCondition=` runs as part of the activation transition, a skip causes the unit to transition from `active` to `inactive`, and consequently `SuccessAction=` (see `systemd.unit(5)`) will be honored. By contrast, `Condition…=` directives in the `[Unit]` section prevent activation entirely and therefore do not trigger `SuccessAction=`. The same recommendations about not running long-running processes in `ExecStartPre=` also applies to `ExecCondition=`. `ExecCondition=` will also run the commands in `ExecStopPost=`, as part of stopping the service, in the case of any non-zero or abnormal exits, like the ones described above. `ExecReload=` Commands to execute to trigger a configuration reload in the service. This setting may take multiple command lines, following the same scheme as described for `ExecStart=` above. Use of this setting is optional. Specifier and environment variable substitution is supported here following the same scheme as for `ExecStart=`. One additional, special environment variable is set: if known, `$MAINPID` is set to the main process of the daemon, and may be used for command lines like the following: ExecReload=kill -HUP $MAINPID Note however that reloading a daemon by enqueuing a signal without completion notification (as is the case with the example line above) is usually not a good choice, because this is an asynchronous operation and hence not suitable when ordering reloads of multiple services against each other. It is thus strongly recommended to either use `Type=notify-reload`, or to set `ExecReload=` to a command that not only triggers a configuration reload of the daemon, but also synchronously waits for it to complete. For example, `dbus-broker(1)` uses the following: ExecReload=busctl call org.freedesktop.DBus \ /org/freedesktop/DBus org.freedesktop.DBus \ ReloadConfig This setting can be combined with `Type=notify-reload`, in which case the service main process is signaled after all specified command lines finish execution. Specially, if `RELOADING=1` notification is received before `ExecReload=` completes, the signaling is skipped and the service manager immediately starts listening for `READY=1`. `ExecReloadPost=` Commands to execute after a successful reload operation. Syntax for this setting is exactly the same as `ExecReload=`. `ExecStop=` Commands to execute to stop the service started via `ExecStart=`. This argument takes multiple command lines, following the same scheme as described for `ExecStart=` above. Use of this setting is optional. After the commands configured in this option are run, it is implied that the service is stopped, and any processes remaining for it are terminated according to the `KillMode=` setting (see `systemd.kill(5)`). If this option is not specified, the process is terminated by sending the signal specified in `KillSignal=` or `RestartKillSignal=` when service stop is requested. Specifier and environment variable substitution is supported (including `$MAINPID`, see above). Note that it is usually not sufficient to specify a command for this setting that only asks the service to terminate (for example, by sending some form of termination signal to it), but does not wait for it to do so. Since the remaining processes of the services are killed according to `KillMode=` and `KillSignal=` or `RestartKillSignal=` as described above immediately after the command exited, this may not result in a clean stop. The specified command should hence be a synchronous operation, not an asynchronous one. Note that the commands specified in `ExecStop=` are only executed when the service started successfully first. They are not invoked if the service was never started at all, or in case its start-up failed, for example because any of the commands specified in `ExecStart=`, `ExecStartPre=` or `ExecStartPost=` failed (and were not prefixed with `-`, see above) or timed out. Use `ExecStopPost=` to invoke commands when a service failed to start up correctly and is shut down again. Also note that the stop operation is always performed if the service started successfully, even if the processes in the service terminated on their own or were killed. The stop commands must be prepared to deal with that case. `$MAINPID` will be unset if systemd knows that the main process exited by the time the stop commands are called. Service restart requests are implemented as stop operations followed by start operations. This means that `ExecStop=` and `ExecStopPost=` are executed during a service restart operation. It is recommended to use this setting for commands that communicate with the service requesting clean termination. For post-mortem clean-up steps use `ExecStopPost=` instead. `ExecStopPost=` Additional commands that are executed after the service is stopped. This includes cases where the commands configured in `ExecStop=` were used, where the service does not have any `ExecStop=` defined, or where the service exited unexpectedly. This argument takes multiple command lines, following the same scheme as described for `ExecStart=`. Use of these settings is optional. Specifier and environment variable substitution is supported. Note that – unlike `ExecStop=` – commands specified with this setting are invoked when a service failed to start up correctly and is shut down again. It is recommended to use this setting for clean-up operations that shall be executed even when the service failed to start up correctly. Commands configured with this setting need to be able to operate even if the service failed starting up half-way and left incompletely initialized data around. As the service's processes have likely exited already when the commands specified with this setting are executed they should not attempt to communicate with them. Note that all commands that are configured with this setting are invoked with the result code of the service, as well as the main process' exit code and status, set in the `$SERVICE_RESULT`, `$EXIT_CODE` and `$EXIT_STATUS` environment variables, see `systemd.exec(5)` for details. Note that the execution of `ExecStopPost=` is taken into account for the purpose of `Before=`/`After=` ordering constraints. `RestartSec=` Configures the time to sleep before restarting a service (as configured with `Restart=`). Takes a unit-less value in seconds, or a time span value such as "5min 20s". Defaults to 100ms. `RestartSteps=` Configures the number of exponential steps to take to increase the interval of auto-restarts from `RestartSec=` to `RestartMaxDelaySec=`. Takes a positive integer or 0 to disable it. Defaults to 0. *Hint:* values between 3 and 5 are good choices when exponential backoff is desired. Example: RestartSec=10s RestartSteps=4 RestartMaxDelaySec=160s This will produce the following restart intervals: 10s, 20s, 40s, 80s, 160s, 160s, 160s, etc. Notice the geometric interpolation and the resulting constant ratio between intervals; here it is 2. The formula for the *ratio* is $`(RestartMaxDelaySec / RestartSec)^(1 / RestartSteps)`$. A (repeating) delay equal to `RestartMaxDelaySec=` is always reached after $`RestartSteps + 1`$ steps. This setting is effective only if `RestartMaxDelaySec=` is also set and `RestartSec=` is not zero. `RestartMaxDelaySec=` Configures the longest time to sleep before restarting a service as the interval goes up with `RestartSteps=`. Takes a value in the same format as `RestartSec=`, or `infinity` to disable the setting. Defaults to `infinity`. This setting is effective only if `RestartSteps=` is also set and `RestartSec=` is not zero. `RestartRandomizedDelaySec=` Delay automatic restarts by a randomly selected, evenly distributed amount of time between 0 and the specified time value, added on top of the delay otherwise configured via `RestartSec=` (and `RestartSteps=`/`RestartMaxDelaySec=`, if used). Takes a value in the same format as `RestartSec=`. Defaults to 0, indicating that no randomized delay shall be applied. This setting is useful to stretch out the restarts of similarly configured service instances that fail at the same time, to prevent them from restarting simultaneously and possibly resulting in resource congestion. It is the restart-side analogue of `RandomizedDelaySec=` in `systemd.timer(5)`. `TimeoutStartSec=` Configures the time to wait for start-up. If a daemon service does not signal start-up completion within the configured time, the service will be considered failed and will be shut down again. The precise action depends on the `TimeoutStartFailureMode=` option. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass `infinity` to disable the timeout logic. Defaults to `DefaultTimeoutStartSec=` set in the manager, except when `Type=oneshot` is used, in which case the timeout is disabled by default (see `systemd-system.conf(5)`). If a service of `Type=notify`/`Type=notify-reload` sends `EXTEND_TIMEOUT_USEC=…`, this may cause the start time to be extended beyond `TimeoutStartSec=`. The first receipt of this message must occur before `TimeoutStartSec=` is exceeded, and once the start time has extended beyond `TimeoutStartSec=`, the service manager will allow the service to continue to start, provided the service repeats `EXTEND_TIMEOUT_USEC=…` within the interval specified until the service startup status is finished by `READY=1`. (see `sd_notify(3)`). Note that the start timeout is also applied to service reloads, regardless of whether implemented through `ExecReload=` or via the reload logic enabled via `Type=notify-reload`. If the reload does not complete within the configured time, the reload will be considered failed and the service will continue running with the old configuration. This will not affect the running service, but will be logged and will cause e.g. `systemctl reload` to fail. `TimeoutStopSec=` This option serves two purposes. First, it configures the time to wait for each `ExecStop=` command. If any of them times out, subsequent `ExecStop=` commands are skipped and the service will be terminated by `SIGTERM`. If no `ExecStop=` commands are specified, the service gets the `SIGTERM` immediately. This default behavior can be changed by the `TimeoutStopFailureMode=` option. Second, it configures the time to wait for the service itself to stop. If it does not terminate in the specified time, it will be forcibly terminated by `SIGKILL` (see `KillMode=` in `systemd.kill(5)`). Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass `infinity` to disable the timeout logic. Defaults to `DefaultTimeoutStopSec=` from the manager configuration file (see `systemd-system.conf(5)`). If a service of `Type=notify`/`Type=notify-reload` sends `EXTEND_TIMEOUT_USEC=…`, this may cause the stop time to be extended beyond `TimeoutStopSec=`. The first receipt of this message must occur before `TimeoutStopSec=` is exceeded, and once the stop time has extended beyond `TimeoutStopSec=`, the service manager will allow the service to continue to stop, provided the service repeats `EXTEND_TIMEOUT_USEC=…` within the interval specified, or terminates itself (see `sd_notify(3)`). `TimeoutAbortSec=` This option configures the time to wait for the service to terminate when it was aborted due to a watchdog timeout (see `WatchdogSec=`). If the service has a short `TimeoutStopSec=` this option can be used to give the system more time to write a core dump of the service. Upon expiration the service will be forcibly terminated by `SIGKILL` (see `KillMode=` in `systemd.kill(5)`). The core file will be truncated in this case. Use `TimeoutAbortSec=` to set a sensible timeout for the core dumping per service that is large enough to write all expected data while also being short enough to handle the service failure in due time. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass an empty value to skip the dedicated watchdog abort timeout handling and fall back `TimeoutStopSec=`. Pass `infinity` to disable the timeout logic. Defaults to `DefaultTimeoutAbortSec=` from the manager configuration file (see `systemd-system.conf(5)`). If a service of `Type=notify`/`Type=notify-reload` handles `SIGABRT` itself (instead of relying on the kernel to write a core dump) it can send `EXTEND_TIMEOUT_USEC=…` to extended the abort time beyond `TimeoutAbortSec=`. The first receipt of this message must occur before `TimeoutAbortSec=` is exceeded, and once the abort time has extended beyond `TimeoutAbortSec=`, the service manager will allow the service to continue to abort, provided the service repeats `EXTEND_TIMEOUT_USEC=…` within the interval specified, or terminates itself (see `sd_notify(3)`). `TimeoutSec=` A shorthand for configuring both `TimeoutStartSec=` and `TimeoutStopSec=` to the specified value. `TimeoutStartFailureMode=`; `TimeoutStopFailureMode=` These options configure the action that is taken in case a daemon service does not signal start-up within its configured `TimeoutStartSec=`, respectively if it does not stop within `TimeoutStopSec=`. Takes one of `terminate`, `abort` and `kill`. Both options default to `terminate`. If `terminate` is set the service will be gracefully terminated by sending the signal specified in `KillSignal=` (defaults to `SIGTERM`, see `systemd.kill(5)`). If the service does not terminate the `FinalKillSignal=` is sent after `TimeoutStopSec=`. If `abort` is set, `WatchdogSignal=` is sent instead and `TimeoutAbortSec=` applies before sending `FinalKillSignal=`. This setting may be used to analyze services that fail to start-up or shut-down intermittently. By using `kill` the service is immediately terminated by sending `FinalKillSignal=` without any further timeout. This setting can be used to expedite the shutdown of failing services. `RuntimeMaxSec=` Configures a maximum time for the service to run. If this is used and the service has been active for longer than the specified time it is terminated and put into a failure state. Note that this setting does not have any effect on `Type=oneshot` services, as they terminate immediately after activation completed (use `TimeoutStartSec=` to limit their activation). Pass `infinity` (the default) to configure no runtime limit. If a service of `Type=notify`/`Type=notify-reload` sends `EXTEND_TIMEOUT_USEC=…`, this may cause the runtime to be extended beyond `RuntimeMaxSec=`. The first receipt of this message must occur before `RuntimeMaxSec=` is exceeded, and once the runtime has extended beyond `RuntimeMaxSec=`, the service manager will allow the service to continue to run, provided the service repeats `EXTEND_TIMEOUT_USEC=…` within the interval specified until the service shutdown is achieved by `STOPPING=1` (or termination). (see `sd_notify(3)`). `RuntimeRandomizedExtraSec=` This option modifies `RuntimeMaxSec=` by increasing the maximum runtime by an evenly distributed duration between 0 and the specified value (in seconds). If `RuntimeMaxSec=` is unspecified, then this feature will be disabled. `WatchdogSec=` Configures the watchdog timeout for a service. The watchdog is activated when the start-up is completed. The service must call `sd_notify(3)` regularly with `WATCHDOG=1` (i.e. the "keep-alive ping"). If the time between two such calls is larger than the configured time, then the service is placed in a failed state and it will be terminated with `SIGABRT` (or the signal specified by `WatchdogSignal=`). By setting `Restart=` to `on-failure`, `on-watchdog`, `on-abnormal` or `always`, the service will be automatically restarted. The time configured here will be passed to the executed service process in the `WATCHDOG_USEC=` environment variable. This allows daemons to automatically enable the keep-alive pinging logic if watchdog support is enabled for the service. If this option is used, `NotifyAccess=` (see below) should be set to open access to the notification socket provided by systemd. If `NotifyAccess=` is not set, it will be implicitly set to `main`. Defaults to 0, which disables this feature. The service can check whether the service manager expects watchdog keep-alive notifications. See `sd_watchdog_enabled(3)` for details. `sd_event_set_watchdog(3)` may be used to enable automatic watchdog notification support. `Restart=` Configures whether the service shall be restarted when the service process exits, is killed, or a timeout is reached. The service process may be the main service process, but it may also be one of the processes specified with `ExecStartPre=`, `ExecStartPost=`, `ExecStop=`, `ExecStopPost=`, or `ExecReload=`. When the death of the process is a result of systemd operation (e.g. service stop or restart), the service will not be restarted. Timeouts include missing the watchdog "keep-alive ping" deadline and a service start, reload, and stop operation timeouts. Takes one of `no`, `on-success`, `on-failure`, `on-abnormal`, `on-watchdog`, `on-abort`, or `always`. If set to `no` (the default), the service will not be restarted. If set to `on-success`, it will be restarted only when the service process exits cleanly. In this context, a clean exit means any of the following: - exit code of 0; - for types other than `Type=oneshot`, one of the signals `SIGHUP`, `SIGINT`, `SIGTERM`, or `SIGPIPE`; - exit statuses and signals specified in `SuccessExitStatus=`. If set to `on-failure`, the service will be restarted when the process exits with a non-zero exit code, is terminated by a signal (including on core dump, but excluding the aforementioned four signals), when an operation (such as service reload) times out, and when the configured watchdog timeout is triggered. If set to `on-abnormal`, the service will be restarted when the process is terminated by a signal (including on core dump, excluding the aforementioned four signals), when an operation times out, or when the watchdog timeout is triggered. If set to `on-abort`, the service will be restarted only if the service process exits due to an uncaught signal not specified as a clean exit status. If set to `on-watchdog`, the service will be restarted only if the watchdog timeout for the service expires. If set to `always`, the service will be restarted regardless of whether it exited cleanly or not, got terminated abnormally by a signal, or hit a timeout. Note that `Type=oneshot` services will never be restarted on a clean exit status, i.e. `always` and `on-success` are rejected for them. | Restart settings/Exit causes | `no` | |------------------------------|------| | Clean exit code or signal | | | Unclean exit code | | | Unclean signal | | | Timeout | | | Watchdog | | | Termination due to OOM | | Exit causes and the effect of the `Restart=` settings As exceptions to the setting above, the service will not be restarted if the exit code or signal is specified in `RestartPreventExitStatus=` (see below) or the service is stopped with `systemctl stop` or an equivalent operation. Also, the services will always be restarted if the exit code or signal is specified in `RestartForceExitStatus=` (see below). Note that service restart is subject to unit start rate limiting configured with `StartLimitIntervalSec=` and `StartLimitBurst=`, see `systemd.unit(5)` for details. Setting this to `on-failure` is the recommended choice for long-running services, in order to increase reliability by attempting automatic recovery from errors. For services that shall be able to terminate on their own choice (and avoid immediate restarting), `on-abnormal` is an alternative choice. `RestartMode=` Takes a string value that specifies how a service should restart: - If set to `normal` (the default), the service restarts by going through a failed/inactive state. - If set to `direct`, the service transitions to the activating state directly during auto-restart, skipping failed/inactive state. `ExecStopPost=` is still invoked. `OnSuccess=` and `OnFailure=` are skipped. This option is useful in cases where a dependency can fail temporarily but we do not want these temporary failures to make the dependent units fail. Dependent units are not notified of these temporary failures. - If set to `debug`, the service manager will log messages that are related to this unit at debug level while automated restarts are attempted, until either the service hits the rate limit or it succeeds, and the `$DEBUG_INVOCATION=1` environment variable will be set for the unit. This is useful to be able to get additional information when a service fails to start, without needing to proactively or permanently enable debug level logging in systemd, which is very verbose. This is otherwise equivalent to `normal` mode. `SuccessExitStatus=` Takes a list of exit status definitions that, when returned by the main service process, will be considered successful termination, in addition to the normal successful exit status 0 and, except for `Type=oneshot`, the signals `SIGHUP`, `SIGINT`, `SIGTERM`, and `SIGPIPE`. Exit status definitions can be numeric termination statuses, termination status names, or termination signal names, separated by spaces. See the Process Exit Codes section in `systemd.exec(5)` for a list of termination status names (for this setting only the part without the `EXIT_` or `EX_` prefix should be used). See `signal(7)` for a list of signal names. Note that this setting does not change the mapping between numeric exit statuses and their names, i.e. regardless how this setting is used 0 will still be mapped to `SUCCESS` (and thus typically shown as `0/SUCCESS` in tool outputs) and 1 to `FAILURE` (and thus typically shown as `1/FAILURE`), and so on. It only controls what happens as effect of these exit statuses, and how it propagates to the state of the service as a whole. This option may appear more than once, in which case the list of successful exit statuses is merged. If the empty string is assigned to this option, the list is reset, all prior assignments of this option will have no effect.
A service with the `SuccessExitStatus=` setting
SuccessExitStatus=TEMPFAIL 250 SIGKILL Exit status 75 (`TEMPFAIL`), 250, and the termination signal `SIGKILL` are considered clean service terminations.
Note: `systemd-analyze exit-status` may be used to list exit statuses and translate between numerical status values and names. `RestartPreventExitStatus=` Takes a list of exit status definitions that, when returned by the main service process, will prevent automatic service restarts, regardless of the restart setting configured with `Restart=`. Exit status definitions can be numeric termination statuses, termination status names, or termination signal names, separated by spaces. Defaults to the empty list, so that, by default, no exit status is excluded from the configured restart logic.
A service with the `RestartPreventExitStatus=` setting
RestartPreventExitStatus=TEMPFAIL 250 SIGKILL Exit status 75 (`TEMPFAIL`), 250, and the termination signal `SIGKILL` will not result in automatic service restarting.
This option may appear more than once, in which case the list of restart-preventing statuses is merged. If the empty string is assigned to this option, the list is reset and all prior assignments of this option will have no effect. Note that this setting has no effect on processes configured via `ExecStartPre=`, `ExecStartPost=`, `ExecStop=`, `ExecStopPost=` or `ExecReload=`, but only on the main service process, i.e. either the one invoked by `ExecStart=` or (depending on `Type=`, `PIDFile=`, …) the otherwise configured main process. `RestartForceExitStatus=` Takes a list of exit status definitions that, when returned by the main service process, will force automatic service restarts, regardless of the restart setting configured with `Restart=`. The argument format is similar to `RestartPreventExitStatus=`. Note that for `Type=oneshot` services, a success exit status will prevent them from auto-restarting, no matter whether the corresponding exit statuses are listed in this option or not. `RootDirectoryStartOnly=` Takes a boolean argument. If true, the root directory, as configured with the `RootDirectory=` option (see `systemd.exec(5)` for more information), is only applied to the process started with `ExecStart=`, and not to the various other `ExecStartPre=`, `ExecStartPost=`, `ExecReload=`, `ExecReloadPost=`, `ExecStop=`, and `ExecStopPost=` commands. If false, the setting is applied to all configured commands the same way. Defaults to false. `NonBlocking=` Set the `O_NONBLOCK` flag for all file descriptors passed via socket-based activation. If true, all file descriptors \>= 3 (i.e. all except stdin, stdout, stderr), excluding those passed in via the file descriptor storage logic (see `FileDescriptorStoreMax=` for details), will have the `O_NONBLOCK` flag set and hence are in non-blocking mode. This option is only useful in conjunction with a socket unit, as described in `systemd.socket(5)` and has no effect on file descriptors which were previously saved in the file-descriptor store for example. Defaults to false. Note that if the same socket unit is configured to be passed to multiple service units (via the `Sockets=` setting, see below), and these services have different `NonBlocking=` configurations, the precise state of `O_NONBLOCK` depends on the order in which these services are invoked, and will possibly change after service code already took possession of the socket file descriptor, simply because the `O_NONBLOCK` state of a socket is shared by all file descriptors referencing it. Hence it is essential that all services sharing the same socket use the same `NonBlocking=` configuration, and do not change the flag in service code either. `NotifyAccess=` Controls access to the service status notification socket, as accessible via the `sd_notify(3)` call. Takes one of `none` (the default), `main`, `exec` or `all`. If `none`, no daemon status updates are accepted from the service processes, all status update messages are ignored. If `main`, only service updates sent from the main process of the service are accepted. If `exec`, only service updates sent from any of the main or control processes originating from one of the `Exec*=` commands are accepted. If `all`, all services updates from all members of the service's control group are accepted. This option should be set to open access to the notification socket when using `Type=notify`/`Type=notify-reload` or `WatchdogSec=` (see above). If those options are used but `NotifyAccess=` is not configured, it will be implicitly set to `main`. Note that `sd_notify()` notifications may be attributed to units correctly only if either the sending process is still around at the time PID 1 processes the message, or if the sending process is explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked off the process, i.e. on all processes that match `main` or `exec`. Conversely, if an auxiliary process of the unit sends an `sd_notify()` message and immediately exits, the service manager might not be able to properly attribute the message to the unit, and thus will ignore it, even if `NotifyAccess=``all` is set for it. Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications to units correctly, `sd_notify_barrier()` may be used. This call acts as a synchronization point and ensures all notifications sent before this call have been picked up by the service manager when it returns successfully. Use of `sd_notify_barrier()` is needed for clients which are not invoked by the service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the unit. `Sockets=` Specifies the name of the socket units this service shall inherit socket file descriptors from when the service is started. Normally, it should not be necessary to use this setting, as all socket file descriptors whose unit shares the same name as the service (subject to the different unit name suffix of course) are passed to the spawned process. Note that the same socket file descriptors may be passed to multiple processes simultaneously. Also note that a different service may be activated on incoming socket traffic than the one which is ultimately configured to inherit the socket file descriptors. Or, in other words: the `Service=` setting of `.socket` units does not have to match the inverse of the `Sockets=` setting of the `.service` it refers to. This option may appear more than once, in which case the list of socket units is merged. Note that once set, clearing the list of sockets again (for example, by assigning the empty string to this option) is not supported. `FileDescriptorStoreMax=` Configure how many file descriptors may be stored in the service manager for the service using `sd_pid_notify_with_fds(3)`'s `FDSTORE=1` messages. This is useful for implementing services that can restart after an explicit request or a crash without losing state. Any open sockets and other file descriptors which should not be closed during the restart may be stored this way. Application state can either be serialized to a file in `RuntimeDirectory=`, or stored in a `memfd_create(2)` memory file descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service manager. All file descriptors passed to the service manager from a specific service are passed back to the service's main process on the next service restart (see `sd_listen_fds(3)` for details about the precise protocol used and the order in which the file descriptors are passed). Any file descriptors passed to the service manager are automatically closed when `POLLHUP` or `POLLERR` is seen on them, or when the service is fully stopped and no job is queued or being executed for it (the latter can be tweaked with `FileDescriptorStorePreserve=`, see below). If this option is used, `NotifyAccess=` (see above) should be set to open access to the notification socket provided by systemd. If `NotifyAccess=` is not set, it will be implicitly set to `main`. The `fdstore` command of `systemd-analyze(1)` may be used to list the current contents of a service's file descriptor store. Note that the service manager will only pass file descriptors contained in the file descriptor store to the service's own processes, never to other clients via IPC or similar. However, it does allow unprivileged clients to query the list of currently open file descriptors of a service. Sensitive data may hence be safely placed inside the referenced files, but should not be attached to the metadata (e.g. included in filenames) of the stored file descriptors. If this option is set to a non-zero value the `$FDSTORE` environment variable will be set for processes invoked for this service. See `systemd.exec(5)` for details. For further information on the file descriptor store see the [File Descriptor Store](https://systemd.io/FILE_DESCRIPTOR_STORE) overview. `FileDescriptorStorePreserve=` Takes one of `no`, `yes`, `restart`, `on-success` and controls when to release the service's file descriptor store (i.e. when to close the contained file descriptors, if any). If set to `no` the file descriptor store is automatically released when the service is stopped; if `restart` (the default) it is kept around as long as the unit is neither inactive nor failed, or a job is queued for the service, or the service is expected to be restarted. If `yes` the file descriptor store is kept around and garbage collection of the unit is disabled. The latter is useful to keep entries in the file descriptor store pinned until the unit is removed, the service manager exits, or the file descriptors get `EPOLLHUP` or `EPOLLERR`. If `on-success` the behaviour is identical to `yes`, except that the file descriptor store is discarded if the unit enters the permanent `failed` state (i.e. once all automated restart attempts driven by `Restart=` have been exhausted). The store is preserved across the transitionary failed states that precede each individual auto-restart attempt. When set to `yes` or `on-success`, and the service is itself running under another service manager (e.g. a service of `user@.service`, or a payload inside `systemd-nspawn(1)`), file descriptors pushed into the store are also forwarded one level up via the enveloping manager's `$NOTIFY_SOCKET`, tagged with the originating unit id, so that they are preserved across restarts of the inner manager and handed back to the originating unit when it is started again. For this to take effect, the enveloping unit must itself enable `FileDescriptorStoreMax=` and a non-`no`/`restart` value for `FileDescriptorStorePreserve=`. See the [File Descriptor Store](https://systemd.io/FILE_DESCRIPTOR_STORE) overview for details. Setting this to `yes` or `on-success` also ensures the file descriptor store is kept loaded across a `kexec`-based reboot on kernels supporting the [Live Update Orchestrator](https://docs.kernel.org/userspace-api/liveupdate.html), so that compatible file descriptors (such as `memfd_create(2)`) are preserved and handed back to the service on the other side. See the [File Descriptor Store](https://systemd.io/FILE_DESCRIPTOR_STORE) overview for details. Use `systemctl clean --what=fdstore …` to release the file descriptor store explicitly. `LUOSession=` Takes a whitespace-separated list of names. For each name, when the service is started the service manager creates a LUO session via the [Live Update Orchestrator](https://docs.kernel.org/userspace-api/liveupdate.html) (LUO, i.e. `/dev/liveupdate`) and hands the resulting session file descriptor to the service through the file descriptor store, using the configured name as its `FDNAME=`. The session is hence passed to the service's processes via `sd_listen_fds(3)`, like any other file descriptor store entry. The service may then preserve additional file descriptors (such as `memfd_create(2)` memory file descriptors) in the session, which survive a `kexec`-based reboot and can be retrieved again on the other side. A session is only handed out if one with the same name is not already present in the service's file descriptor store. This way a session handed out on first start, or restored across a `kexec`, is reused on the next start rather than replaced. The kernel-level session name is derived deterministically from the unit name and the configured name, so that it remains stable and unique, and it fits within the length limit imposed by the kernel. This setting implies `FileDescriptorStoreMax=` is set to at least the number of configured sessions. To ensure the sessions are kept pinned and preserved across a `kexec`, combine this with `FileDescriptorStorePreserve=yes` (see above). If `/dev/liveupdate` is not available no session is handed out, and the service is started normally. This setting may be specified more than once, in which case the lists are combined. If the empty string is assigned the list is reset and all prior assignments have no effect. For further information on the file descriptor store see the [File Descriptor Store](https://systemd.io/FILE_DESCRIPTOR_STORE) overview. `USBFunctionDescriptors=` Configure the location of a file containing [USB FunctionFS](https://docs.kernel.org/usb/functionfs.html) descriptors, for implementation of USB gadget functions. This is used only in conjunction with a socket unit with `ListenUSBFunction=` configured. The contents of this file are written to the `ep0` file after it is opened. `USBFunctionStrings=` Configure the location of a file containing USB FunctionFS strings. Behavior is similar to `USBFunctionDescriptors=` above. `OOMPolicy=` Configure the out-of-memory (OOM) killing policy for the kernel and the userspace OOM killer `systemd-oomd.service(8)`. On Linux, when memory becomes scarce to the point that the kernel has trouble allocating memory for itself, it might decide to kill a running process in order to free up memory and reduce memory pressure. Note that `systemd-oomd.service` is a more flexible solution that aims to prevent out-of-memory situations for the userspace too, not just the kernel, by attempting to terminate services earlier, before the kernel would have to act. This setting takes one of `continue`, `stop` or `kill`. If set to `continue` and a process in the unit is killed by the OOM killer, this is logged but the unit continues running. If set to `stop` the event is logged and the unit's processes are terminated cleanly by the service manager. If set to `kill` and one of the unit's processes is killed by the OOM killer the kernel is instructed to kill all remaining processes of the unit too, by setting the `memory.oom.group` attribute to `1`; also see kernel page [Control Group v2](https://docs.kernel.org/admin-guide/cgroup-v2.html). In case of both `stop` and `kill`, the service ultimately ends up in the `oom-kill` failed state after which `Restart=` may apply. Defaults to the setting `DefaultOOMPolicy=` in `systemd-system.conf(5)` is set to, except for units where `Delegate=` is turned on, where it defaults to `continue`. Use the `OOMScoreAdjust=` setting to configure whether processes of the unit shall be considered preferred or less preferred candidates for process termination by the Linux OOM killer logic. See `systemd.exec(5)` for details. This setting also applies to `systemd-oomd.service(8)`. Similarly to the kernel OOM kills performed by the kernel, this setting determines the state of the unit after `systemd-oomd` kills a cgroup associated with it. `OpenFile=` Takes an argument of the form `path:fd-name:options`, where: - `path` is a path to a file or an `AF_UNIX` socket in the file system; - `fd-name` is a name that will be associated with the file descriptor; the name may contain any ASCII character, but must exclude control characters and ":", and must be at most 255 characters in length; it is optional and, if not provided, defaults to the file name; - `options` is a comma-separated list of access options; possible values are `read-only`, `append`, `truncate`, `graceful`; if not specified, files will be opened in `rw` mode; if `graceful` is specified, errors during file/socket opening are ignored. Specifying the same option several times is treated as an error. The file or socket is opened by the service manager and the file descriptor is passed to the service. If the path is a socket, we call `connect()` on it. See `sd_listen_fds(3)` for more details on how to retrieve these file descriptors. This setting is useful to allow services to access files/sockets that they cannot access themselves (due to running in a separate mount namespace, not having privileges, ...). This setting can be specified multiple times, in which case all the specified paths are opened and the file descriptors passed to the service. If the empty string is assigned, the entire list of open files defined prior to this is reset. `ReloadSignal=` Configures the UNIX process signal to send to the service's main process when asked to reload the service's configuration. Defaults to `SIGHUP`. This option has no effect unless `Type=``notify-reload` is used, see above. `RefreshOnReload=` Takes a boolean argument, or a list of resources defined in `systemd.exec(5)`. Possible values are `extensions` and `credentials`, separated by space. Prepending the list with a single tilde character (`~`) inverts the effect. Defaults to `extensions`. An empty assignment resets the list to default. If enabled, the corresponding resources (`ExtensionImages=`/`ExtensionDirectories=` for `extensions` and `LoadCredential=`/`ImportCredential=`/ `SetCredential=` (along with their `Encrypted` counterparts) for `credentials`) will be refreshed on service reload. If `yes`, all resources listed above that are used by the service shall be refreshed. Specially, if this option is set explicitly, and the respective resources are in use, the service may be reloaded without any actual reload mechanism (`ExecReload=` or `Type=notify-reload`) for notifying the main process, in which case the reload is considered complete immediately after refreshing. Check `systemd.unit(5)`, `systemd.exec(5)`, and `systemd.kill(5)` for more settings. # Command lines This section describes command line parsing and variable and specifier substitutions for `ExecStart=`, `ExecStartPre=`, `ExecStartPost=`, `ExecReload=`, `ExecStop=`, `ExecStopPost=`, and `ExecCondition=` options. Multiple command lines may be specified by using the relevant setting multiple times. Each command line is unquoted using the rules described in "Quoting" section in `systemd.syntax(7)`. The first item becomes the command to execute, and the subsequent items the arguments. This syntax is inspired by shell syntax, but only the meta-characters and expansions described in the following paragraphs are understood, and the expansion of variables is different. Specifically, redirection using `<`, `<<`, `>`, and `>>`, pipes using `|`, running programs in the background using `&`, and *other elements of shell syntax are not supported*. The command to execute may contain spaces, but control characters are not allowed. Each command may be prefixed with a number of special characters: | Prefix | Effect | |----|----| | `@` | If the executable path is prefixed with `@`, the second specified token will be passed as `argv[0]` to the executed process (instead of the actual filename), followed by the further arguments specified, unless `|` is also specified, in which case it enables login shell semantics for the shell spawned by prefixing `-` to `argv[0]`. | | `-` | If the executable path is prefixed with `-`, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is recorded, but has no further effect and is considered equivalent to success. | | `:` | If the executable path is prefixed with `:`, environment variable substitution (as described below this table) is not applied. | | `+` | If the executable path is prefixed with `+` then the process is executed with full privileges. In this mode privilege restrictions configured with `User=`, `Group=`, `CapabilityBoundingSet=` or the various file system namespacing options (such as `PrivateDevices=`, `PrivateTmp=`) are not applied to the invoked command line (but still affect any other `ExecStart=`, `ExecStop=`, … lines). Resource limits configured with `LimitCPU=`, `LimitCORE=`, `LimitNOFILE=` and the other resource limit settings described in `systemd.exec(5)` (including the defaults set with `DefaultLimitCPU=`, `DefaultLimitCORE=`, … in `systemd-system.conf(5)`) are not applied either, and the invoked command inherits the resource limits of the service manager itself. However, note that this will not bypass options that apply to the whole control group, such as `DevicePolicy=`, see `systemd.resource-control(5)` for the full list. | | `!` | Similar to the `+` character discussed above this permits invoking command lines with elevated privileges. However, unlike `+` the `!` character exclusively alters the effect of `User=`, `Group=` and `SupplementaryGroups=`, i.e. only the stanzas that affect user and group credentials. Note that this setting may be combined with `DynamicUser=`, in which case a dynamic user/group pair is allocated before the command is invoked, but credential changing is left to the executed process itself. | | `|` | If `|` is specified standalone as executable path, invoke the default shell of `User=`. If specified as a prefix, use the shell (`-c`) to spawn the executable. When `@` is used in conjunction, `argv[0]` of shell will be prefixed with `-` to enable login shell semantics. | Special executable prefixes `@`, `|`, `-`, `:`, and one of `+`/`!` may be used together and they can appear in any order. However, `+` and `!` may not be specified at the same time. For each command, the first argument must be either an absolute path to an executable or a simple file name without any slashes. If the command is not a full (absolute) path, it will be resolved to a full path using a fixed search path determined at compilation time. Searched directories include `/usr/local/bin/`, `/usr/bin/`, and their `sbin/` counterparts (only on systems using split `bin/` and `sbin/`). It is thus safe to use just the executable name in case of executables located in any of the "standard" directories, and an absolute path must be used in other cases. Hint: this search path may be queried using `systemd-path search-binaries-default`. The command line accepts `%` specifiers as described in `systemd.unit(5)`. An argument solely consisting of `;` must be escaped, i.e. specified as `\;`. Basic environment variable substitution is supported. Use `${FOO}` as part of a word, or as a word of its own, on the command line, in which case it will be erased and replaced by the exact value of the environment variable (if any) including all whitespace it contains, always resulting in exactly a single argument. Use `$FOO` as a separate word on the command line, in which case it will be replaced by the value of the environment variable split at whitespace, resulting in zero or more arguments. For this type of expansion, quotes are respected when splitting into words, and afterwards removed. Example: Environment="ONE=one" 'TWO=two two' ExecStart=echo $ONE $TWO ${TWO} This will execute `/bin/echo` with four arguments: `one`, `two`, `two`, and `two two`. Example: Environment=ONE='one' "TWO='two two' too" THREE= ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} ExecStart=/bin/echo $ONE $TWO $THREE This results in `/bin/echo` being called twice, the first time with arguments `one`, `'two two' too`, ``, and the second time with arguments `one`, `two two`, `too`. Unless for commands with the special executable prefix `:`, to pass a literal dollar sign, use `$$`. Variables whose value is not known at expansion time are treated as empty strings. Note that the first argument (i.e. the program to execute) may not be a variable. Variables to be used in this fashion may be defined through `Environment=` and `EnvironmentFile=`. In addition, variables listed in the section "Environment variables in spawned processes" in `systemd.exec(5)`, which are considered "static configuration", may be used (this includes e.g. `$USER`, but not `$TERM`). Note that shell command lines are not directly supported, and `|` invokes the user's default shell which isn't deterministic. It's recommended to specify a shell implementation explicitly if portability is desired. Example: ExecStart=sh -c 'dmesg | tac' Example: ExecStart=echo one ExecStart=echo "two two" This will execute `echo` two times, each time with one argument: `one` and `two two`, respectively. Because two commands are specified, `Type=oneshot` must be used. Example: Type=oneshot ExecStart=:echo $USER ExecStart=-false ExecStart=+:@true $TEST This will execute `/usr/bin/echo` with the literal argument `$USER` (`:` suppresses variable expansion), and then `/usr/bin/false` (the return value will be ignored because `-` suppresses checking of the return value), and `/usr/bin/true` (with elevated privileges, with `$TEST` as `argv[0]`). Example: ExecStart=echo / >/dev/null & \; \ ls This will execute `echo` with five arguments: `/`, `>/dev/null`, `&`, `;`, and `ls`. # Examples
Simple service
The following unit file creates a service that will execute `/usr/sbin/foo-daemon`. Since no `Type=` is specified, the default `Type=``simple` will be assumed. systemd will assume the unit to be started immediately after the program has begun executing. [Unit] Description=Foo [Service] ExecStart=/usr/sbin/foo-daemon [Install] WantedBy=multi-user.target Note that systemd assumes here that the process started by systemd will continue running until the service terminates. If the program daemonizes itself (i.e. forks), please use `Type=``forking` instead. Since no `ExecStop=` was specified, systemd will send SIGTERM to all processes started from this service, and after a timeout also SIGKILL. This behavior can be modified, see `systemd.kill(5)` for details. Note that this unit type does not include any type of notification when a service has completed initialization. For this, you should use other unit types, such as `Type=``notify`/`Type=``notify-reload` if the service understands systemd's notification protocol, `Type=``forking` if the service can background itself or `Type=``dbus` if the unit acquires a DBus name once initialization is complete. See below.
Oneshot service
Sometimes, units should just execute an action without keeping active processes, such as a filesystem check or a cleanup action on boot. For this, `Type=``oneshot` exists. Units of this type will wait until the process specified terminates and then fall back to being inactive. The following unit will perform a cleanup action: [Unit] Description=Cleanup old Foo data [Service] Type=oneshot ExecStart=/usr/sbin/foo-cleanup [Install] WantedBy=multi-user.target Note that systemd will consider the unit to be in the state "starting" until the program has terminated, so ordered dependencies will wait for the program to finish before starting themselves. The unit will revert to the "inactive" state after the execution is done, never reaching the "active" state. That means another request to start the unit will perform the action again. `Type=``oneshot` are the only service units that may have more than one `ExecStart=` specified. For units with multiple commands (`Type=oneshot`), all commands will be run again. For `Type=oneshot`, `Restart=``always` and `Restart=``on-success` are *not* allowed.
Stoppable oneshot service
Similarly to the oneshot services, there are sometimes units that need to execute a program to set up something and then execute another to shut it down, but no process remains active while they are considered "started". Network configuration can sometimes fall into this category. Another use case is if a oneshot service shall not be executed each time when they are pulled in as a dependency, but only the first time. For this, systemd knows the setting `RemainAfterExit=``yes`, which causes systemd to consider the unit to be active if the start action exited successfully. This directive can be used with all types, but is most useful with `Type=``oneshot` and `Type=``simple`. With `Type=``oneshot`, systemd waits until the start action has completed before it considers the unit to be active, so dependencies start only after the start action has succeeded. With `Type=``simple`, dependencies will start immediately after the start action has been dispatched. The following unit provides an example for a simple static firewall. [Unit] Description=Simple firewall [Service] Type=oneshot RemainAfterExit=yes ExecStart=/usr/local/sbin/simple-firewall-start ExecStop=/usr/local/sbin/simple-firewall-stop [Install] WantedBy=multi-user.target Since the unit is considered to be running after the start action has exited, invoking `systemctl start` on that unit again will cause no action to be taken.
Traditional forking services
Many traditional daemons/services background (i.e. fork, daemonize) themselves when starting. Set `Type=``forking` in the service's unit file to support this mode of operation. systemd will consider the service to be in the process of initialization while the original program is still running. Once it exits successfully and at least a process remains (and `RemainAfterExit=``no`), the service is considered started. Often, a traditional daemon only consists of one process. Therefore, if only one process is left after the original process terminates, systemd will consider that process the main process of the service. In that case, the `$MAINPID` variable will be available in `ExecReload=`, `ExecStop=`, etc. In case more than one process remains, systemd will be unable to determine the main process, so it will not assume there is one. In that case, `$MAINPID` will not expand to anything. However, if the process decides to write a traditional PID file, systemd will be able to read the main PID from there. Please set `PIDFile=` accordingly. Note that the daemon should write that file before finishing with its initialization. Otherwise, systemd might try to read the file before it exists. The following example shows a simple daemon that forks and just starts one process in the background: [Unit] Description=My Simple Daemon [Service] Type=forking ExecStart=/usr/sbin/my-simple-daemon -d [Install] WantedBy=multi-user.target Please see `systemd.kill(5)` for details on how you can influence the way systemd terminates the service.
DBus services
For services that acquire a name on the DBus system bus, use `Type=``dbus` and set `BusName=` accordingly. The service should not fork (daemonize). systemd will consider the service to be initialized once the name has been acquired on the system bus. The following example shows a typical DBus service: [Unit] Description=Simple DBus Service [Service] Type=dbus BusName=org.example.simple-dbus-service ExecStart=/usr/sbin/simple-dbus-service [Install] WantedBy=multi-user.target For *bus-activatable* services, do not include a \[Install\] section in the systemd service file, but use the `SystemdService=` option in the corresponding DBus service file, for example (`/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service`): [D-BUS Service] Name=org.example.simple-dbus-service Exec=/usr/sbin/simple-dbus-service User=root SystemdService=simple-dbus-service.service Please see `systemd.kill(5)` for details on how you can influence the way systemd terminates the service.
Services that notify systemd about their initialization
`Type=``simple` services are really easy to write, but have the major disadvantage of systemd not being able to tell when initialization of the given service is complete. For this reason, systemd supports a simple notification protocol that allows daemons to make systemd aware that they are done initializing. Use `Type=``notify` or `Type=``notify-reload` for this. A typical service file for such a daemon would look like this: [Unit] Description=Simple Notifying Service [Service] Type=notify-reload ExecStart=/usr/sbin/simple-notifying-service [Install] WantedBy=multi-user.target Note that the daemon has to support systemd's notification protocol, else systemd will think the service has not started yet and kill it after a timeout. For an example of how to update daemons to support this protocol transparently, take a look at `sd_notify(3)`. systemd will consider the unit to be in the 'starting' state until a readiness notification has arrived. Please see `systemd.kill(5)` for details on how you can influence the way systemd terminates the service. To avoid code duplication, it is preferable to use `sd_notify(3)` when possible, especially when other APIs provided by `libsystemd(3)` are also used, but note that the notification protocol is very simple and guaranteed to be stable as per the [Interface Portability and Stability Promise](https://systemd.io/PORTABILITY_AND_STABILITY/), so it can be reimplemented by services with no external dependencies. For a self-contained example, see `sd_notify(3)`.
# See Also `systemd(1)`, `systemctl(1)`, `systemd-system.conf(5)`, `systemd.unit(5)`, `systemd.exec(5)`, `systemd.resource-control(5)`, `systemd.kill(5)`, `systemd.directives(7)`, `systemd-run(1)` # systemd.slice systemd systemd.slice 5 systemd.slice Slice unit configuration `slice.slice` # Description A unit configuration file whose name ends in `.slice` encodes information about a slice unit. A slice unit is a concept for hierarchically managing resources of a group of processes. This management is performed by creating a node in the Linux Control Group (cgroup) tree. Units that manage processes (primarily scope and service units) may be assigned to a specific slice. For each slice, certain resource limits may be set that apply to all processes of all units contained in that slice. Slices are organized hierarchically in a tree. The name of the slice encodes the location in the tree. The name consists of a dash-separated series of names, which describes the path to the slice from the root slice. The root slice is named `-.slice`. Example: `foo-bar.slice` is a slice that is located within `foo.slice`, which in turn is located in the root slice `-.slice`. Note that slice units cannot be templated, nor is it possible to add multiple names to a slice unit by creating additional symlinks to its unit file. By default, service and scope units are placed in `system.slice`, virtual machines and containers registered with `systemd-machined(8)` are found in `machine.slice`, and user sessions handled by `systemd-logind(8)` in `user.slice`. See `systemd.special(7)` for more information. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. The slice specific configuration options are configured in the \[Slice\] section. Currently, only generic resource control settings as described in `systemd.resource-control(5)` are allowed. See the [New Control Group Interfaces](https://systemd.io/CONTROL_GROUP_INTERFACE) for an introduction on how to make use of slice units from programs. # Automatic Dependencies ## Implicit Dependencies The following dependencies are implicitly added: - Slice units automatically gain dependencies of type `After=` and `Requires=` on their immediate parent slice unit. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - Slice units will automatically have dependencies of type `Conflicts=` and `Before=` on `shutdown.target`. These ensure that slice units are removed prior to system shutdown. Only slice units involved with late system shutdown should disable `DefaultDependencies=` option. # Options Slice unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. Slice files may include a \[Slice\] section. Many options that may be used in this section are shared with other unit types. These options are documented in `systemd.resource-control(5)`. The options specific to the \[Slice\] section of slice units are the following: `ConcurrencyHardMax=`; `ConcurrencySoftMax=` Configures a hard and a soft limit on the maximum number of units assigned to this slice (or any descendent slices) that may be active at the same time. If the hard limit is reached no further units associated with the slice may be activated, and their activation will fail with an error. If the soft limit is reached any further requested activation of units will be queued, but no immediate error is generated. The queued activation job will remain queued until the number of concurrent active units within the slice is below the limit again. If the special value `infinity` is specified, no concurrency limit is enforced. This is the default. Note that if multiple start jobs are queued for units, and all their dependencies are fulfilled they'll be processed in an order that is dependent on the unit type, the CPU weight (for unit types that know the concept, such as services), the nice level (similar), and finally in alphabetical order by the unit name. This may be used to influence dispatching order when using `ConcurrencySoftMax=` to pace concurrency within a slice unit. Note that these options have a hierarchial effect: a limit set for a slice unit will apply to both the units immediately within the slice, but also all units further down the slice tree. Also note that each sub-slice unit counts as one unit each too, and thus when choosing a limit for a slice hierarchy the limit must provide room for both the payload units (i.e. services, mounts, …) and structural units (i.e. slice units), if any are defined. `ActivatingConcurrencyMax=` Configures a limit on the maximum number of units assigned to this slice (or any descendent slices) that may be in the *activating* state at the same time. Unlike `ConcurrencySoftMax=` which limits units in the *active* state, this option limits units while they are starting up. Once a unit leaves the *activating* state (whether to *active*, *failed*, or any other state), it no longer counts toward this limit, allowing the next queued unit to begin starting. This is particularly useful for managing the "thundering herd" problem during system boot, where many long-running services (such as container workloads) attempt to start simultaneously. By setting `ActivatingConcurrencyMax=`, you can pace the startup process to limit CPU and I/O pressure, while still allowing all services to eventually reach the *active* state. When the limit is reached, further activation requests are queued and will be dispatched automatically once running activations complete. No error is returned to the caller. Note that if a unit becomes stuck in the activating state (for example, due to a hung process or missing dependency), it will continue to occupy a slot until it leaves that state. Configure appropriate timeouts (e.g., `TimeoutStartSec=`) on individual units to prevent indefinite blocking. Setting `ActivatingConcurrencyMax=0` blocks all activation requests in the slice hierarchy indefinitely. Queued units will never start until the limit is raised. This can be used to intentionally freeze slice startup, matching the behavior of `ConcurrencySoftMax=0`. If the special value `infinity` is specified, no concurrency limit is enforced. This is the default. Note that this option has a hierarchical effect: a limit set for a slice unit will apply to both the units immediately within the slice and all units further down the slice tree. Note that slice units themselves never enter the activating state, so nested slices do not count toward the limit. # See Also `systemd(1)`, `systemd.unit(5)`, `systemd.resource-control(5)`, `systemd.service(5)`, `systemd.scope(5)`, `systemd.special(7)`, `systemd.directives(7)` # systemd.socket systemd systemd.socket 5 systemd.socket Socket unit configuration `socket.socket` # Description A unit configuration file whose name ends in `.socket` encodes information about an IPC or network socket or a file system FIFO controlled and supervised by systemd, for socket-based activation. This man page lists the configuration options specific to this unit type. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. The socket specific configuration options are configured in the \[Socket\] section. Additional options are listed in `systemd.exec(5)`, which define the execution environment the `ExecStartPre=`, `ExecStartPost=`, `ExecStopPre=` and `ExecStopPost=` commands are executed in, and in `systemd.kill(5)`, which define the way the processes are terminated, and in `systemd.resource-control(5)`, which configure resource control settings for the processes of the socket. For each socket unit, a matching service unit must exist, describing the service to start on incoming traffic on the socket (see `systemd.service(5)` for more information about .service units). The name of the .service unit is by default the same as the name of the .socket unit, but can be altered with the `Service=` option described below. Depending on the setting of the `Accept=` option described below, this .service unit must either be named like the .socket unit, but with the suffix replaced, unless overridden with `Service=`; or it must be a template unit named the same way. Example: a socket file `foo.socket` needs a matching service `foo.service` if `Accept=no` is set. If `Accept=yes` is set, a service template `foo@.service` must exist from which services are instantiated for each incoming connection. No implicit `WantedBy=` or `RequiredBy=` dependency from the socket to the service is added. This means that the service may be started without the socket, in which case it must be able to open sockets by itself. To prevent this, an explicit `Requires=` dependency may be added. Socket units may be used to implement on-demand starting of services, as well as parallelized starting of services. See the blog stories linked at the end for an introduction. Note that the daemon software configured for socket activation with socket units needs to be able to accept sockets from systemd, either via systemd's native socket passing interface (see `sd_listen_fds(3)` for details about the precise protocol used and the order in which the file descriptors are passed) or via traditional `inetd(8)`-style socket passing (i.e. sockets passed in via standard input and output, using `StandardInput=socket` in the service file). By default, network sockets allocated through `.socket` units are allocated in the host's network namespace (see `network_namespaces(7)`). This does not mean however that the service activated by a configured socket unit has to be part of the host's network namespace as well. It is supported and even good practice to run services in their own network namespace (for example through `PrivateNetwork=`, see `systemd.exec(5)`), receiving only the sockets configured through socket-activation from the host's namespace. In such a set-up communication within the host's network namespace is only permitted through the activation sockets passed in while all sockets allocated from the service code itself will be associated with the service's own namespace, and thus possibly subject to a restrictive configuration. Alternatively, it is possible to run a `.socket` unit in another network namespace by setting `PrivateNetwork=yes` in combination with `JoinsNamespaceOf=`, see `systemd.exec(5)` and `systemd.unit(5)` for details. # Automatic Dependencies ## Implicit Dependencies The following dependencies are implicitly added: - Socket units automatically gain a `Before=` dependency on the service units they activate. - Socket units referring to file system paths (such as `AF_UNIX` sockets or FIFOs) implicitly gain `Requires=` and `After=` dependencies on all mount units necessary to access those paths. - Socket units using the `BindToDevice=` setting automatically gain a `BindsTo=` and `After=` dependency on the device unit encapsulating the specified network interface. Additional implicit dependencies may be added as result of execution and resource control parameters as documented in `systemd.exec(5)` and `systemd.resource-control(5)`. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - Socket units automatically gain a `Before=` dependency on `sockets.target`. - Socket units automatically gain a pair of `After=` and `Requires=` dependency on `sysinit.target`, and a pair of `Before=` and `Conflicts=` dependencies on `shutdown.target`. These dependencies ensure that the socket unit is started before normal services at boot, and is stopped on shutdown. Only sockets involved with early boot or late system shutdown should disable `DefaultDependencies=` option. # Options Socket unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. Socket unit files must include a \[Socket\] section, which carries information about the socket or FIFO it supervises. A number of options that may be used in this section are shared with other unit types. These options are documented in `systemd.exec(5)`, `systemd.kill(5)` and `systemd.resource-control(5)`. The options specific to the \[Socket\] section of socket units are the following: `ListenStream=`; `ListenDatagram=`; `ListenSequentialPacket=` Specifies an address to listen on for a stream (`SOCK_STREAM`), datagram (`SOCK_DGRAM`), or sequential packet (`SOCK_SEQPACKET`) socket, respectively. The address can be written in various formats: If the address starts with a slash (`/`), it is read as file system socket in the `AF_UNIX` socket family. If the address starts with an at symbol (`@`), it is read as abstract namespace socket in the `AF_UNIX` family. The `@` is replaced with a `NUL` character before binding. For details, see `unix(7)`. If the address string is a single number, it is read as port number to listen on via IPv6. Depending on the value of `BindIPv6Only=` (see below) this might result in the service being available via both IPv6 and IPv4 (default) or just via IPv6. If the address string is a string in the format `v.w.x.y:z`, it is interpreted as IPv4 address \ and port \. If the address string is a string in the format `[x]:y`, it is interpreted as IPv6 address \ and port \. An optional interface scope (interface name or number) may be specified after a `%` symbol: `[x]:y%dev`. Interface scopes are only useful with link-local addresses, because the kernel ignores them in other cases. Note that if an address is specified as IPv6, it might still make the service available via IPv4 too, depending on the `BindIPv6Only=` setting (see below). If the address string is a string in the format `vsock:x:y`, it is read as CID \ on a port \ address in the `AF_VSOCK` family. The CID is a unique 32-bit integer identifier in `AF_VSOCK` analogous to an IP address. Specifying the CID is optional, and may be set to the empty string. `vsock` may be replaced with `vsock-stream`, `vsock-dgram` or `vsock-seqpacket` to force usage of the corresponding socket type. Note that `SOCK_SEQPACKET` (i.e. `ListenSequentialPacket=`) is only available for `AF_UNIX` sockets. `SOCK_STREAM` (i.e. `ListenStream=`) when used for IP sockets refers to TCP sockets, `SOCK_DGRAM` (i.e. `ListenDatagram=`) to UDP. These options may be specified more than once, in which case incoming traffic on any of the sockets will trigger service activation, and all listed sockets will be passed to the service, regardless of whether there is incoming traffic on them or not. If the empty string is assigned to any of these options, the list of addresses to listen on is reset, all prior uses of any of these options will have no effect. It is also possible to have more than one socket unit for the same service when using `Service=`, and the service will receive all the sockets configured in all the socket units. Sockets configured in one unit are passed in the order of configuration, but no ordering between socket units is specified. If an IP address is used here, it is often desirable to listen on it before the interface it is configured on is up and running, and even regardless of whether it will be up and running at any point. To deal with this, it is recommended to set the `FreeBind=` option described below. `ListenFIFO=` Specifies a file system FIFO (see `fifo(7)` for details) to listen on. This expects an absolute file system path as argument. Behavior otherwise is very similar to the `ListenDatagram=` directive above. `ListenSpecial=` Specifies a special file in the file system to listen on. This expects an absolute file system path as argument. Behavior otherwise is very similar to the `ListenFIFO=` directive above. Use this to open character device nodes as well as special files in `/proc/` and `/sys/`. `ListenNetlink=` Specifies a Netlink family to create a socket for to listen on. This expects a short string referring to the `AF_NETLINK` family name (such as `audit` or `kobject-uevent`) as argument, optionally suffixed by a whitespace followed by a multicast group integer. Behavior otherwise is very similar to the `ListenDatagram=` directive above. `ListenMessageQueue=` Specifies a POSIX message queue name to listen on (see `mq_overview(7)` for details). This expects a valid message queue name (i.e. beginning with `/`). Behavior otherwise is very similar to the `ListenFIFO=` directive above. On Linux message queue descriptors are actually file descriptors and can be inherited between processes. `ListenUSBFunction=` Specifies a [USB FunctionFS](https://docs.kernel.org/usb/functionfs.html) endpoints location to listen on, for implementation of USB gadget functions. This expects an absolute file system path of a FunctionFS mount point as the argument. Behavior otherwise is very similar to the `ListenFIFO=` directive above. Use this to open the FunctionFS endpoint `ep0`. When using this option, the activated service has to have the `USBFunctionDescriptors=` and `USBFunctionStrings=` options set. `SocketProtocol=` Takes one of `udplite`, `sctp` or `mptcp`. The socket will use the UDP-Lite (`IPPROTO_UDPLITE`), SCTP (`IPPROTO_SCTP`) or MPTCP (`IPPROTO_MPTCP`) protocol, respectively. `BindIPv6Only=` Takes one of `default`, `both` or `ipv6-only`. Controls the IPV6_V6ONLY socket option (see `ipv6(7)` for details). If `both`, IPv6 sockets bound will be accessible via both IPv4 and IPv6. If `ipv6-only`, they will be accessible via IPv6 only. If `default` (which is the default, surprise!), the system wide default setting is used, as controlled by `/proc/sys/net/ipv6/bindv6only`, which in turn defaults to the equivalent of `both`. `Backlog=` Takes an unsigned 32-bit integer argument. Specifies the number of connections to queue that have not been accepted yet. This setting matters only for stream and sequential packet sockets. See `listen(2)` for details. Defaults to 4294967295. Note that this value is silently capped by the `net.core.somaxconn` sysctl, which typically defaults to 4096, so typically the sysctl is the setting that actually matters. `BindToDevice=` Specifies a network interface name to bind this socket to. If set, traffic will only be accepted from the specified network interfaces. This controls the `SO_BINDTODEVICE` socket option (see `socket(7)` for details). If this option is used, an implicit dependency from this socket unit on the network interface device unit is created (see `systemd.device(5)`). Note that setting this parameter might result in additional dependencies to be added to the unit (see above). `SocketUser=`; `SocketGroup=` Takes a UNIX user/group name. When specified, all `AF_UNIX` sockets, FIFO nodes, and message queues are owned by the specified user and group. If unset (the default), the nodes are owned by the root user/group (if run in system context) or the invoking user/group (if run in user context). If only a user is specified but no group, then the group is derived from the user's default group. `SocketMode=` If listening on a file system socket, FIFO, or message queue, this option specifies the file system access mode used when creating the file node. Takes an access mode in octal notation. Defaults to 0666. `DirectoryMode=` If listening on a file system socket or FIFO, the parent directories are automatically created if needed. This option specifies the file system access mode used when creating these directories. Takes an access mode in octal notation. Defaults to 0755. `Accept=` Takes a boolean argument. If yes, a service instance is spawned for each incoming connection and only the connection socket is passed to it. If no, all listening sockets themselves are passed to the started service unit, and only one service unit is spawned for all connections (also see above). This value is ignored for datagram sockets and FIFOs where a single service unit unconditionally handles all incoming traffic. Defaults to `no`. Typically, for performance sensitive services, a choice of `Accept=no` is preferable, since that way only the first connection will have to pay the activation resource cost. On the other hand, for sporadically used services `Accept=yes` can be preferable as it simplifies the implementation (as the service program code only has to process a single connection instead of handling multiple) and enables stronger security (since the various sandboxing options can be used to isolate parallel connections from each other, as each is serviced by a separate service instance and process). A service listening on an `AF_UNIX` socket may, but does not need to, call `close(2)` on the received socket before exiting. However, it must not unlink the socket from a file system. It should not invoke `shutdown(2)` on sockets it got with `Accept=no`, but it may do so for sockets it got with `Accept=yes` set. Setting `Accept=yes` is in particular useful for allowing daemons designed for usage with `inetd(8)` to work unmodified with systemd socket activation. Note that depending on this setting the services activated by units of this type are either regular services (in case of `Accept=``no`) or instances of templated services (in case of `Accept=``yes`). See the Description section above for a more detailed discussion of the naming rules of triggered services. For IPv4 and IPv6 connections, the `$REMOTE_ADDR` environment variable will contain the remote IP address, and `$REMOTE_PORT` will contain the remote port number. These two variables correspond to those defined by the CGI interface for web services (see [RFC 3875](https://datatracker.ietf.org/doc/html/rfc3875)). For `AF_UNIX` socket connections, the `$REMOTE_ADDR` environment variable will contain either the remote socket's file system path starting with a slash (`/`) or its address in the abstract namespace starting with an at symbol (`@`). If the socket is unnamed, `$REMOTE_ADDR` will not be set. If `Accept=yes` is used, the activated service process will have set the `$SO_COOKIE` environment variable to the Linux socket cookie, formatted as decimal integer. The socket cookie can otherwise be acquired via `getsockopt(7)`. It is recommended to set `CollectMode=inactive-or-failed` for service instances activated via `Accept=yes`, to ensure that failed connection services are cleaned up and released from memory, and do not accumulate. `Writable=` Takes a boolean argument. May only be used in conjunction with `ListenSpecial=`. If true, the specified special file is opened in read-write mode, if false, in read-only mode. Defaults to false. `FlushPending=` Takes a boolean argument. May only be used when `Accept=no`. If yes, the socket's buffers are cleared after the triggered service exited. This causes any pending data to be flushed and any pending incoming connections to be rejected. If no, the socket's buffers will not be cleared, permitting the service to handle any pending connections after restart, which is the usually expected behaviour. Defaults to `no`. `MaxConnections=` The maximum number of connections to simultaneously run services instances for, when `Accept=yes` is set. If more concurrent connections are coming in, they will be refused until at least one existing connection is terminated. This setting has no effect on sockets configured with `Accept=no` or datagram sockets. Defaults to 64. `MaxConnectionsPerSource=` The maximum number of connections for a service per source IP address (in case of IPv4/IPv6), per source CID (in case of `AF_VSOCK`), or source UID (in case of `AF_UNIX`). This is very similar to the `MaxConnections=` directive above. Defaults to 0, i.e. disabled. `KeepAlive=` Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message after 2h (depending on the configuration of `/proc/sys/net/ipv4/tcp_keepalive_time`) for all TCP streams accepted on this socket. This controls the `SO_KEEPALIVE` socket option (see `socket(7)` and the [TCP Keepalive HOWTO](http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/) for details.) Defaults to `false`. `KeepAliveTimeSec=` Takes time (in seconds) as argument. The connection needs to remain idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE socket option (see `socket(7)` and the [TCP Keepalive HOWTO](http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/) for details.) Default value is 7200 seconds (2 hours). `KeepAliveIntervalSec=` Takes time (in seconds) as argument between individual keepalive probes, if the socket option `SO_KEEPALIVE` has been set on this socket. This controls the `TCP_KEEPINTVL` socket option (see `socket(7)` and the [TCP Keepalive HOWTO](http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/) for details.) Default value is 75 seconds. `KeepAliveProbes=` Takes an integer as argument. It is the number of unacknowledged probes to send before considering the connection dead and notifying the application layer. This controls the TCP_KEEPCNT socket option (see `socket(7)` and the [TCP Keepalive HOWTO](http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/) for details.) Default value is 9. `NoDelay=` Takes a boolean argument. TCP Nagle's algorithm works by combining a number of small outgoing messages, and sending them all at once. This controls the TCP_NODELAY socket option (see `tcp(7)`). Defaults to `false`. `Priority=` Takes an integer argument controlling the priority for all traffic sent from this socket. This controls the `SO_PRIORITY` socket option (see `socket(7)` for details.). `DeferAcceptSec=` Takes time (in seconds) as argument. If set, the listening process will be awakened only when data arrives on the socket, and not immediately when connection is established. When this option is set, the `TCP_DEFER_ACCEPT` socket option will be used (see `tcp(7)`), and the kernel will ignore initial ACK packets without any data. The argument specifies the approximate amount of time the kernel should wait for incoming data before falling back to the normal behavior of honoring empty ACK packets. This option is beneficial for protocols where the client sends the data first (e.g. HTTP, in contrast to SMTP), because the server process will not be woken up unnecessarily before it can take any action. If the client also uses the `TCP_DEFER_ACCEPT` option, the latency of the initial connection may be reduced, because the kernel will send data in the final packet establishing the connection (the third packet in the "three-way handshake"). Disabled by default. `ReceiveBuffer=`; `SendBuffer=` Takes an integer argument controlling the receive or send buffer sizes of this socket, respectively. This controls the `SO_RCVBUF` and `SO_SNDBUF` socket options (see `socket(7)` for details.). The usual suffixes K, M, G are supported and are understood to the base of 1024. `IPTOS=` Takes an integer argument controlling the IP Type-Of-Service field for packets generated from this socket. This controls the `IP_TOS` socket option (see `ip(7)` for details.). Either a numeric string or one of `low-delay`, `throughput`, `reliability` or `low-cost` may be specified. `IPTTL=` Takes an integer argument controlling the IPv4 Time-To-Live/IPv6 Hop-Count field for packets generated from this socket. This sets the `IP_TTL`/`IPV6_UNICAST_HOPS` socket options (see `ip(7)` and `ipv6(7)` for details.) `Mark=` Takes an integer value. Controls the firewall mark of packets generated by this socket. This can be used in the firewall logic to filter packets from this socket. This sets the `SO_MARK` socket option. See `iptables(8)` for details. `ReusePort=` Takes a boolean value. If true, allows multiple `bind(2)`s to this TCP or UDP port. This controls the `SO_REUSEPORT` socket option. See `socket(7)` for details. `SmackLabel=`; `SmackLabelIPIn=`; `SmackLabelIPOut=` Takes a string value. Controls the extended attributes `security.SMACK64`, `security.SMACK64IPIN` and `security.SMACK64IPOUT`, respectively, i.e. the security label of the FIFO, or the security label for the incoming or outgoing connections of the socket, respectively. See [Smack](https://docs.kernel.org/admin-guide/LSM/Smack.html) for details. `XAttrEntryPoint=`; `XAttrListen=`; `XAttrAccept=` Set an extended attribute on the socket, in the form `NAME=VALUE`. The extended attribute's name must be in the `user.` namespace, i.e. begin with the four characters `user.`. Specifiers are expanded in both the name and the value, see `systemd.unit(5)` for details on the available specifiers. These settings may be used more than once to set multiple extended attributes; assigning the empty string resets the list. The three variables control where the extended attributes are applied: `XAttrEntryPoint=` sets them on the file-system inode an `AF_UNIX` socket is bound to (i.e. the socket node visible in the file system at the specified listening path; this only applies to `AF_UNIX` sockets), `XAttrListen=` sets them on the listening socket, and `XAttrAccept=` sets them on the connection sockets accepted off the listening socket (and is thus only relevant in combination with `Accept=``yes`). This is primarily useful to tag sockets so that they can be discovered and classified by other tools. For example, Varlink entrypoint sockets are supposed to be tagged with `user.varlink=entrypoint` via `XAttrEntryPoint=`, which makes them discoverable via `varlinkctl list-sockets`, see `varlinkctl(1)`. These settings require kernel support for extended attributes on socket inodes (available since Linux 7.0). Extended attributes that cannot be applied are logged at debug level and otherwise ignored. `SELinuxContextFromNet=` Takes a boolean argument. When true, systemd will attempt to figure out the SELinux label used for the instantiated service from the information handed by the peer over the network. Note that only the security level is used from the information provided by the peer. Other parts of the resulting SELinux context originate from either the target binary that is effectively triggered by socket unit or from the value of the `SELinuxContext=` option. This configuration option applies only when activated service is passed in single socket file descriptor, i.e. service instances that have standard input connected to a socket or services triggered by exactly one socket unit. Also note that this option is useful only when MLS/MCS SELinux policy is deployed. Defaults to `false`. `PipeSize=` Takes a size in bytes. Controls the pipe buffer size of FIFOs configured in this socket unit. See `fcntl(2)` for details. The usual suffixes K, M, G are supported and are understood to the base of 1024. `MessageQueueMaxMessages=`, `MessageQueueMessageSize=` These two settings control the mq_maxmsg field or the mq_msgsize field, respectively, when creating the message queue. `MessageQueueMaxMessages=` takes an integer value. `MessageQueueMessageSize=` takes a size in bytes, and the usual suffixes K, M, G are supported and understood to the base of 1024. Note that either none or both of these variables need to be set. See `mq_setattr(3)` for details. `FreeBind=` Takes a boolean value. Controls whether the socket can be bound to non-local IP addresses. This is useful to configure sockets listening on specific IP addresses before those IP addresses are successfully configured on a network interface. This sets the `IP_FREEBIND`/`IPV6_FREEBIND` socket option. For robustness reasons it is recommended to use this option whenever you bind a socket to a specific IP address. Defaults to `false`. `Transparent=` Takes a boolean value. Controls the `IP_TRANSPARENT`/`IPV6_TRANSPARENT` socket option. Defaults to `false`. `Broadcast=` Takes a boolean value. This controls the `SO_BROADCAST` socket option, which allows broadcast datagrams to be sent from this socket. Defaults to `false`. `PassCredentials=` Takes a boolean value. This controls the `SO_PASSCRED` socket option, which allows `AF_UNIX` sockets to receive the credentials of the sending process in an ancillary message. Defaults to `false`. `PassPIDFD=` Takes a boolean value. This controls the `SO_PASSPIDFD` socket option, which allows `AF_UNIX` sockets to receive the pidfd of the sending process in an ancillary message. Defaults to `false`. `PassSecurity=` Takes a boolean value. This controls the `SO_PASSSEC` socket option, which allows `AF_UNIX` sockets to receive the security context of the sending process in an ancillary message. Defaults to `false`. `PassPacketInfo=` Takes a boolean value. This controls the `IP_PKTINFO`, `IPV6_RECVPKTINFO`, `NETLINK_PKTINFO` or `PACKET_AUXDATA` socket options, which enable reception of additional per-packet metadata as ancillary message, on `AF_INET`, `AF_INET6`, `AF_UNIX` and `AF_PACKET` sockets. Defaults to `false`. `AcceptFileDescriptors=` Takes a boolean value. This controls the `SO_PASSRIGHTS` socket option, which when disabled prohibits the peer from sending `SCM_RIGHTS` ancillary messages (aka file descriptors) via `AF_UNIX` sockets. Defaults to `true`. `Timestamping=` Takes one of `off`, `us` (alias: `usec`, `μs`) or `ns` (alias: `nsec`). This controls the `SO_TIMESTAMP` or `SO_TIMESTAMPNS` socket options, and enables whether ingress network traffic shall carry timestamping metadata. Defaults to `off`. `TCPCongestion=` Takes a string value. Controls the TCP congestion algorithm used by this socket. Should be one of `westwood`, `reno`, `cubic`, `lp` or any other available algorithm supported by the IP stack. This setting applies only to stream sockets. `ExecStartPre=`; `ExecStartPost=` Takes one or more command lines, which are executed before or after the listening sockets/FIFOs are created and bound, respectively. The first token of the command line must be an absolute filename, then followed by arguments for the process. Multiple command lines may be specified following the same scheme as used for `ExecStartPre=` of service unit files. `ExecStopPre=`; `ExecStopPost=` Additional commands that are executed before or after the listening sockets/FIFOs are closed and removed, respectively. Multiple command lines may be specified following the same scheme as used for `ExecStartPre=` of service unit files. `TimeoutSec=` Configures the time to wait for the commands specified in `ExecStartPre=`, `ExecStartPost=`, `ExecStopPre=` and `ExecStopPost=` to finish. If a command does not exit within the configured time, the socket will be considered failed and be shut down again. All commands still running will be terminated forcibly via `SIGTERM`, and after another delay of this time with `SIGKILL`. (See `KillMode=` in `systemd.kill(5)`.) Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass `0` to disable the timeout logic. Defaults to `DefaultTimeoutStartSec=` from the manager configuration file (see `systemd-system.conf(5)`). `Service=` Specifies the service unit name to activate on incoming traffic. This setting is only allowed for sockets with `Accept=no`. It defaults to the service that bears the same name as the socket (with the suffix replaced). In most cases, it should not be necessary to use this option. Note that setting this parameter might result in additional dependencies to be added to the unit (see above). `RemoveOnStop=` Takes a boolean argument. If enabled, any file nodes created by this socket unit are removed when it is stopped. This applies to `AF_UNIX` sockets in the file system, POSIX message queues, FIFOs, as well as any symlinks to them configured with `Symlinks=`. Normally, it should not be necessary to use this option, and is not recommended as services might continue to run after the socket unit has been terminated and it should still be possible to communicate with them via their file system node. Defaults to off. `Symlinks=` Takes a list of file system paths. The specified paths will be created as symlinks to the `AF_UNIX` socket path or FIFO path of this socket unit. If this setting is used, only one `AF_UNIX` socket in the file system or one FIFO may be configured for the socket unit. Use this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty list. `FileDescriptorName=` Assigns a name to all file descriptors this socket unit encapsulates. This is useful to help activated services identify specific file descriptors, if multiple fds are passed. Services may use the `sd_listen_fds_with_names(3)` call to acquire the names configured for the received file descriptors. Names may contain any ASCII character, but must exclude control characters and `:`, and must be at most 255 characters in length. If this setting is not used, the file descriptor name defaults to the name of the socket unit (including its `.socket` suffix) when `Accept=no`, `connection` otherwise. `TriggerLimitIntervalSec=`; `TriggerLimitBurst=` Configures a limit on how often this socket unit may be activated within a specific time interval. The `TriggerLimitIntervalSec=` setting may be used to configure the length of the time interval in the usual time units `us`, `ms`, `s`, `min`, `h`, … and defaults to 2s (See `systemd.time(7)` for details on the various time units understood). The `TriggerLimitBurst=` setting takes a positive integer value and specifies the number of permitted activations per time interval, and defaults to 200 for `Accept=yes` sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20 activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this limit is enforced before the service activation is enqueued. Compare with `PollLimitIntervalSec=`/`PollLimitBurst=` described below, which implements a temporary slowdown if a socket unit is flooded with incoming traffic, as opposed to the permanent failure state `TriggerLimitIntervalSec=`/`TriggerLimitBurst=` results in. `PollLimitIntervalSec=`; `PollLimitBurst=` Configures a limit on how often polling events on the file descriptors backing this socket unit will be considered. This pair of settings is similar to `TriggerLimitIntervalSec=`/`TriggerLimitBurst=` but instead of putting a (fatal) limit on the activation frequency puts a (transient) limit on the polling frequency. The expected parameter syntax and range are identical to that of the aforementioned options, and can be disabled the same way. If the polling limit is hit polling is temporarily disabled on it until the specified time window passes. The polling limit hence slows down connection attempts if hit, but unlike the trigger limit will not cause permanent failures. It's the recommended mechanism to deal with DoS attempts through packet flooding. The polling limit is enforced per file descriptor to listen on, as opposed to the trigger limit which is enforced for the entire socket unit. This distinction matters for socket units that listen on multiple file descriptors (i.e. have multiple `ListenXYZ=` stanzas). These setting defaults to 150 (in case of `Accept=yes`) and 15 (otherwise) polling events per 2s. This is considerably lower than the default values for the trigger limit (see above) and means that the polling limit should typically ensure the trigger limit is never hit, unless one of them is reconfigured or disabled. `DeferTrigger=` Takes a boolean argument, or `patient`. May only be used when `Accept=no`. If enabled, job mode `lenient` instead of `replace` is used when triggering the service, which means currently activating/running units that conflict with the service won't be disturbed/brought down. Furthermore, if a conflict exists, the socket unit will wait for current job queue to complete and potentially defer the activation by then. An upper limit of total time to wait can be configured via `DeferTriggerMaxSec=`. If set to `yes`, the socket unit will fail if all jobs have finished or the timeout has been reached but the conflict remains. If `patient`, always wait until `DeferTriggerMaxSec=` elapses. Defaults to no. This setting is particularly useful if the socket unit should stay active across switch-root/soft-reboot operations while the triggered service is stopped. `DeferTriggerMaxSec=` Configures the maximum time to defer the triggering when `DeferTrigger=` is enabled. If the service cannot be activated within the specified time, the socket will be considered failed and get terminated. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass `0` or `infinity` to disable the timeout logic (the default). `PassFileDescriptorsToExec=` Takes a boolean argument. Defaults to off. If enabled, file descriptors created by the socket unit are passed to `ExecStartPost=`, `ExecStopPre=`, and `ExecStopPost=` commands from the socket unit. The passed file descriptors can be accessed with `sd_listen_fds(3)` as if the commands were invoked from the associated service units. Note that `ExecStartPre=` command cannot access socket file descriptors. # See Also `systemd(1)`, `systemctl(1)`, `systemd-system.conf(5)`, `systemd.unit(5)`, `systemd.exec(5)`, `systemd.kill(5)`, `systemd.resource-control(5)`, `systemd.service(5)`, `systemd.directives(7)`, `sd_listen_fds(3)`, `sd_listen_fds_with_names(3)` For more extensive descriptions see the "systemd for Developers" series: [Socket Activation](https://0pointer.de/blog/projects/socket-activation.html), [Socket Activation, part II](https://0pointer.de/blog/projects/socket-activation2.html), [Converting inetd Services](https://0pointer.de/blog/projects/inetd.html), [Socket Activated Internet Services and OS Containers](https://0pointer.de/blog/projects/socket-activated-containers.html). # systemd.swap systemd systemd.swap 5 systemd.swap Swap unit configuration `swap.swap` # Description A unit configuration file whose name ends in `.swap` encodes information about a swap device or file for memory paging controlled and supervised by systemd. This man page lists the configuration options specific to this unit type. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. The swap specific configuration options are configured in the \[Swap\] section. Additional options are listed in `systemd.exec(5)`, which define the execution environment the `swapon(8)` program is executed in, in `systemd.kill(5)`, which define the way these processes are terminated, and in `systemd.resource-control(5)`, which configure resource control settings for these processes of the unit. Swap units must be named after the devices or files they control. Example: the swap device `/dev/sda5` must be configured in a unit file `dev-sda5.swap`. For details about the escaping logic used to convert a file system path to a unit name, see `systemd.unit(5)`. Note that swap units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to it. Note that swap support on Linux is privileged, swap units are hence only available in the system service manager (and root's user service manager), but not in unprivileged user's service manager. # Automatic Dependencies ## Implicit Dependencies The following dependencies are implicitly added: - All swap units automatically get the `Requires=` and `After=` dependencies on the device units or the mount units of the files they are activated from. Additional implicit dependencies may be added as result of execution and resource control parameters as documented in `systemd.exec(5)` and `systemd.resource-control(5)`. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - Local swap units automatically acquire a `Conflicts=` and a `Before=` dependency on `umount.target` so that they are deactivated at shutdown as well as a `Before=swap.target` dependency. - Network swap units (those with `_netdev` in their options) automatically acquire `After=` dependencies on `remote-fs-pre.target` and `network.target`, plus `After=` and `Wants=` dependencies on `network-online.target`, and a `Before=` dependency on `remote-fs.target` instead of `swap.target`. # `fstab` Swap units may either be configured via unit files, or via `/etc/fstab` (see `fstab(5)` for details). Swaps listed in `/etc/fstab` will be converted into native units dynamically at boot and when the configuration of the system manager is reloaded. See `systemd-fstab-generator(8)` for details about the conversion. If a swap device or file is configured in both `/etc/fstab` and a unit file, the configuration in the latter takes precedence. When reading `/etc/fstab`, a few special options are understood by systemd which influence how dependencies are created for swap units. `noauto`; `auto` With `noauto`, the swap unit will not be added as a dependency for `swap.target` (or `remote-fs.target` for network swap devices, see `_netdev` below). This means that it will not be activated automatically during boot, unless it is pulled in by some other unit. The `auto` option has the opposite meaning and is the default. `nofail` With `nofail`, the swap unit will be only wanted, not required by `swap.target` (or `remote-fs.target` for network swap devices). This means that the boot will continue even if this swap device is not activated successfully. `x-systemd.makefs` The swap structure will be initialized on the device. If the device is not "empty", i.e. it contains any signature, the operation will be skipped. It is hence expected that this option remains set even after the device has been initialized. Note that this option can only be used in `/etc/fstab`, and will be ignored when part of the `Options=` setting in a unit file. See `systemd-mkswap@.service(8)` and the discussion of `wipefs(8)` in `systemd.mount(5)`. `_netdev` Marks this swap device as requiring network access. This is useful for swap on network block devices (e.g. iSCSI). Network swap units are ordered between `remote-fs-pre.target` and `remote-fs.target`, instead of being ordered before `swap.target`. They also pull in `network-online.target` and are ordered after it and `network.target`. # Options Swap unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. Swap unit files must include a \[Swap\] section, which carries information about the swap device it supervises. A number of options that may be used in this section are shared with other unit types. These options are documented in `systemd.exec(5)`, `systemd.kill(5)` and `systemd.resource-control(5)`. The options specific to the \[Swap\] section of swap units are the following: `What=` Takes an absolute path or a fstab-style identifier of a device node or file to use for paging. See `swapon(8)` for details. If this refers to a device node, a dependency on the respective device unit is automatically created. (See `systemd.device(5)` for more information.) If this refers to a file, a dependency on the respective mount unit is automatically created. (See `systemd.mount(5)` for more information.) This option is mandatory. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as `%%`. `Priority=` Swap priority to use when activating the swap device or file. This takes an integer. This setting is optional and ignored when the priority is set by `pri=` in the `Options=` key. `Options=` May contain an option string for the swap device. This may be used for controlling discard options among other functionality, if the swap backing device supports the discard or trim operation. (See `swapon(8)` for more information.) Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as `%%`. `TimeoutSec=` Configures the time to wait for the swapon command to finish. If a command does not exit within the configured time, the swap will be considered failed and be shut down again. All commands still running will be terminated forcibly via `SIGTERM`, and after another delay of this time with `SIGKILL`. (See `KillMode=` in `systemd.kill(5)`.) Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass `0` to disable the timeout logic. Defaults to `DefaultTimeoutStartSec=` from the manager configuration file (see `systemd-system.conf(5)`). # See Also `systemd(1)`, `systemctl(1)`, `systemd-system.conf(5)`, `systemd.unit(5)`, `systemd.exec(5)`, `systemd.kill(5)`, `systemd.resource-control(5)`, `systemd.device(5)`, `systemd.mount(5)`, `swapon(8)`, `systemd-fstab-generator(8)`, `systemd.directives(7)` # systemd.syntax systemd systemd.syntax 7 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](https://standards.freedesktop.org/desktop-entry-spec/latest/) `.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 \=\. 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. | 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 \ in hexadecimal encoding | | `\nnn` | character number \ in octal encoding | | `\unnnn` | unicode code point \ in hexadecimal encoding | | `\Unnnnnnnn` | unicode code point \ in hexadecimal encoding | Supported escapes # See Also `systemd(1)`, `systemd.time(7)` # systemd.system-credentials systemd systemd.system-credentials 7 systemd.system-credentials System Credentials # Description [System and Service Credentials](https://systemd.io/CREDENTIALS) 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. `firstboot.hostname` This credential specifies the static system hostname to set during first boot. The user will not be prompted for the hostname. Note that this controls the static hostname, not the transient hostname, and only has an effect on first boot, unlike `system.hostname` (see below). Read by `systemd-firstboot(1)` and only honoured if no static hostname has been configured before. The value may use the wildcard patterns documented in `hostname(5)` (e.g. `$-$` or `foo-????`). When the credential is applied on the running system (the usual case, by `systemd-firstboot.service` on first boot), the wildcards are resolved against the machine ID and the resulting concrete name is written to `/etc/hostname`. The name is thus *persisted* once at first boot and does not change on subsequent boots even if the word lists are later updated or the pattern is changed (for example to add more `?`/`$` tokens for additional entropy), which is the recommended way to obtain a stable, per-machine generated hostname. (When `systemd-firstboot(1)` operates on an offline image via `--root=`/`--image=`, the target's machine ID is not yet known, so the pattern is written verbatim and, like a pattern placed directly in `/etc/hostname`, re-derived on every boot rather than persisted.) `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`. `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. `firstboot.machine-tags` The machine tags to set, as a colon-separated list (e.g. `company.role=webserver:company.location=berlin`). Read by `systemd-firstboot(1)`, and only honoured if `/etc/machine-info` has not been configured before. Written into the `TAGS=` field of that file, see `machine-info(5)` for details. `keyring-setup.dm-verity.NAME`; `keyring-setup.fs-verity.NAME`; `keyring-setup.bpf.NAME` A PEM-encoded X.509 certificate to enroll into the `.dm-verity`, `.fs-verity` or `.bpf` kernel keyring, respectively (e.g. `keyring-setup.dm-verity.vendor`). Read by `systemd-keyring-setup.service(8)`, which writes the certificate to `/run/voa/` before enrolling it, see there for details. \ may consist of lowercase letters, digits, `.`, `_` and `-`. `keyring-setup.os` A whitespace-separated list of OS identifiers (e.g. `debian:13 debian`) under which certificates are looked up in the VOA hierarchy, instead of the ones derived from `os-release(5)`. Read by `systemd-keyring-setup.service(8)`. `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)`. `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)`. `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)`. `network.dns`; `network.search_domains` DNS server information and search domains. Read by `systemd-resolved.service(8)`. `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. `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)`. `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. `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. `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)`. `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)`. `ssh.listen` May be used to configure SSH sockets the system shall be reachable on. See `systemd-ssh-generator(8)` for details. `sysusers.extra` Additional `sysusers.d(5)` lines to process during boot. `sysctl.extra` Additional `sysctl.d(5)` lines to process during boot. `tmpfiles.extra` Additional `tmpfiles.d(5)` lines to process during boot. `fstab.extra` Additional mounts to establish at boot. For details, see `systemd-fstab-generator(8)`. `vconsole.keymap`; `vconsole.keymap_toggle`; `vconsole.font`; `vconsole.font_map`; `vconsole.font_unimap`; `vconsole.font_scale` Console settings to apply, see `systemd-vconsole-setup.service(8)` for details. `vconsole.font_scale` was added in version 262. `getty.auto` Used for controlling the execution mode of `systemd-getty-generator`. See `systemd-getty-generator(8)` for details. `getty.ttys.serial`; `getty.ttys.container` Used for spawning additional login prompts, see `systemd-getty-generator(8)` for details. `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. `journal.storage` Used by `systemd-journald(8)` to determine where to store journal files, see `journald.conf(5)` for details. `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)`. `shell.prompt.prefix`; `shell.prompt.suffix` Defines strings to prefix and suffix any interactive UNIX shell prompt with. For details see `pam_systemd(8)`. `shell.welcome` Define a string to print when an interactive UNIX shell initializes. For details see `pam_systemd(8)`. `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)`. `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)`. Also see `firstboot.hostname` above. The value may use the wildcard patterns documented in `hostname(5)` (`?` and `$`), which are expanded deterministically from the machine ID when the credential is applied. As this is a transient hostname that is re-applied on every boot, a wildcard value is re-derived each boot (and may change if the word lists change) and is never persisted; pass an already-resolved name if a stable hostname is required. Note also that the word-list tokens require the word lists to be present, which is generally not the case in the initrd so during initrd the default hostname is used and in late boot the resolved one becomes available. `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)`. `home.create.*` Creates a new home area for the specified user with the user record data passed in. For details see `homectl(1)`. `home.register.*` Registers an existing home area for the specified user with the user record data passed in. For details see `homectl(1)`. `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)`. `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)`. `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. `import.pull` Specified disk images (tarballs and DDIs) to automatically download and install at boot. For details see `systemd-import-generator(8)`. `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](https://systemd.io/USER_RECORD) and [JSON Group](https://systemd.io/GROUP_RECORD) 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(8)`, `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). `fsck.*` Read by `systemd-fsck@.service`, `systemd-fsck-root.service`, and `systemd-fsck-usr.service`. See `systemd-fsck@.service(8)` for more details. `quotacheck.*` Read by `systemd-quotacheck@.service` and `systemd-quotacheck-root.service`. See `systemd-quotacheck(8)` for more details. `imds.*` Read by `systemd-imdsd@.service(8)`. # See Also `systemd(1)`, `kernel-command-line(7)`, `smbios-type-11(7)` # systemd.target systemd systemd.target 5 systemd.target Target unit configuration `target.target` # Description A unit configuration file whose name ends in `.target` encodes information about a target unit of systemd. Target units are used to group units and to set synchronization points for ordering dependencies with other unit files. This unit type has no specific options. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. A separate \[Target\] section does not exist, since no target-specific options may be configured. Target units do not offer any additional functionality on top of the generic functionality provided by units. They merely group units, allowing a single target name to be used in `Wants=` and `Requires=` settings to establish a dependency on a set of units defined by the target, and in `Before=` and `After=` settings to establish ordering. Targets establish standardized names for synchronization points during boot and shutdown. Importantly, see `systemd.special(7)` for examples and descriptions of standard systemd targets. Target units provide a more flexible replacement for SysV runlevels in the classic SysV init system. Note that a target unit file must not be empty, lest it be considered a masked unit. It is recommended to provide a \[Unit\] section which includes informative `Description=` and `Documentation=` options. # Automatic Dependencies ## Implicit Dependencies There are no implicit dependencies for target units. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - Target units will automatically complement all configured dependencies of type `Wants=` or `Requires=` with dependencies of type `After=` unless `DefaultDependencies=no` is set in the specified units. Note that the reverse is not true. For example, defining `Wants=that.target` in `some.service` will not automatically add the `After=that.target` ordering dependency for `some.service`. Instead, `some.service` should use the primary synchronization function of target type units, by setting a specific `After=that.target` or `Before=that.target` ordering dependency in its .service unit file. - Target units automatically gain `Conflicts=` and `Before=` dependencies against `shutdown.target`. # Options Target unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. No options specific to this file type are supported. # Example
Simple standalone target
# emergency-net.target [Unit] Description=Emergency Mode with Networking Requires=emergency.target systemd-networkd.service After=emergency.target systemd-networkd.service AllowIsolate=yes When adding dependencies to other units, it is important to check if they set `DefaultDependencies=`. Service units, unless they set `DefaultDependencies=no`, automatically get a dependency on `sysinit.target`. In this case, both `emergency.target` and `systemd-networkd.service` have `DefaultDependencies=no`, so they are suitable for use in this target, and do not pull in `sysinit.target`. You can now switch into this emergency mode by running `systemctl isolate emergency-net.target` or by passing the option `systemd.unit=emergency-net.target` on the kernel command line. Other units can have `WantedBy=emergency-net.target` in the `[Install]` section. After they are enabled using `systemctl enable`, they will be started before `emergency-net.target` is started. It is also possible to add arbitrary units as dependencies of `emergency.target` without modifying them by using `systemctl add-wants`.
# See Also `systemd(1)`, `systemctl(1)`, `systemd.unit(5)`, `systemd.special(7)`, `systemd.directives(7)` # systemd.time systemd systemd.time 7 systemd.time Time and date specifications # Description In systemd, timestamps, time spans, and calendar events are displayed and may be specified in closely related syntaxes. # Displaying Time Spans Time spans refer to time durations. On display, systemd will present time spans as a space-separated series of time values each suffixed by a time unit. Example: 2h 30min All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is locale-independent, only English names for the time units are used. # Parsing Time Spans When parsing, systemd will accept the same time span syntax. Separating spaces may be omitted. The following time units are understood: - usec, us, μs - msec, ms - seconds, second, sec, s - minutes, minute, min, m - hours, hour, hr, h - days, day, d - weeks, week, w - months, month, M (defined as 30.44 days) - years, year, y (defined as 365.25 days) If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as such. In a few cases `ns`, `nsec` is accepted too, where the granularity of the time span permits this. Parsing is generally locale-independent, non-English names for the time units are not accepted. Examples for valid time span specifications: 2 h 2hours 48hr 1y 12month 55s500ms 300ms20s 5day One can use the `timespan` command of `systemd-analyze(1)` to normalise a textual time span for testing and validation purposes. Internally, systemd generally operates with microsecond time granularity, while the default time unit in user-configurable time spans is usually seconds (see above). This disparity becomes visible when comparing the same settings in the (high-level) unit file syntax with the matching (more low-level) D-Bus properties (which are what `systemctl(1)`'s `show` command displays). The former typically are suffixed with `…Sec` to indicate the default unit of seconds, the latter are typically suffixed with `…USec` to indicate the underlying low-level time unit, even if they both encapsulate the very same settings. # Displaying Timestamps Timestamps refer to specific, unique points in time. On display, systemd will format these in the local timezone as follows: Fri 2012-11-23 23:02:15 CET The weekday is printed in the abbreviated English language form. The formatting is locale-independent. In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via the `UTC` timezone specifier in the output. In some cases timestamps are shown with microsecond granularity. In this case, the sub-second remainder is separated by a full stop from the seconds component. # Parsing Timestamps When parsing, systemd will accept a similar syntax, but some fields can be omitted, and the space between the date and time can be replaced with a `T` (à la the [RFC 3339](https://tools.ietf.org/html/rfc3339) profile of ISO 8601); thus, in CET, the following are all identical: `Fri 2012-11-23 23:02:15 CET`, `Fri 2012-11-23T23:02:15`, `2012-11-23T23:02:15 CET`, `2012-11-23 23:02:15`. The timezone defaults to the current timezone if not specified explicitly. It may be given after a space, like above, in which case it can be: `UTC`, an entry in the installed IANA timezone database (e.g. `CET`, `Asia/Tokyo`, where the complete list can be obtained with `timedatectl list-timezones` (see `timedatectl(1)`)), or `±05`, `±0530`, `±05:30`, `Z`. It may also be affixed directly to the timestamp, in which case it must correspond to one of the formats defined in the [RFC 3339](https://tools.ietf.org/html/rfc3339) profile of ISO 8601: `±05:30` or `Z`. Thus, the following are also identical to the above: `2012-11-23T23:02:15+01:00`, `2012-11-23 22:02:15Z`. A timestamp can start with a field containing a weekday, which can be in an abbreviated (`Wed`) or non-abbreviated (`Wednesday`) English language form (case does not matter), regardless of the locale. However, if a weekday *is* specified and does not match the date, the timestamp is rejected. If the date is omitted, it defaults to today. If the time is omitted, it defaults to 00:00:00. Fractional seconds can be specified down to 1µs precision. The seconds field can also be omitted, defaulting to 0. There are special tokens that can be used in place of timestamps: `now` may be used to refer to the current time (or of the invocation of the command that is currently executed). `today`, `yesterday`, and `tomorrow` refer to 00:00:00 of the current day, the day before, or the next day, respectively. Relative times are also accepted: a time span (see above) prefixed with `+` is evaluated to the current time plus the specified time span. Correspondingly, a time span that is prefixed with `-` is evaluated to the current time minus the specified time span. Instead of prefixing the time span with `+` or `-`, it may also be suffixed with a space and the word `left` or `ago`. Finally, an integer prefixed with `@` is evaluated relative to the UNIX epoch – 1970-01-01 00:00:00 UTC. Examples for valid timestamps and their normalized form (assuming the current time was 2012-11-23 18:15:22 and the timezone was UTC+8, for example `TZ=:Asia/Shanghai`): Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13 2012-11-23T11:12:13Z → Fri 2012-11-23 19:12:13 2012-11-23T11:12+02:00 → Fri 2012-11-23 17:12:00 2012-11-23 → Fri 2012-11-23 00:00:00 12-11-23 → Fri 2012-11-23 00:00:00 11:12:13 → Fri 2012-11-23 11:12:13 11:12 → Fri 2012-11-23 11:12:00 now → Fri 2012-11-23 18:15:22 today → Fri 2012-11-23 00:00:00 today UTC → Fri 2012-11-23 16:00:00 yesterday → Fri 2012-11-22 00:00:00 tomorrow → Fri 2012-11-24 00:00:00 tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00 +3h30min → Fri 2012-11-23 21:45:22 -5s → Fri 2012-11-23 18:15:17 11min ago → Fri 2012-11-23 18:04:22 @1395716396 → Tue 2014-03-25 03:59:56 Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable locally, as the timezone component is not understood (unless it happens to be `UTC`). Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated by a full stop from the seconds component. Example: 2014-03-25 03:59:56.654563 In some cases, systemd will display a relative timestamp (relative to the current time, or the time of invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative timestamp is formatted as follows: 2 months 5 days ago Note that a relative timestamp is also accepted where a timestamp is expected (see above). Use the `timestamp` command of `systemd-analyze(1)` to validate and normalize timestamps for testing purposes. # Calendar Events Calendar events may be used to refer to one or more points in time in a single expression. They form a superset of the absolute timestamps explained above: Thu,Fri 2012-*-1,5 11:12:13 The above refers to 11:12:13 of the first or fifth day of any month of the year 2012, but only if that day is a Thursday or Friday. The weekday specification is optional. If specified, it should consist of one or more English language weekday names, either in the abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not matter), separated by commas. Specifying two weekdays separated by `..` refers to a range of continuous weekdays. `,` and `..` may be combined freely. In the date and time specifications, any component may be specified as `*` in which case any value will match. Alternatively, each component can be specified as a list of values separated by commas. Values may be suffixed with `/` and a repetition value, which indicates that the value itself and the value plus all multiples of the repetition value are matched. Two values separated by `..` may be used to indicate a range of values; ranges may also be followed with `/` and a repetition value, in which case the expression matches all times starting with the start value, and continuing with all multiples of the repetition value relative to the start value, ending at the end value the latest. A date specification may use `~` to indicate the last day in a month. For example, `*-02~03` means "the third last day in February," and `Mon *-05~07/1` means "the last Monday in May." The seconds component may contain decimal fractions both in the value and the repetition. All fractions are rounded to 6 decimal places. Either time or date specification may be omitted, in which case 00:00:00 and \*-\*-\* is implied, respectively. If the seconds component is not specified, `:00` is assumed. Timezone can be specified as the literal string `UTC`, or the local timezone, similar to the supported syntax of timestamps (see above), or the timezone in the IANA timezone database format (also see above). The following special expressions may be used as shorthands for longer normalized forms: minutely → *-*-* *:*:00 hourly → *-*-* *:00:00 daily → *-*-* 00:00:00 monthly → *-*-01 00:00:00 weekly → Mon *-*-* 00:00:00 yearly → *-01-01 00:00:00 quarterly → *-01,04,07,10-01 00:00:00 semiannually → *-01,07-01 00:00:00 Examples for valid timestamps and their normalized form: Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00 Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00 Wed *-1 → Wed *-*-01 00:00:00 Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00 Wed, 17:48 → Wed *-*-* 17:48:00 Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03 *-*-7 0:0:0 → *-*-07 00:00:00 10-15 → *-10-15 00:00:00 monday *-12-* 17:00 → Mon *-12-* 17:00:00 Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00 12..14:10,20,30 → *-*-* 12..14:10,20,30:00 mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45 03-05 08:05:40 → *-03-05 08:05:40 08:05:40 → *-*-* 08:05:40 05:40 → *-*-* 05:40:00 Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40 Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40 2003-03-05 05:40 → 2003-03-05 05:40:00 05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001 2003-02..04-05 → 2003-02..04-05 00:00:00 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC 2003-03-05 → 2003-03-05 00:00:00 03-05 → *-03-05 00:00:00 hourly → *-*-* *:00:00 daily → *-*-* 00:00:00 daily UTC → *-*-* 00:00:00 UTC monthly → *-*-01 00:00:00 weekly → Mon *-*-* 00:00:00 weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland yearly → *-01-01 00:00:00 annually → *-01-01 00:00:00 *:2/3 → *-*-* *:02/3:00 Calendar events are used by timer units, see `systemd.timer(5)` for details. Use the `calendar` command of `systemd-analyze(1)` to validate and normalize calendar time specifications for testing purposes. The tool also calculates when a specified calendar event would occur next. # See Also `systemd(1)`, `journalctl(1)`, `systemd.timer(5)`, `systemd.unit(5)`, `systemd.directives(7)`, `systemd-analyze(1)` # systemd.timer systemd systemd.timer 5 systemd.timer Timer unit configuration `timer.timer` # Description A unit configuration file whose name ends in `.timer` encodes information about a timer controlled and supervised by systemd, for timer-based activation. This man page lists the configuration options specific to this unit type. See `systemd.unit(5)` for the common options of all unit configuration files. The common configuration items are configured in the generic \[Unit\] and \[Install\] sections. The timer specific configuration options are configured in the \[Timer\] section. For each timer file, a matching unit file must exist, describing the unit to activate when the timer elapses. By default, a service by the same name as the timer (except for the suffix) is activated. Example: a timer file `foo.timer` activates a matching service `foo.service`. The unit to activate may be controlled by `Unit=` (see below). Note that in case the unit to activate is already active at the time the timer elapses it is not restarted, but simply left running. There is no concept of spawning new service instances in this case. Due to this, services with `RemainAfterExit=yes` set (which stay around continuously even after the service's main process exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and then stay around forever. Target units, which by default do not deactivate on their own, can be activated repeatedly by timers by setting `StopWhenUnneeded=yes` on them. This will cause a target unit to be stopped immediately after its activation, if it is not a dependency of another running unit. # Automatic Dependencies ## Implicit Dependencies The following dependencies are implicitly added: - Timer units automatically gain a `Before=` dependency on the service they are supposed to activate. ## Default Dependencies The following dependencies are added unless `DefaultDependencies=no` is set: - Timer units will automatically have dependencies of type `Requires=` and `After=` on `sysinit.target`, a dependency of type `Before=` on `timers.target`, as well as `Conflicts=` and `Before=` on `shutdown.target` to ensure that they are stopped cleanly prior to system shutdown. Only timer units involved with early boot or late system shutdown should disable the `DefaultDependencies=` option. - Timer units with at least one `OnCalendar=` directive acquire a pair of additional `After=` dependencies on `time-set.target` and `time-sync.target`, in order to avoid being started before the system clock has been correctly set. See `systemd.special(7)` for details on these two targets. # Options Timer unit files may include \[Unit\] and \[Install\] sections, which are described in `systemd.unit(5)`. Timer unit files must include a \[Timer\] section, which carries information about the timer it defines. The options specific to the \[Timer\] section of timer units are the following: `OnActiveSec=`; `OnBootSec=`; `OnStartupSec=`; `OnUnitActiveSec=`; `OnUnitInactiveSec=` Defines monotonic timers relative to different starting points: | Setting | Meaning | |----|----| | `OnActiveSec=` | Defines a timer relative to the moment the timer unit itself is activated. | | `OnBootSec=` | Defines a timer relative to when the machine was booted up. In containers, for the system manager instance, this is mapped to `OnStartupSec=`, making both equivalent. | | `OnStartupSec=` | Defines a timer relative to when the service manager was first started. For system timer units this is very similar to `OnBootSec=` as the system service manager is generally started very early at boot. It's primarily useful when configured in units running in the per-user service manager, as the user service manager is generally started on first login only, not already during boot. | | `OnUnitActiveSec=` | Defines a timer relative to when the unit the timer unit is activating was last activated. | | `OnUnitInactiveSec=` | Defines a timer relative to when the unit the timer unit is activating was last deactivated. | Settings and their starting points Multiple directives may be combined of the same and of different types, in which case the timer unit will trigger whenever any of the specified timer expressions elapse. For example, by combining `OnBootSec=` and `OnUnitActiveSec=`, it is possible to define a timer that elapses in regular intervals and activates a specific service each time. Moreover, both monotonic time expressions and `OnCalendar=` calendar expressions may be combined in the same timer unit. The arguments to the directives are time spans configured in seconds. Example: "OnBootSec=50" means 50s after boot-up. The argument may also include time units. Example: "OnBootSec=5h 30min" means 5 hours and 30 minutes after boot-up. For details about the syntax of time spans, see `systemd.time(7)`. If a timer configured with `OnBootSec=` or `OnStartupSec=` is already in the past when the timer unit is activated, it will immediately elapse and the configured unit is started. This is not the case for timers defined in the other directives. These are monotonic timers, independent of wall-clock time and timezones. If the computer is temporarily suspended, the monotonic clock generally pauses, too. Note that if `WakeSystem=` is used, a different monotonic clock is selected that continues to advance while the system is suspended and thus can be used as the trigger to resume the system. If the empty string is assigned to any of these options, the list of timers is reset (both monotonic timers and `OnCalendar=` timers, see below), and all prior assignments will have no effect. Note that timers do not necessarily expire at the precise time configured with these settings, as they are subject to the `AccuracySec=` setting below. `OnCalendar=` Defines realtime (i.e. wallclock) timers with calendar event expressions. See `systemd.time(7)` for more information on the syntax of calendar event expressions. Otherwise, the semantics are similar to `OnActiveSec=` and related settings. Note that timers do not necessarily expire at the precise time configured with this setting, as it is subject to the `AccuracySec=` setting below. May be specified more than once, in which case the timer unit will trigger whenever any of the specified expressions elapse. Moreover, calendar timers and monotonic timers (see above) may be combined within the same timer unit. If the empty string is assigned to any of these options, the list of timers is reset (both `OnCalendar=` timers and monotonic timers, see above), and all prior assignments will have no effect. Note that calendar timers might be triggered at unexpected times if the system's realtime clock is not set correctly. Specifically, on systems that lack a battery-buffered Realtime Clock (RTC) it might be wise to enable `systemd-time-wait-sync.service` to ensure the clock is adjusted to a network time source *before* the timer event is set up. Timer units with at least one `OnCalendar=` expression are automatically ordered after `time-sync.target`, which `systemd-time-wait-sync.service` is ordered before. When a system is temporarily put to sleep (i.e. system suspend or hibernation) the realtime clock does not pause. When a calendar timer elapses while the system is sleeping it will not be acted on immediately, but once the system is later resumed it will catch up and process all timers that triggered while the system was sleeping. Note that if a calendar timer elapsed more than once while the system was continuously sleeping the timer will only result in a single service activation. If `WakeSystem=` (see below) is enabled a calendar time event elapsing while the system is suspended will cause the system to wake up (under the condition the system's hardware supports time-triggered wake-up functionality). `AccuracySec=` Specify the accuracy the timer shall elapse with. Defaults to 1min. The timer is scheduled to elapse within a time window starting with the time specified in `OnCalendar=`, `OnActiveSec=`, `OnBootSec=`, `OnStartupSec=`, `OnUnitActiveSec=` or `OnUnitInactiveSec=` and ending the time configured with `AccuracySec=` later. Within this time window, the expiry time will be placed at a host-specific, randomized, but stable position that is synchronized between all local timer units. This is done in order to optimize power consumption to suppress unnecessary CPU wake-ups. To get best accuracy, set this option to 1us. Note that the timer is still subject to the timer slack configured via `systemd-system.conf(5)`'s `TimerSlackNSec=` setting. See `prctl(2)` for details. To optimize power consumption, make sure to set this value as high as possible and as low as necessary. Note that this setting is primarily a power saving option that allows coalescing CPU wake-ups. It should not be confused with `RandomizedDelaySec=` (see below) which adds a random value to the time the timer shall elapse next and whose purpose is the opposite: to stretch elapsing of timer events over a longer period to reduce workload spikes. For further details and explanations and how both settings play together, see below. `RandomizedDelaySec=` Delay the timer by a randomly selected, evenly distributed amount of time between 0 and the specified time value. Defaults to 0, indicating that no randomized delay shall be applied. Each timer unit will determine this delay randomly before each iteration, unless modified with `FixedRandomDelay=`, see below. The delay is added on top of the next determined elapsing time or the service manager's startup time, whichever is later. This setting is useful to stretch dispatching of similarly configured timer events over a certain time interval, to prevent them from firing all at the same time, possibly resulting in resource congestion on the local system. Note the relation to `AccuracySec=` above: the latter allows the service manager to coalesce timer events within a specified time range in order to minimize wakeups, while this setting does the opposite: it stretches timer events over an interval, to make it unlikely that they fire simultaneously. If `RandomizedDelaySec=` and `AccuracySec=` are used in conjunction, first the randomized delay is added, and then the result is possibly further shifted to coalesce it with other timer events happening on the system. As mentioned above `AccuracySec=` defaults to 1 minute and `RandomizedDelaySec=` to 0, thus encouraging coalescing of timer events. In order to optimally stretch timer events over a certain range of time, set `AccuracySec=1us` and `RandomizedDelaySec=` to some higher value. `FixedRandomDelay=` Takes a boolean argument. When enabled, the randomized delay specified by `RandomizedDelaySec=` is chosen deterministically, and remains stable between all firings of the same timer, even if the manager is restarted. The delay is derived from the machine ID, the manager's user identifier, and the timer unit's name. This effectively creates a unique fixed offset for each timer, reducing the jitter in firings of an individual timer while still avoiding firing at the same time as other similarly configured timers. This setting has an effect only if `RandomizedDelaySec=` is not 0. Defaults to `false`. `RandomizedOffsetSec=` Offsets the timer by a stable, randomly-selected, and evenly distributed amount of time between 0 and the specified time value. Defaults to 0, indicating that no such offset shall be applied. The offset is chosen deterministically, and is derived the same way as `FixedRandomDelay=`, see above. The offset is added on top of the next determined elapsing time. This setting only has an effect on timers configured with `OnCalendar=`, and it can be combined with `RandomizedDelaySec=`. Much like `RandomizedDelaySec=`, this setting is for distributing timer events to prevent them from firing all at once. However, this setting is most useful to prevent resource congestion on a remote service, from a fleet of similarly-configured clients. Unlike `RandomizedDelaySec=`, this setting applies its offset with no regard to manager startup time. This maintains the periodicity of configured `OnCalendar=` events across manager restarts. For example, let's say you're running a backup service and have a fleet of laptops that wish to make backups weekly. To distribute load on the backup service, each laptop should randomly pick a weekday to upload its backups. This could be achieved by setting `OnCalendar=` to `weekly`, and then configuring a `RandomizedDelaySec=` of `5 days` with `FixedRandomDelay=` enabled. Let's say that some laptop randomly chooses a delay of 4 days. If this laptop is restarted more often than that, then the timer will never fire: on each fresh boot, the 4 day delay is restarted and will not be finished by the time of the next shutdown. Instead, you should use `RandomizedOffsetSec=`, which will maintain the configured weekly cadence of timer events, even across reboots. `DeferReactivation=` Takes a boolean argument. When enabled, the timer schedules the next elapse based on the trigger unit entering inactivity, instead of the last trigger time. This is most apparent in the case where the service unit takes longer to run than the timer interval. With this setting enabled, the timer will schedule the next elapse based on when the service finishes running, and so it will have to wait until the next realtime elapse time to trigger. Otherwise, the default behavior is for the timer unit to immediately trigger again once the service finishes running. This happens because the timer schedules the next elapse based on the previous trigger time, and since the interval is shorter than the service runtime, that elapse will be in the past, causing it to immediately trigger once done. This setting has an effect only if a realtime timer has been specified with `OnCalendar=`. Defaults to `false`. `OnClockChange=`; `OnTimezoneChange=` These options take boolean arguments. When true, the service unit will be triggered when the system clock (`CLOCK_REALTIME`) jumps relative to the monotonic clock (`CLOCK_MONOTONIC`), or when the local system timezone is modified. These options can be used alone or in combination with other timer expressions (see above) within the same timer unit. These options default to `false`. `Unit=` The unit to activate when this timer elapses. The argument is a unit name, whose suffix is not `.timer`. If not specified, this value defaults to a service that has the same name as the timer unit, except for the suffix. (See above.) It is recommended that the unit name that is activated and the unit name of the timer unit are named identically, except for the suffix. `Persistent=` Takes a boolean argument. If true, the time when the service unit was last triggered is stored on disk. When the timer is activated, the service unit is triggered immediately if it would have been triggered at least once during the time when the timer was inactive. Such triggering is nonetheless subject to the delay imposed by `RandomizedDelaySec=`. This is useful to catch up on missed runs of the service when the system was powered down. Note that this setting only has an effect on timers configured with `OnCalendar=`. Defaults to `false`. Use `systemctl clean --what=state …` on the timer unit to remove the timestamp file maintained by this option from disk. In particular, use this command before uninstalling a timer unit. See `systemctl(1)` for details. `WakeSystem=` Takes a boolean argument. If true, an elapsing timer will cause the system to resume from suspend, should it be suspended and if the system supports this. Note that this option will only make sure the system resumes on the appropriate times, it will not take care of suspending it again after any work that is to be done is finished. Defaults to `false`. Note that this functionality requires privileges and is thus generally only available in the system service manager. Note that behaviour of monotonic clock timers (as configured with `OnActiveSec=`, `OnBootSec=`, `OnStartupSec=`, `OnUnitActiveSec=`, `OnUnitInactiveSec=`, see above) is altered depending on this option. If false, a monotonic clock is used that is paused during system suspend (`CLOCK_MONOTONIC`), if true a different monotonic clock is used that continues advancing during system suspend (`CLOCK_BOOTTIME`), see `clock_getres(2)` for details. `RemainAfterElapse=` Takes a boolean argument. If true, a timer will stay loaded, and its state remains queryable even after it elapsed and the associated unit (as configured with `Unit=`, see above) deactivated again. If false, an elapsed timer unit that cannot elapse anymore is unloaded once its associated unit deactivated again. Turning this off is particularly useful for transient timer units. Note that this setting has an effect when repeatedly starting a timer unit: if `RemainAfterElapse=` is on, starting the timer a second time has no effect. However, if `RemainAfterElapse=` is off and the timer unit was already unloaded, it can be started again, and thus the service can be triggered multiple times. Defaults to `true`. # See Also Environment variables with details on the trigger will be set for triggered units. See the `Environment Variables Set or Propagated by the Service Manager` section in `systemd.exec(5)` for more details. `systemd(1)`, `systemctl(1)`, `systemd.unit(5)`, `systemd.service(5)`, `systemd.time(7)`, `systemd.directives(7)`, `systemd-system.conf(5)`, `prctl(2)` # systemd.unit systemd systemd.unit 5 systemd.unit Unit configuration `service.service`, `socket.socket`, `device.device`, `mount.mount`, `automount.automount`, `swap.swap`, `target.target`, `path.path`, `timer.timer`, `slice.slice`, `scope.scope` ## System Unit Search Path `/etc/systemd/system.control/*`, `/run/systemd/system.control/*`, `/run/systemd/transient/*`, `/run/systemd/generator.early/*`, `/etc/systemd/system/*`, `/etc/systemd/system.attached/*`, `/run/systemd/system/*`, `/run/systemd/system.attached/*`, `/run/systemd/generator/*`, `…`, `/usr/local/lib/systemd/system/*`, `/usr/lib/systemd/system/*`, `/run/systemd/generator.late/*` ## User Unit Search Path `~/.config/systemd/user.control/*`, `$XDG_RUNTIME_DIR/systemd/user.control/*`, `$XDG_RUNTIME_DIR/systemd/transient/*`, `$XDG_RUNTIME_DIR/systemd/generator.early/*`, `~/.config/systemd/user/*`, `$XDG_CONFIG_DIRS/systemd/user/*`, `/etc/systemd/user/*`, `$XDG_RUNTIME_DIR/systemd/user/*`, `/run/systemd/user/*`, `$XDG_RUNTIME_DIR/systemd/generator/*`, `$XDG_DATA_HOME/systemd/user/*`, `$XDG_DATA_DIRS/systemd/user/*`, `…`, `/usr/local/lib/systemd/user/*`, `/usr/lib/systemd/user/*`, `$XDG_RUNTIME_DIR/systemd/generator.late/*` # Description A unit file is a plain text ini-style file that encodes information about a service, a socket, a device, a mount point, an automount point, a swap file or partition, a start-up target, a watched file system path, a timer controlled and supervised by `systemd(1)`, a resource management slice or a group of externally created processes. See `systemd.syntax(7)` for a general description of the syntax. This man page lists the common configuration options of all the unit types. These options need to be configured in the \[Unit\] or \[Install\] sections of the unit files. In addition to the generic \[Unit\] and \[Install\] sections described here, each unit may have a type-specific section, e.g. \[Service\] for a service unit. See the respective man pages for more information: `systemd.service(5)`, `systemd.socket(5)`, `systemd.device(5)`, `systemd.mount(5)`, `systemd.automount(5)`, `systemd.swap(5)`, `systemd.target(5)`, `systemd.path(5)`, `systemd.timer(5)`, `systemd.slice(5)`, `systemd.scope(5)`. Unit files are loaded from a set of paths determined during compilation, described in the next section. Valid unit names consist of a "unit name prefix", and a suffix specifying the unit type which begins with a dot. The "unit name prefix" must consist of one or more valid characters (ASCII letters, digits, `:`, `-`, `_`, `.`, and `\`). The total length of the unit name including the suffix must not exceed 255 characters. The unit type suffix must be one of `.service`, `.socket`, `.device`, `.mount`, `.automount`, `.swap`, `.target`, `.path`, `.timer`, `.slice`, or `.scope`. Unit names can be parameterized by a single argument called the "instance name". The unit is then constructed based on a "template file" which serves as the definition of multiple services or other units. A template unit must have a single `@` at the end of the unit name prefix (right before the type suffix). The name of the full unit is formed by inserting the instance name between `@` and the unit type suffix. In the unit file itself, the instance parameter may be referred to using `%i` and other specifiers, see below. Unit files may contain additional options on top of those listed here. If systemd encounters an unknown option, it will write a warning log message but continue loading the unit. If an option or section name is prefixed with `X-`, it is ignored completely by systemd. Options within an ignored section do not need the prefix. Applications may use this to include additional information in the unit files. To access those options, applications need to parse the unit files on their own. Units can be aliased (have an alternative name), by creating a symlink from the new name to the existing name in one of the unit search paths. For example, `systemd-networkd.service` has the alias `dbus-org.freedesktop.network1.service`, created during installation as a symlink, so when `systemd` is asked through D-Bus to load `dbus-org.freedesktop.network1.service`, it'll load `systemd-networkd.service`. As another example, `default.target` — the default system target started at boot — is commonly aliased to either `multi-user.target` or `graphical.target` to select what is started by default. Alias names may be used in commands like `disable`, `start`, `stop`, `status`, and similar, and in all unit dependency directives, including `Wants=`, `Requires=`, `Before=`, `After=`. Aliases cannot be used with the `preset` command. Aliases obey the following restrictions: a unit of a certain type (`.service`, `.socket`, …) can only be aliased by a name with the same type suffix. A plain unit (not a template or an instance), may only be aliased by a plain name. A template instance may only be aliased by another template instance, and the instance part must be identical. A template may be aliased by another template (in which case the alias applies to all instances of the template). As a special case, a template instance (e.g. `alias@inst.service`) may be a symlink to different template (e.g. `template@inst.service`). In that case, just this specific instance is aliased, while other instances of the template (e.g. `alias@foo.service`, `alias@bar.service`) are not aliased. Those rules preserve the requirement that the instance (if any) is always uniquely defined for a given unit and all its aliases. The target of alias symlink must point to a valid unit file location, i.e. the symlink target name must match the symlink source name as described, and the destination path must be in one of the unit search paths, see UNIT FILE LOAD PATH section below for more details. Note that the target file might not exist, i.e. the symlink may be dangling. Unit files may specify aliases through the `Alias=` directive in the \[Install\] section. When the unit is enabled, symlinks will be created for those names, and removed when the unit is disabled. For example, `reboot.target` specifies `Alias=ctrl-alt-del.target`, so when enabled, the symlink `/etc/systemd/system/ctrl-alt-del.target` pointing to the `reboot.target` file will be created, and when Ctrl+Alt+Del is invoked, `systemd` will look for `ctrl-alt-del.target`, follow the symlink to `reboot.target`, and execute `reboot.service` as part of that target. `systemd` does not look at the \[Install\] section at all during normal operation, so any directives in that section only have an effect through the symlinks created during enablement. Along with a unit file `foo.service`, the directory `foo.service.wants/` may exist. All unit files symlinked from such a directory are implicitly added as dependencies of type `Wants=` to the unit. Similar functionality exists for `Requires=` type dependencies as well, the directory suffix is `.requires/` in this case. This functionality is useful to hook units into the start-up of other units, without having to modify their unit files. For details about the semantics of `Wants=` and `Requires=`, see below. The preferred way to create symlinks in the `.wants/` or `.requires/` directories is by specifying the dependency in \[Install\] section of the target unit, and creating the symlink in the file system with the `enable` or `preset` commands of `systemctl(1)`. The target can be a normal unit (either plain or a specific instance of a template unit). In case when the source unit is a template, the target can also be a template, in which case the instance will be "propagated" to the target unit to form a valid unit instance. The target of symlinks in `.wants/` or `.requires/` must thus point to a valid unit file location, i.e. the symlink target name must satisfy the described requirements, and the destination path must be in one of the unit search paths, see UNIT FILE LOAD PATH section below for more details. Note that the target file might not exist, i.e. the symlink may be dangling. Along with a unit file `foo.service`, a "drop-in" directory `foo.service.d/` may exist. All files with the suffix `.conf` from this directory will be merged in the alphanumeric order and parsed after the main unit file itself has been parsed. This is useful to alter or add configuration settings for a unit, without having to modify unit files. Each drop-in file must contain appropriate section headers. For instantiated units, this logic will first look for the instance `.d/` subdirectory (e.g. `foo@bar.service.d/`) and read its `.conf` files, followed by the template `.d/` subdirectory (e.g. `foo@.service.d/`) and the `.conf` files there. Moreover, for unit names containing dashes (`-`), the set of directories generated by repeatedly truncating the unit name after all dashes is searched too. Specifically, for a unit name `foo-bar-baz.service` not only the regular drop-in directory `foo-bar-baz.service.d/` is searched but also both `foo-bar-.service.d/` and `foo-.service.d/`. This is useful for defining common drop-ins for a set of related units, whose names begin with a common prefix. This scheme is particularly useful for mount, automount and slice units, whose systematic naming structure is built around dashes as component separators. Note that equally named drop-in files further down the prefix hierarchy override those further up, i.e. `foo-bar-.service.d/10-override.conf` overrides `foo-.service.d/10-override.conf`. In cases of unit aliases (described above), dropins for the aliased name and all aliases are loaded. In the example of `default.target` aliasing `graphical.target`, `default.target.d/`, `default.target.wants/`, `default.target.requires/`, `graphical.target.d/`, `graphical.target.wants/`, `graphical.target.requires/` would all be read. For templates, dropins for the template, any template aliases, the template instance, and all alias instances are read. When just a specific template instance is aliased, then the dropins for the target template, the target template instance, and the alias template instance are read. In addition to `/etc/systemd/system`, the drop-in `.d/` directories for system services can be placed in `/usr/lib/systemd/system` or `/run/systemd/system` directories. Drop-in files in `/etc/` take precedence over those in `/run/` which in turn take precedence over those in `/usr/lib/`. Drop-in files under any of these directories take precedence over unit files wherever located. Multiple drop-in files with different names are applied in lexicographic order, regardless of which of the directories they reside in. Units also support a top-level drop-in with `type.d/`, where \ may be e.g. `service` or `socket`, that allows altering or adding to the settings of all corresponding unit files on the system. The formatting and precedence of applying drop-in configurations follow what is defined above. Files in `type.d/` have lower precedence compared to files in name-specific override directories. The usual rules apply: multiple drop-in files with different names are applied in lexicographic order, regardless of which of the directories they reside in, so a file in `type.d/` applies to a unit only if there are no drop-ins or masks with that name in directories with higher precedence. See Examples. Note that while systemd offers a flexible dependency system between units it is recommended to use this functionality only sparingly and instead rely on techniques such as bus-based or socket-based activation which make dependencies implicit, resulting in a both simpler and more flexible system. As mentioned above, a unit may be instantiated from a template file. This allows creation of multiple units from a single configuration file. If systemd looks for a unit configuration file, it will first search for the literal unit name in the file system. If that yields no success and the unit name contains an `@` character, systemd will look for a unit template that shares the same name but with the instance string (i.e. the part between the `@` character and the suffix) removed. Example: if a service `getty@tty3.service` is requested and no file by that name is found, systemd will look for `getty@.service` and instantiate a service from that configuration file if it is found. To refer to the instance string from within the configuration file you may use the special `%i` specifier in many of the configuration options. See below for details. If a unit file is empty (i.e. has the file size 0) or is symlinked to `/dev/null`, its configuration will not be loaded and it appears with a load state of `masked`, and cannot be activated. Use this as an effective way to fully disable a unit, making it impossible to start it even manually. Files (including directories) with names that match certain patterns are generally ignored. This includes names that start with a `.` or end with a `.ignore`. When unit aliasing is introduced during reload/reexec (e.g., converting `b.service` to a symlink pointing to `a.service`), the running state of the canonical unit (`a.service`) is preserved. The old serialized state of the now-aliased unit is migrated to a new stub orphaned unit to prevent stale data from corrupting the canonical unit's live state. Dependencies referencing the alias name are automatically resolved to the canonical unit, and the dependency graph is rebuilt from unit files, ensuring consistency. If the now-aliased unit had resources such as running processes, they will now be tracked under the new orphaned unit. Once all resources are gone (e.g. all processes have exited) the orphaned unit will be garbage collected automatically. The unit file format is covered by the [Interface Portability and Stability Promise](https://systemd.io/PORTABILITY_AND_STABILITY/). # String Escaping for Inclusion in Unit Names Sometimes it is useful to convert arbitrary strings into unit names. To facilitate this, a method of string escaping is used, in order to map strings containing arbitrary byte values (except `NUL`) into valid unit names and their restricted character set. A common special case are unit names that reflect paths to objects in the file system hierarchy. Example: a device unit `dev-sda.device` refers to a device with the device node `/dev/sda` in the file system. The escaping algorithm operates as follows: given a string, any `/` character is replaced by `-`, and all other characters which are not ASCII alphanumerics, `:`, `_` or `.` are replaced by C-style `\x2d` escapes. In addition, `.` is replaced with such a C-style escape when it would appear as the first character in the escaped string. When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the root directory `/` is encoded as single dash `-`. In addition, any leading, trailing or duplicate `/` characters are removed from the string before transformation. Example: `/foo//bar/baz/` becomes `foo-bar-baz`. This escaping is fully reversible, as long as it is known whether the escaped string was a path (the unescaping results are different for paths and non-path strings). The `systemd-escape(1)` command may be used to apply and reverse escaping on arbitrary strings. Use `systemd-escape --path` to escape path strings, and `systemd-escape` without `--path` otherwise. # Automatic dependencies ## Implicit Dependencies A number of unit dependencies are implicitly established, depending on unit type and unit configuration. These implicit dependencies can make unit configuration file cleaner. For the implicit dependencies in each unit type, please refer to section "Implicit Dependencies" in respective man pages. For example, service units with `Type=dbus` automatically acquire dependencies of type `Requires=` and `After=` on `dbus.socket`. See `systemd.service(5)` for details. ## Default Dependencies Default dependencies are similar to implicit dependencies, but can be turned on and off by setting `DefaultDependencies=` to `yes` (the default) and `no`, while implicit dependencies are always in effect. See section "Default Dependencies" in respective man pages for the effect of enabling `DefaultDependencies=` in each unit types. For example, target units will complement all configured dependencies of type `Wants=` or `Requires=` with dependencies of type `After=`. See `systemd.target(5)` for details. Note that this behavior can be opted out by setting `DefaultDependencies=no` in the specified units, or it can be selectively overridden via an explicit `Before=` dependency. # Unit File Load Path Unit files are loaded from a set of paths determined during compilation, described in the two tables below. Unit files found in directories listed earlier override files with the same name in directories lower in the list . When the variable `$SYSTEMD_UNIT_PATH` is set, the contents of this variable overrides the unit load path. If `$SYSTEMD_UNIT_PATH` ends with an empty component (`:`), the usual unit load path will be appended to the contents of the variable.
Load path when running in system mode (--system).
Path Description
/etc/systemd/system.control Persistent and transient configuration created using the dbus API
/run/systemd/system.control
/run/systemd/transient Dynamic configuration for transient units
/run/systemd/generator.early Generated units with high priority (see <early-dir> in systemd.generator(7))
/etc/systemd/system System units created by the administrator
/run/systemd/system Runtime units
/run/systemd/generator Generated units with medium priority (see <normal-dir> in systemd.generator(7))
/usr/local/lib/systemd/system System units installed by the administrator
/usr/lib/systemd/system System units installed by the distribution package manager
/run/systemd/generator.late Generated units with low priority (see <late-dir> in systemd.generator(7))
Load path when running in user mode (--user).
Path Description
$XDG_CONFIG_HOME/systemd/user.control or ~/.config/systemd/user.control Persistent and transient configuration created using the dbus API ($XDG_CONFIG_HOME is used if set, ~/.config otherwise)
$XDG_RUNTIME_DIR/systemd/user.control
$XDG_RUNTIME_DIR/systemd/transient Dynamic configuration for transient units
$XDG_RUNTIME_DIR/systemd/generator.early Generated units with high priority (see <early-dir> in systemd.generator(7))
$XDG_CONFIG_HOME/systemd/user or $HOME/.config/systemd/user User configuration ($XDG_CONFIG_HOME is used if set, ~/.config otherwise)
$XDG_CONFIG_DIRS/systemd/user or /etc/xdg/systemd/user Additional configuration directories as specified by the XDG base directory specification ($XDG_CONFIG_DIRS is used if set, /etc/xdg otherwise)
/etc/systemd/user User units created by the administrator
$XDG_RUNTIME_DIR/systemd/user Runtime units (only used when $XDG_RUNTIME_DIR is set)
/run/systemd/user Runtime units
$XDG_RUNTIME_DIR/systemd/generator Generated units with medium priority (see <normal-dir> in systemd.generator(7))
$XDG_DATA_HOME/systemd/user or $HOME/.local/share/systemd/user Units of packages that have been installed in the home directory ($XDG_DATA_HOME is used if set, ~/.local/share otherwise)
$XDG_DATA_DIRS/systemd/user or /usr/local/share/systemd/user and /usr/share/systemd/user Additional data directories as specified by the XDG base directory specification ($XDG_DATA_DIRS is used if set, /usr/local/share and /usr/share otherwise)
$dir/systemd/user for each $dir in $XDG_DATA_DIRS Additional locations for installed user units, one for each entry in $XDG_DATA_DIRS
/usr/local/lib/systemd/user User units installed by the administrator
/usr/lib/systemd/user User units installed by the distribution package manager
$XDG_RUNTIME_DIR/systemd/generator.late Generated units with low priority (see <late-dir> in systemd.generator(7))
The set of load paths for the user manager instance may be augmented or changed using various environment variables. And environment variables may in turn be set using environment generators, see `systemd.environment-generator(7)`. In particular, `$XDG_DATA_HOME` and `$XDG_DATA_DIRS` may be easily set using `systemd-environment-d-generator(8)`. Thus, directories listed here are just the defaults. To see the actual list that would be used based on compilation options and current environment use systemd-analyze --user unit-paths Moreover, additional units might be loaded into systemd from directories not on the unit load path by creating a symlink pointing to a unit file in the directories. You can use `systemctl link` for this; see `systemctl(1)`. The file system where the linked unit files are located must be accessible when systemd is started (e.g. anything underneath `/home/` or `/var/` is not allowed, unless those directories are located on the root file system). It is important to distinguish "linked unit files" from "unit file aliases": any symlink where the symlink *target* is within the unit load path becomes an alias: the source name and the target file name must satisfy specific constraints listed above in the discussion of aliases, but the symlink target does not have to exist, and in fact the symlink target path is not used, except to check whether the target is within the unit load path. In contrast, a symlink which goes outside of the unit load path signifies a linked unit file. The symlink is followed when loading the file, but the destination name is otherwise unused (and may even not be a valid unit file name). For example, symlinks `/etc/systemd/system/alias1.service` → `service1.service`, `/etc/systemd/system/alias2.service` → `/usr/lib/systemd/service1.service`, `/etc/systemd/system/alias3.service` → `/etc/systemd/system/service1.service` are all valid aliases and `service1.service` will have four names, even if the unit file is located at `/run/systemd/system/service1.service`. In contrast, a symlink `/etc/systemd/system/link1.service` → `../link1_service_file` means that `link1.service` is a "linked unit" and the contents of `/etc/systemd/link1_service_file` provide its configuration. # Unit Garbage Collection The system and service manager loads a unit's configuration automatically when a unit is referenced for the first time. It will automatically unload the unit configuration and state again when the unit is not needed anymore ("garbage collection"). A unit may be referenced through a number of different mechanisms: 1. Another loaded unit references it with a dependency such as `After=`, `Wants=`, … 2. The unit is currently starting, running, reloading or stopping. 3. The unit is currently in the `failed` state. (But see below.) 4. A job for the unit is pending. 5. The unit is pinned by an active IPC client program. 6. The unit is a special "perpetual" unit that is always active and loaded. Examples for perpetual units are the root mount unit `-.mount` or the scope unit `init.scope` that the service manager itself lives in. 7. The unit has running processes associated with it. The garbage collection logic may be altered with the `CollectMode=` option, which allows configuration whether automatic unloading of units that are in `failed` state is permissible, see below. Note that when a unit's configuration and state is unloaded, all execution results, such as exit codes, exit signals, resource consumption and other statistics are lost, except for what is stored in the log subsystem. Use `systemctl daemon-reload` or an equivalent command to reload unit configuration while the unit is already loaded. In this case, all configuration settings are flushed out and replaced with the new configuration (which however might not be in effect immediately), however all runtime state is saved/restored. # \[Unit\] Section Options The unit file may include a \[Unit\] section, which carries generic information about the unit that is not dependent on the type of unit: `Description=` A brief, meaningful, human-readable text identifying the unit. This may be used by `systemd` (and suitable UIs) as a user-visible label for the unit, so this string should identify the unit rather than just describe it, despite the name. This string also should not just repeat the unit name. `Apache HTTP Server` or `Postfix Mail Server` are good examples. Bad examples are `high-performance lightweight HTTP server` (too generic) or `Apache` (meaningless for people who do not know the Apache HTTP server project, duplicates the unit name). `systemd` may use this string as a noun in status messages (`Starting Description...`, `Started Description.`, `Reached target Description.`, `Failed to start Description.`), so it should be capitalized, and should not be a full sentence, or a phrase with a verb conjugated in the present continuous, or end in a full stop. Bad examples include `exiting the container`, `updating the database once per day.`, or `OpenSSH server second instance daemon`. `Documentation=` A space-separated list of URIs referencing documentation for this unit or its configuration. Accepted are only URIs of the types `http://`, `https://`, `file:`, `info:`, `man:`. For more information about the syntax of these URIs, see `uri(7)`. The URIs should be listed in order of relevance, starting with the most relevant. It is a good idea to first reference documentation that explains what the unit's purpose is, followed by how it is configured, followed by any other related documentation. This option may be specified more than once, in which case the specified list of URIs is merged. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect. `Wants=` Configures (weak) requirement dependencies on other units. This option may be specified more than once or multiple space-separated units may be specified in one option in which case dependencies for all listed names will be created. Dependencies of this type may also be configured outside of the unit configuration file by adding a symlink to a `.wants/` directory accompanying the unit file. For details, see above. Units listed in this option will be started if the configuring unit is. However, if the listed units fail to start or cannot be added to the transaction, this has no impact on the validity of the transaction as a whole, and this unit will still be started. This is the recommended way to hook the start-up of one unit to the start-up of another unit. Note that requirement dependencies do not influence the order in which services are started or stopped. This has to be configured independently with the `After=` or `Before=` options. If unit `foo.service` pulls in unit `bar.service` as configured with `Wants=` and no ordering is configured with `After=` or `Before=`, then both units will be started simultaneously and without any delay between them if `foo.service` is activated. `Requires=` Similar to `Wants=`, but declares a stronger requirement dependency. Dependencies of this type may also be configured by adding a symlink to a `.requires/` directory accompanying the unit file. If this unit gets activated, the units listed will be activated as well. If one of the other units fails to activate, and an ordering dependency `After=` on the failing unit is set, this unit will not be started. Besides, with or without specifying `After=`, this unit will be stopped (or restarted) if one of the other units is explicitly stopped (or restarted). Often, it is a better choice to use `Wants=` instead of `Requires=` in order to achieve a system that is more robust when dealing with failing services. Note that this dependency type does not imply that the other unit always has to be in active state when this unit is running. Specifically: failing condition checks (such as `ConditionPathExists=`, `ConditionPathIsSymbolicLink=`, … — see below) do not cause the start job of a unit with a `Requires=` dependency on it to fail. Also, some unit types may deactivate on their own (for example, a service process may decide to exit cleanly, or a device may be unplugged by the user), which is not propagated to units having a `Requires=` dependency. Use the `BindsTo=` dependency type together with `After=` to ensure that a unit may never be in active state without a specific other unit also in active state (see below). `Requisite=` Similar to `Requires=`. However, if the units listed here are not started already, they will not be started and the starting of this unit will fail immediately. `Requisite=` does not imply an ordering dependency, even if both units are started in the same transaction. Hence this setting should usually be combined with `After=`, to ensure this unit is not started before the other unit. When `Requisite=b.service` is used on `a.service`, this dependency will show as `RequisiteOf=a.service` in property listing of `b.service`. `RequisiteOf=` dependency cannot be specified directly. `BindsTo=` Configures requirement dependencies, very similar in style to `Requires=`. However, this dependency type is stronger: in addition to the effects of `Requires=`, which already stops (or restarts) the configuring unit when a listed unit is explicitly stopped (or restarted), it also does so when a listed unit stops unexpectedly (which includes when it fails). Units can suddenly, unexpectedly enter inactive state for different reasons: the main process of a service unit might terminate on its own choice, the backing device of a device unit might be unplugged or the mount point of a mount unit might be unmounted without involvement of the system and service manager. When used in conjunction with `After=` on the same unit the behaviour of `BindsTo=` is even stronger. In this case, the unit bound to strictly has to be in active state for this unit to also be in active state. This not only means a unit bound to another unit that suddenly enters inactive state, but also one that is bound to another unit that gets skipped due to an unmet condition check (such as `ConditionPathExists=`, `ConditionPathIsSymbolicLink=`, … — see below) will be stopped, should it be running. Hence, in many cases it is best to combine `BindsTo=` with `After=`. When `BindsTo=b.service` is used on `a.service`, this dependency will show as `BoundBy=a.service` in property listing of `b.service`. `BoundBy=` dependency cannot be specified directly. `PartOf=` Configures dependencies similar to `Requires=`, but limited to stopping and restarting of units. When systemd stops or restarts the units listed here, the action is propagated to this unit. Note that this is a one-way dependency — changes to this unit do not affect the listed units. When `PartOf=b.service` is used on `a.service`, this dependency will show as `ConsistsOf=a.service` in property listing of `b.service`. `ConsistsOf=` dependency cannot be specified directly. `Upholds=` Configures dependencies similar to `Wants=`, but as long as this unit is up, all units listed in `Upholds=` are started whenever found to be inactive or failed, and no job is queued for them. While a `Wants=` dependency on another unit has a one-time effect when this units started, a `Upholds=` dependency on it has a continuous effect, constantly restarting the unit if necessary. This is an alternative to the `Restart=` setting of service units, to ensure they are kept running whatever happens. The restart happens without delay, and usual per-unit rate-limit applies. When `Upholds=b.service` is used on `a.service`, this dependency will show as `UpheldBy=a.service` in the property listing of `b.service`. `Conflicts=` A space-separated list of unit names. Configures negative requirement dependencies. If a unit has a `Conflicts=` requirement on a set of other units, then starting it will stop all of them and starting any of them will stop it. Note that this setting does not imply an ordering dependency, similarly to the `Wants=` and `Requires=` dependencies described above. This means that to ensure that the conflicting unit is stopped before the other unit is started, an `After=` or `Before=` dependency must be declared. It does not matter which of the two ordering dependencies is used, because stop jobs are always ordered before start jobs, see the discussion in `Before=`/`After=` below. If unit A that conflicts with unit B is scheduled to be started at the same time as B, the transaction will either fail (in case both are required parts of the transaction) or be modified to be fixed (in case one or both jobs are not a required part of the transaction). In the latter case, the job that is not required will be removed, or in case both are not required, the unit that conflicts will be started and the unit that is conflicted is stopped. `Before=`; `After=` These two settings expect a space-separated list of unit names. They may be specified more than once, in which case dependencies for all listed names are created. Those two settings configure ordering dependencies between units. If unit `foo.service` contains the setting `Before=bar.service` and both units are being started, `bar.service`'s start-up is delayed until `foo.service` has finished starting up. `After=` is the inverse of `Before=`, i.e. while `Before=` ensures that the configured unit is started before the listed unit begins starting up, `After=` ensures the opposite, that the listed unit is fully started up before the configured unit is started. When two units with an ordering dependency between them are shut down, the inverse of the start-up order is applied. I.e. if a unit is configured with `After=` on another unit, the former is stopped before the latter if both are shut down. Given two units with any ordering dependency between them, if one unit is shut down and the other is started up, the shutdown is ordered before the start-up. It does not matter if the ordering dependency is `After=` or `Before=`, in this case. It also does not matter which of the two is shut down, as long as one is shut down and the other is started up; the shutdown is ordered before the start-up in all cases. If two units have no ordering dependencies between them, they are shut down or started up simultaneously, and no ordering takes place. It depends on the unit type when precisely a unit has finished starting up. Most importantly, for service units start-up is considered completed for the purpose of `Before=`/`After=` when all its configured start-up commands have been invoked and they either failed or reported start-up success. Note that this includes `ExecStartPost=` (or `ExecStopPost=` for the shutdown case). Note that those settings are independent of and orthogonal to the requirement dependencies as configured by `Requires=`, `Wants=`, `Requisite=`, or `BindsTo=`. It is a common pattern to include a unit name in both the `After=` and `Wants=` options, in which case the unit listed will be started before the unit that is configured with these options. Note that `Before=` dependencies on device units have no effect and are not supported. Devices generally become available as a result of an external hotplug event, and systemd creates the corresponding device unit without delay. `OnFailure=` A space-separated list of one or more units that are activated when this unit enters the `failed` state. `OnSuccess=` A space-separated list of one or more units that are activated when this unit enters the `inactive` state. `PropagatesReloadTo=`; `ReloadPropagatedFrom=` A space-separated list of one or more units to which reload requests from this unit shall be propagated to, or units from which reload requests shall be propagated to this unit, respectively. Issuing a reload request on a unit will automatically also enqueue reload requests on all units that are linked to it using these two settings. `PropagatesStopTo=`; `StopPropagatedFrom=` A space-separated list of one or more units to which stop requests from this unit shall be propagated to, or units from which stop requests shall be propagated to this unit, respectively. Issuing a stop request on a unit will automatically also enqueue stop requests on all units that are linked to it using these two settings. `JoinsNamespaceOf=` For units that start processes (such as service units), lists one or more other units whose network and/or temporary file namespace to join. If this is specified on a unit (say, `a.service` has `JoinsNamespaceOf=b.service`), then the inverse dependency (`JoinsNamespaceOf=a.service` for b.service) is implied. This only applies to unit types which support the `PrivateNetwork=`, `NetworkNamespacePath=`, `PrivateIPC=`, `IPCNamespacePath=`, and `PrivateTmp=` directives (see `systemd.exec(5)` for details). If a unit that has this setting set is started, its processes will see the same `/tmp/`, `/var/tmp/`, IPC namespace and network namespace as one listed unit that is started. If multiple listed units are already started and these do not share their namespace, then it is not defined which namespace is joined. Note that this setting only has an effect if `PrivateNetwork=`/`NetworkNamespacePath=`, `PrivateIPC=`/`IPCNamespacePath=` and/or `PrivateTmp=` is enabled for both the unit that joins the namespace and the unit whose namespace is joined. `RequiresMountsFor=` Takes a space-separated list of absolute paths. Automatically adds dependencies of type `Requires=` and `After=` for all mount units required to access the specified path. Mount points marked with `noauto` are not mounted automatically through `local-fs.target`, but are still honored for the purposes of this option, i.e. they will be pulled in by this unit. `WantsMountsFor=` Same as `RequiresMountsFor=`, but adds dependencies of type `Wants=` instead of `Requires=`. `OnSuccessJobMode=`; `OnFailureJobMode=` Takes a value of `fail`, `replace`, `replace-irreversibly`, `isolate`, `flush`, `ignore-dependencies` or `ignore-requirements`. `OnFailureJobMode=` defaults to `replace`, `OnSuccessJobMode=` defaults to `fail`. Specifies how the units listed in `OnSuccess=`/`OnFailure=` will be enqueued. See `systemctl(1)`'s `--job-mode=` option for details on the possible values. If this is set to `isolate`, only a single unit may be listed in `OnSuccess=`/`OnFailure=`. `IgnoreOnIsolate=` Takes a boolean argument. If `true`, this unit will not be stopped when isolating another unit. Defaults to `false` for service, target, socket, timer, and path units, and `true` for slice, scope, device, swap, mount, and automount units. `StopWhenUnneeded=` Takes a boolean argument. If `true`, this unit will be stopped when it is no longer used. Note that, in order to minimize the work to be executed, systemd will not stop units by default unless they are conflicting with other units, or the user explicitly requested their shut down. If this option is set, a unit will be automatically cleaned up if no other active unit requires it. Defaults to `false`. `RefuseManualStart=`; `RefuseManualStop=` Takes a boolean argument. If `true`, this unit can only be activated or deactivated indirectly. In this case, explicit start-up or termination requested by the user is denied, however if it is started or stopped as a dependency of another unit, start-up or termination will succeed. This is mostly a safety feature to ensure that the user does not accidentally activate units that are not intended to be activated explicitly, and not accidentally deactivate units that are not intended to be deactivated. These options default to `false`. `AllowIsolate=` Takes a boolean argument. If `true`, this unit may be used with the `systemctl isolate` command. Otherwise, this will be refused. It probably is a good idea to leave this disabled except for target units that shall be used similar to runlevels in SysV init systems, just as a precaution to avoid unusable system states. This option defaults to `false`. `DefaultDependencies=` Takes a boolean argument. If `yes`, (the default), a few default dependencies will implicitly be created for the unit. The actual dependencies created depend on the unit type. For example, for service units, these dependencies ensure that the service is started only after basic system initialization is completed and is properly terminated on system shutdown. See the respective man pages for details. Generally, only services involved with early boot or late shutdown should set this option to `no`. It is highly recommended to leave this option enabled for the majority of common units. If set to `no`, this option does not disable all implicit dependencies, just non-essential ones. `SurviveFinalKillSignal=` Takes a boolean argument. Defaults to `no`. If `yes`, processes belonging to this unit will not be sent the final `SIGTERM` and `SIGKILL` signals during the final phase of the system shutdown process. This functionality replaces the older mechanism that allowed a program to set `argv[0][0] = '@'` as described at [systemd and Storage Daemons for the Root File System](https://systemd.io/ROOT_STORAGE_DAEMONS), which however continues to be supported. `CollectMode=` Tweaks the "garbage collection" algorithm for this unit. Takes one of `inactive` or `inactive-or-failed`. If set to `inactive` the unit will be unloaded if it is in the `inactive` state and is not referenced by clients, jobs or other units — however it is not unloaded if it is in the `failed` state. In `failed` mode, failed units are not unloaded until the user invoked `systemctl reset-failed` on them to reset the `failed` state, or an equivalent command. This behaviour is altered if this option is set to `inactive-or-failed`: in this case, the unit is unloaded even if the unit is in a `failed` state, and thus an explicitly resetting of the `failed` state is not necessary. Note that if this mode is used unit results (such as exit codes, exit signals, consumed resources, …) are flushed out immediately after the unit completed, except for what is stored in the logging subsystem. Defaults to `inactive`. Since v261, if `FileDescriptorStorePreserve=` is set to `yes`, and the unit has file descriptors stored, garbage collection will be disabled until the unit is removed, the service manager exits, or the file descriptors get `EPOLLHUP` or `EPOLLERR`. `FailureAction=`; `SuccessAction=` Configure the action to take when the unit stops and enters a failed state or inactive state. Takes one of `none`, `reboot`, `reboot-force`, `reboot-immediate`, `poweroff`, `poweroff-force`, `poweroff-immediate`, `exit`, `exit-force`, `soft-reboot`, `soft-reboot-force`, `kexec`, `kexec-force`, `halt`, `halt-force` and `halt-immediate`. In system mode, all options are allowed. In user mode, only `none`, `exit`, and `exit-force` are allowed. Both options default to `none`. These actions are tied to the unit's state transitions and fire only when the unit actually transitions out of an `active` or `activating` state. As a consequence, `Condition…=` and `Assert…=` directives that fail do *not* trigger `SuccessAction=` or `FailureAction=`: they prevent activation in the first place, so no state transition occurs. By contrast, the `ExecCondition=` directive in `systemd.service(5)` runs as part of activation, so an `ExecCondition=` skip *will* trigger `SuccessAction=`. If `none` is set, no action will be triggered. `reboot` causes a reboot following the normal shutdown procedure (i.e. equivalent to `systemctl reboot`). `reboot-force` causes a forced reboot which will terminate all processes forcibly but should cause no dirty file systems on reboot (i.e. equivalent to `systemctl reboot -f`) and `reboot-immediate` causes immediate execution of the `reboot(2)` system call, which might result in data loss (i.e. equivalent to `systemctl reboot -ff`). Similarly, `poweroff`, `poweroff-force`, `poweroff-immediate`, `kexec`, `kexec-force`, `halt`, `halt-force` and `halt-immediate` have the effect of powering down the system, executing kexec, and halting the system respectively with similar semantics. `exit` causes the manager to exit following the normal shutdown procedure, and `exit-force` causes it terminate without shutting down services. When `exit` or `exit-force` is used by default the exit status of the main process of the unit (if this applies) is returned from the service manager. If there is no such status, `FailureAction=` returns 255 instead, while `SuccessAction=` leaves the exit status unchanged. However, this may be overridden with `FailureActionExitStatus=`/`SuccessActionExitStatus=`, see below. `soft-reboot` will trigger a userspace reboot operation. `soft-reboot-force` does that too, but does not go through the shutdown transaction beforehand. `FailureActionExitStatus=`; `SuccessActionExitStatus=` Controls the exit status to propagate back to an invoking container manager (in case of a system service) or service manager (in case of a user manager) when the `FailureAction=`/`SuccessAction=` are set to `exit` or `exit-force` and the action is triggered. By default, the exit status of the main process of the triggering unit (if this applies) is propagated. Takes a value in the range 0…255 or the empty string to request default behaviour. `JobTimeoutSec=`; `JobRunningTimeoutSec=` `JobTimeoutSec=` specifies a timeout for the whole job that starts running when the job is queued. `JobRunningTimeoutSec=` specifies a timeout that starts running when the queued job is actually started. If either limit is reached, the job will be cancelled, the unit however will not change state or even enter the `failed` mode. Both settings take a time span with the default unit of seconds, but other units may be specified, see `systemd.time(7)`. The default is `infinity` (job timeouts disabled), except for device units where `JobRunningTimeoutSec=` defaults to `DefaultDeviceTimeoutSec=`. Note: these timeouts are independent from any unit-specific timeouts (for example, the timeout set with `TimeoutStartSec=` in service units). The job timeout has no effect on the unit itself. Or in other words: unit-specific timeouts are useful to abort unit state changes, and revert them. The job timeout set with this option however is useful to abort only the job waiting for the unit state to change. `JobTimeoutAction=`; `JobTimeoutRebootArgument=` `JobTimeoutAction=` optionally configures an additional action to take when the timeout is hit, see description of `JobTimeoutSec=` and `JobRunningTimeoutSec=` above. It takes the same values as `FailureAction=`/`SuccessAction=`. Defaults to `none`. `JobTimeoutRebootArgument=` configures an optional reboot string to pass to the `reboot(2)` system call. `StartLimitIntervalSec=interval`; `StartLimitBurst=burst` Configure unit start rate limiting. Units which are started more than \ times within an \ time span are not permitted to start any more. Use `StartLimitIntervalSec=` to configure the checking interval and `StartLimitBurst=` to configure how many starts per interval are allowed. \ is a time span with the default unit of seconds, but other units may be specified, see `systemd.time(7)`. The special value `infinity` can be used to limit the total number of start attempts, even if they happen at large time intervals. Defaults to `DefaultStartLimitIntervalSec=` in manager configuration file, and may be set to 0 to disable any kind of rate limiting. \ is a number and defaults to `DefaultStartLimitBurst=` in manager configuration file. These configuration options are particularly useful in conjunction with the service setting `Restart=` (see `systemd.service(5)`); however, they apply to all kinds of starts (including manual), not just those triggered by the `Restart=` logic. Note that units which are configured for `Restart=`, and which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted manually or from a timer or socket at a later point, after the \ has passed. From that point on, the restart logic is activated again. `systemctl reset-failed` will cause the restart rate counter for a service to be flushed, which is useful if the administrator wants to manually start a unit and the start limit interferes with that. Rate-limiting is enforced after any unit condition checks are executed, and hence unit activations with failing conditions do not count towards the rate limit. When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters are flushed out too. This means that configuring start rate limiting for a unit that is not referenced continuously has no effect. This setting does not apply to slice, target, device, and scope units, since they are unit types whose activation may either never fail, or may succeed only a single time. `StartLimitAction=` Configure an additional action to take if the rate limit configured with `StartLimitIntervalSec=` and `StartLimitBurst=` is hit. Takes the same values as the `FailureAction=`/`SuccessAction=` settings. If `none` is set, hitting the rate limit will trigger no action except that the start will not be permitted. Defaults to `none`. `RebootArgument=` Configure the optional argument for the `reboot(2)` system call if `StartLimitAction=` or `FailureAction=` is a reboot action. This works just like the optional argument to `systemctl reboot` command. `SourcePath=` A path to a configuration file this unit has been generated from. This is primarily useful for implementation of generator tools that convert configuration from an external configuration file format into native unit files. This functionality should not be used in normal units. ## Conditions and Asserts Unit files may also include a number of `Condition…=` and `Assert…=` settings. Before the unit is started, systemd will verify that the specified conditions and asserts are true. If not, the starting of the unit will be (mostly silently) skipped (in case of conditions), or aborted with an error message (in case of asserts). Failing conditions or asserts will not result in the unit being moved into the `failed` state. The conditions and asserts are checked at the time the queued start job is to be executed. The ordering dependencies are still respected, so other units are still pulled in and ordered as if this unit was successfully activated, and the conditions and asserts are executed the precise moment the unit would normally start and thus can validate system state after the units ordered before completed initialization. Use condition expressions for skipping units that do not apply to the local system, for example because the kernel or runtime environment does not require their functionality. If multiple conditions are specified, the unit will be executed if all of them apply (i.e. a logical AND is applied). Condition checks can use a pipe symbol (`|`) after the equals sign (`Condition…=|…`), which causes the condition to become a *triggering* condition. If at least one triggering condition is defined for a unit, then the unit will be started if at least one of the triggering conditions of the unit applies and all of the regular (i.e. non-triggering) conditions apply. If you prefix an argument with the pipe symbol and an exclamation mark, the pipe symbol must be passed first, the exclamation second. If any of these options is assigned the empty string, the list of conditions is reset completely, all previous condition settings (of any kind) will have no effect. The `AssertArchitecture=`, `AssertVirtualization=`, … options are similar to conditions but cause the start job to fail (instead of being skipped). The failed check is logged. Units with unmet conditions are considered to be in a clean state and will be garbage collected if they are not referenced. This means that when queried, the condition failure may or may not show up in the state of the unit. Note that neither assertion nor condition expressions result in unit state changes. Also note that both are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit dependencies. The `condition` verb of `systemd-analyze(1)` can be used to test condition and assert expressions. Except for `ConditionPathIsSymbolicLink=`, all path checks follow symlinks. `ConditionArchitecture=` Check whether the system is running on a specific architecture. Takes one of `x86`, `x86-64`, `ppc`, `ppc-le`, `ppc64`, `ppc64-le`, `ia64`, `parisc`, `parisc64`, `s390`, `s390x`, `sparc`, `sparc64`, `mips`, `mips-le`, `mips64`, `mips64-le`, `alpha`, `arm`, `arm-be`, `arm64`, `arm64-be`, `sh`, `sh64`, `m68k`, `tilegx`, `cris`, `arc`, `arc-be`, or `native`. Use `systemd-analyze(1)` for the complete list of known architectures. The architecture is determined from the information returned by `uname(2)` and is thus subject to `personality(2)`. Note that a `Personality=` setting in the same unit file has no effect on this condition. A special architecture name `native` is mapped to the architecture the system manager itself is compiled for. The test may be negated by prepending an exclamation mark. `ConditionFirmware=` Check whether the system's firmware is of a certain type. The following values are possible: - `uefi` matches systems with EFI. - `device-tree` matches systems with a device tree. - `device-tree-compatible(value)` matches systems with a device tree that are compatible with `value`. - `smbios-field(field operator value)` matches systems with a SMBIOS field containing a certain value. \ is the name of the SMBIOS field exposed as `sysfs` attribute file below `/sys/class/dmi/id/`. \ is one of `<`, `<=`, `>=`, `>`, `==`, `<>` for version comparisons, `=` and `!=` for literal string comparisons, or `$=`, `!$=` for shell-style glob comparisons. \ is the expected value of the SMBIOS field value (possibly containing shell style globs in case `$=`/`!$=` is used). `ConditionVirtualization=` Check whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation. Takes either boolean value to check if being executed in any virtualized environment, or one of `vm` and `container` to test against a generic type of virtualization solution, or one of `qemu`, `kvm`, `amazon`, `zvm`, `vmware`, `microsoft`, `oracle`, `powervm`, `xen`, `bochs`, `uml`, `bhyve`, `qnx`, `apple`, `sre`, `openvz`, `lxc`, `lxc-libvirt`, `systemd-nspawn`, `docker`, `podman`, `rkt`, `wsl`, `proot`, `pouch`, `acrn` to test against a specific implementation, or `private-users` to check whether we are running in a user namespace. See `systemd-detect-virt(1)` for a full list of known virtualization technologies and their identifiers. If multiple virtualization technologies are nested, only the innermost is considered. The test may be negated by prepending an exclamation mark. `ConditionHost=` `ConditionHost=` may be used to match against the hostname, machine ID, boot ID or product UUID of the host. This either takes a hostname string (optionally with shell style globs) which is tested against the locally set hostname as returned by `gethostname(2)`, or a 128bit ID or UUID, formatted as string. The latter is compared against machine ID, boot ID and the firmware product UUID if there is any. See `machine-id(5)` for details about the machine ID. The test may be negated by prepending an exclamation mark. `ConditionFraction=` `ConditionFraction=` may be used to enable a unit on a stable, pseudo-random subset of a fleet of machines. It is primarily useful for staged rollouts: the same unit (or drop-in) is distributed to every machine in a fleet, but only the configured fraction of them will actually have it enabled. The decision is derived locally from the machine ID (see `machine-id(5)`), so it requires no central coordination and is stable over time: a given machine always lands on the same side of the threshold. The argument consists of an optional \ followed by a percentage, separated by whitespace, for example `30%` or `myrollout 30%`. The percentage may include up to two decimal places (e.g. `0.5%`). The condition is satisfied on approximately the configured percentage of all machines; `0%` matches no machine and `100%` matches every machine. The optional tag is an arbitrary string (not containing whitespace) that is mixed into the derivation, so that independent rollouts select *independent* subsets of the fleet. Without it, all untagged `ConditionFraction=` checks would select the very same machines (the same machines would always be picked first). Use distinct tags for unrelated rollouts, and a shared tag to deliberately target the same machines across several units. The test may be negated by prepending an exclamation mark, in which case it is satisfied on the complementary fraction of machines (e.g. `!myrollout 30%` matches the other ≈70%). If the machine ID cannot be determined, the condition fails. `ConditionKernelCommandLine=` `ConditionKernelCommandLine=` may be used to check whether a specific kernel command line option is set (or if prefixed with the exclamation mark — unset). The argument must either be a single word, or an assignment (i.e. two words, separated by `=`). In the former case the kernel command line is searched for the word appearing as is, or as left hand side of an assignment. In the latter case, the exact assignment is looked for with right and left hand side matching. This operates on the kernel command line communicated to userspace via `/proc/cmdline`, except when the service manager is invoked as payload of a container manager, in which case the command line of `PID 1` is used instead (i.e. `/proc/1/cmdline`). `ConditionKernelVersion=` `ConditionKernelVersion=` may be used to check whether the kernel version (as reported by `uname -r`) matches a certain expression, or if prefixed with the exclamation mark, does not match. The argument must be a list of (potentially quoted) expressions. Each expression starts with one of `=` or `!=` for string comparisons, `<`, `<=`, `==`, `<>`, `>=`, `>` for version comparisons, or `$=`, `!$=` for a shell-style glob match. If no operator is specified, `$=` is implied. Note that using the kernel version string is an unreliable way to determine which features are supported by a kernel, because of the widespread practice of backporting drivers, features, and fixes from newer upstream kernels into older versions provided by distributions. Hence, this check is inherently unportable and should not be used for units which may be used on different distributions. `ConditionVersion=` `ConditionVersion=` may be used to check whether a software version matches a certain expression, or if prefixed with the exclamation mark, does not match. The first argument is the software whose version has to be checked. Currently `kernel`, `systemd` and `glibc` are supported. If this argument is omitted, `kernel` is implied. The second argument must be a list of (potentially quoted) expressions. Each expression starts with one of `=` or `!=` for string comparisons, `<`, `<=`, `==`, `<>`, `>=`, `>` for version comparisons, or `$=`, `!$=` for a shell-style glob match. If no operator is specified, `$=` is implied. `ConditionCredential=` `ConditionCredential=` may be used to check whether a credential by the specified name was passed into the service manager. See [System and Service Credentials](https://systemd.io/CREDENTIALS) for details about credentials. If used in services for the system service manager this may be used to conditionalize services based on system credentials passed in. If used in services for the per-user service manager this may be used to conditionalize services based on credentials passed into the `unit@.service` service instance belonging to the user. The argument must be a valid credential name. If no such credential was passed into the service manager, the credential stores are searched too, i.e. the same directories that `ImportCredential=` searches (see `systemd.exec(5)`), such as `/etc/credstore/`, `/run/credstore/`, `/usr/lib/credstore/` and their `.encrypted` counterparts for the system service manager, and `$XDG_CONFIG_HOME/credstore/`, `$XDG_RUNTIME_DIR/credstore/`, `$HOME/.local/lib/credstore/` and their `.encrypted` counterparts for the per-user service manager. Hence any credential that `ImportCredential=` would pass to a service also satisfies this condition. For encrypted credentials only their existence is checked, they are not decrypted. Before version 263, only the credentials passed into the service manager were checked. `ConditionEnvironment=` `ConditionEnvironment=` may be used to check whether a specific environment variable is set (or if prefixed with the exclamation mark — unset) in the service manager's environment block. The argument may be a single word, to check if the variable with this name is defined in the environment block, or an assignment (`name=value`), to check if the variable with this exact value is defined. Note that the environment block of the service manager itself is checked, i.e. not any variables defined with `Environment=` or `EnvironmentFile=`, as described above. This is particularly useful when the service manager runs inside a containerized environment or as per-user service manager, in order to check for variables passed in by the enclosing container manager or PAM. `ConditionSecurity=` `ConditionSecurity=` may be used to check whether the given security technology is enabled on the system. Currently, the following values are recognized: | Value | Description | |----|----| | selinux | SELinux MAC | | apparmor | AppArmor MAC | | tomoyo | Tomoyo MAC | | smack | SMACK MAC | | ima | Integrity Measurement Architecture (IMA) | | audit | Linux Audit Framework | | uefi-secureboot | UEFI SecureBoot | | tpm2 | Trusted Platform Module 2.0 (TPM2) (with full UEFI support, including the TCG PC Client Platform Firmware Profile) | | cvm | Confidential virtual machine (SEV/TDX) | | measured-uki | Unified Kernel Image with PCR 11 Measurements, as per `systemd-stub(7)`. | | measured-os | OS PCR measurements enabled. This is typically equivalent to `measured-uki`, however may also be set explicitly via the `systemd.tpm2_measured_os=` kernel command line switch, see `kernel-command-line(7)` for details. The various system services doing boot and runtime measurements are conditioned on this flag. | Recognized security technologies The test may be negated by prepending an exclamation mark. `ConditionCapability=` Check whether the given capability exists in the capability bounding set of the service manager (i.e. this does not check whether capability is actually available in the permitted or effective sets, see `capabilities(7)` for details). Pass a capability name such as `CAP_MKNOD`, possibly prefixed with an exclamation mark to negate the check. `ConditionACPower=` Check whether the system has AC power, or is exclusively battery powered at the time of activation of the unit. This takes a boolean argument. If set to `true`, the condition will hold only if at least one AC connector of the system is connected to a power source, or if no AC connectors are known. Conversely, if set to `false`, the condition will hold only if there is at least one AC connector known and all AC connectors are disconnected from a power source. `ConditionNeedsUpdate=` Takes one of `/var/` or `/etc/` as argument, possibly prefixed with a `!` (to invert the condition). This condition may be used to conditionalize units on whether the specified directory requires an update because `/usr/`'s modification time is newer than the stamp file `.updated` in the specified directory. This is useful to implement offline updates of the vendor operating system resources in `/usr/` that require updating of `/etc/` or `/var/` on the next following boot. Units making use of this condition should order themselves before `systemd-update-done.service(8)`, to make sure they run before the stamp file's modification time gets reset indicating a completed update. If the `systemd.condition_needs_update=` option is specified on the kernel command line (taking a boolean), it will override the result of this condition check, taking precedence over any file modification time checks. If the kernel command line option is used, `systemd-update-done.service` will not have immediate effect on any following `ConditionNeedsUpdate=` checks, until the system is rebooted where the kernel command line option is not specified anymore. Note that to make this scheme effective, the timestamp of `/usr/` should be explicitly updated after its contents are modified. The kernel will automatically update modification timestamp on a directory only when immediate children of a directory are modified; an modification of nested files will not automatically result in mtime of `/usr/` being updated. Also note that if the update method includes a call to execute appropriate post-update steps itself, it should not touch the timestamp of `/usr/`. In a typical distribution packaging scheme, packages will do any required update steps as part of the installation or upgrade, to make package contents immediately usable. `ConditionNeedsUpdate=` should be used with other update mechanisms where such an immediate update does not happen. `ConditionFirstBoot=` Takes a boolean argument. This condition may be used to conditionalize units on whether the system is booting up for the first time. This roughly means that `/etc/` was unpopulated when the system started booting (for details, see "First Boot Semantics" in `machine-id(5)`). First Boot is considered finished (this condition will evaluate as false) after the manager has finished the startup phase. This condition may be used to populate `/etc/` on the first boot after factory reset, or when a new system instance boots up for the first time. Note that the service manager itself will perform setup steps during First Boot: it will initialize `machine-id(5)` and preset all units, enabling or disabling them according to the `systemd.preset(5)` settings. Additional setup may be performed via units with `ConditionFirstBoot=yes`. For robustness, units with `ConditionFirstBoot=yes` should order themselves before `first-boot-complete.target` and pull in this passive target with `Wants=`. This ensures that in a case of an aborted first boot, these units will be re-run during the next system startup. If the `systemd.condition_first_boot=` option is specified on the kernel command line (taking a boolean), it will override the result of this condition check, taking precedence over `/etc/machine-id` existence checks. `ConditionPathExists=` Check for the existence of a path. This applies to any file system object (such as a regular file, directory, device node, FIFO, or socket), not only regular files. Symbolic links are followed, so a broken symbolic link is not considered to exist. If the specified absolute path name does not exist, the condition will fail. If the absolute path name passed to `ConditionPathExists=` is prefixed with an exclamation mark (`!`), the test is negated, and the unit is only started if the path does not exist. `ConditionPathExistsGlob=` `ConditionPathExistsGlob=` is similar to `ConditionPathExists=`, but checks for the existence of at least one file or directory matching the specified globbing pattern. `ConditionPathIsDirectory=` `ConditionPathIsDirectory=` is similar to `ConditionPathExists=` but verifies that a certain path exists and is a directory. `ConditionPathIsSymbolicLink=` `ConditionPathIsSymbolicLink=` is similar to `ConditionPathExists=` but verifies that a certain path exists and is a symbolic link. `ConditionPathIsMountPoint=` `ConditionPathIsMountPoint=` is similar to `ConditionPathExists=` but verifies that a certain path exists and is a mount point. `ConditionPathIsReadWrite=` `ConditionPathIsReadWrite=` is similar to `ConditionPathExists=` but verifies that the underlying file system is readable and writable (i.e. not mounted read-only). `ConditionPathIsEncrypted=` `ConditionPathIsEncrypted=` is similar to `ConditionPathExists=` but verifies that the underlying file system's backing block device is encrypted using dm-crypt/LUKS. Note that this check does not cover ext4 per-directory encryption, and only detects block level encryption. Moreover, if the specified path resides on a file system on top of a loopback block device, only encryption above the loopback device is detected. It is not detected whether the file system backing the loopback block device is encrypted. `ConditionPathIsSocket=` `ConditionPathIsSocket=` is similar to `ConditionPathExists=` but verifies that a certain path exists and is a socket. `ConditionDirectoryNotEmpty=` `ConditionDirectoryNotEmpty=` is similar to `ConditionPathExists=` but verifies that a certain path exists and is a non-empty directory. `ConditionFileNotEmpty=` `ConditionFileNotEmpty=` is similar to `ConditionPathExists=` but verifies that a certain path exists and refers to a regular file with a non-zero size. `ConditionFileIsExecutable=` `ConditionFileIsExecutable=` is similar to `ConditionPathExists=` but verifies that a certain path exists, is a regular file, and marked executable. `ConditionUser=` `ConditionUser=` takes a numeric `UID`, a UNIX user name, or the special value `@system`. This condition may be used to check whether the service manager is running as the given user. The special value `@system` can be used to check if the user id is within the system user range. This option is not useful for system services, as the system manager exclusively runs as the root user, and thus the test result is constant. `ConditionGroup=` `ConditionGroup=` is similar to `ConditionUser=` but verifies that the service manager's real or effective group, or any of its auxiliary groups, match the specified group or GID. This setting does not support the special value `@system`. `ConditionControlGroupController=` Check whether given cgroup controllers (e.g. `cpu`) are available for use on the system or whether the legacy v1 cgroup or the modern v2 cgroup hierarchy is used. Multiple controllers may be passed with a space separating them; in this case, the condition will only pass if all listed controllers are available for use. Controllers unknown to systemd are ignored. Valid controllers are `cpu`, `io`, `memory`, and `pids`. Even if available in the kernel, a particular controller may not be available if it was disabled on the kernel command line with `cgroup_disable=controller`. Alternatively, two special strings `v1` and `v2` may be specified (without any controller names). `v2` will pass if the unified v2 cgroup hierarchy is used, and `v1` will pass if the legacy v1 hierarchy or the hybrid hierarchy are used. Note that legacy or hybrid hierarchies have been deprecated. See `systemd(1)` for more information. `ConditionMemory=` Verify that the specified amount of system memory is available to the current system. Takes a memory size in bytes as argument, optionally prefixed with a comparison operator `<`, `<=`, `=` (or `==`), `!=` (or `<>`), `>=`, `>`. On bare-metal systems compares the amount of physical memory in the system with the specified size, adhering to the specified comparison operator. In containers compares the amount of memory assigned to the container instead. `ConditionCPUs=` Verify that the specified number of CPUs is available to the current system. Takes a number of CPUs as argument, optionally prefixed with a comparison operator `<`, `<=`, `=` (or `==`), `!=` (or `<>`), `>=`, `>`. Compares the number of CPUs in the CPU affinity mask configured of the service manager itself with the specified number, adhering to the specified comparison operator. On physical systems the number of CPUs in the affinity mask of the service manager usually matches the number of physical CPUs, but in special and virtual environments might differ. In particular, in containers the affinity mask usually matches the number of CPUs assigned to the container and not the physically available ones. `ConditionCPUFeature=` On i386 and x86-64, verify that a given CPU feature is available via the `CPUID` instruction. It checks the leaves `1`, `7`, `0x80000001`, and `0x80000007`. Valid values are: `fpu`, `vme`, `de`, `pse`, `tsc`, `msr`, `pae`, `mce`, `cx8`, `apic`, `sep`, `mtrr`, `pge`, `mca`, `cmov`, `pat`, `pse36`, `clflush`, `mmx`, `fxsr`, `sse`, `sse2`, `ht`, `pni`, `pclmul`, `monitor`, `ssse3`, `fma3`, `cx16`, `sse4_1`, `sse4_2`, `movbe`, `popcnt`, `aes`, `xsave`, `osxsave`, `avx`, `f16c`, `rdrand`, `bmi1`, `avx2`, `bmi2`, `rdseed`, `adx`, `sha_ni`, `syscall`, `rdtscp`, `lm`, `lahf_lm`, `abm`, `constant_tsc`. On arm64, valid values are the corresponding arm64 feature names, such as `asimd`, `paca`, `pacg`, `bti`, `mte`, among others. For the full list, see the documentation on [ARM64 ELF hwcaps](https://docs.kernel.org/arch/arm64/elf_hwcaps.html). See `systemd-analyze(1)`'s `cpu-features` command for the complete list of known CPU features for the system. To avoid ambiguities in mixed-architecture fleets, the value can be prefixed with the architecture name using the form `ARCH.FEATURE`. If the architecture prefix does not match the running system, the condition evaluates to false. For example, one can specify `arm64.bti` on arm64 systems to check if `bti` is supported. In this example, `ConditionCPUFeature=arm64.bti` and `ConditionCPUFeature=bti` are functionally equivalent. See `ConditionArchitecture=` for valid architecture names. On architectures other than x86 and arm64, it is assumed that the CPU does not support the given feature. `ConditionOSRelease=` Verify that a specific `key=value` pair is set in the host's `os-release(5)`. Other than exact string matching (with `=` and `!=`), relative comparisons are supported for versioned parameters (e.g. `VERSION_ID`; with `<`, `<=`, `==`, `<>`, `>=`, `>`), and shell-style wildcard comparisons (`*`, `?`, `[]`) are supported with the `$=` (match) and `!$=` (non-match). If the given key is not found in the file, the match is done against an empty value. `ConditionMachineTag=` `ConditionMachineTag=` may be used to match against the tags assigned to the local machine. Machine tags are short labels that classify and group machines for management purposes; they are configured in the `TAGS=` field of `machine-info(5)` and may be queried and changed with the `tags` command of `hostnamectl(1)`. The argument is a single tag pattern, which is compared against each of the configured tags using shell-style globbing (`*`, `?`, `[]`). The condition is satisfied if at least one of the configured tags matches the pattern. The test may be negated by prepending an exclamation mark, in which case it is satisfied if none of the configured tags matches. Tags may be parameterized with a value in the form `key=value`; the `=` and the value are part of the tag and thus part of the string the pattern is matched against. Hence `ConditionMachineTag=company.role=webserver` matches the tag `company.role=webserver` exactly, `ConditionMachineTag=company.role=*` matches any value assigned to the `company.role` key, and `ConditionMachineTag=company.role` (without `=`) does *not* match `company.role=webserver`. See `machine-info(5)` for the precise syntax of machine tags. `ConditionMemoryPressure=`; `ConditionCPUPressure=`; `ConditionIOPressure=` Verify that the overall system (memory, CPU or IO) pressure is below or equal to a threshold. This setting takes a threshold value as argument. It can be specified as a simple percentage value, suffixed with `%`, in which case the pressure will be measured as an average over the last five minutes before the attempt to start the unit is performed. Alternatively, the average timespan can also be specified using `/` as a separator, for example: `10%/1min`. The supported timespans match what the kernel provides, and are limited to `10sec`, `1min` and `5min`. The `full` PSI will be checked first, and if not found `some` will be checked. For more details, see the documentation on [PSI (Pressure Stall Information) ](https://docs.kernel.org/accounting/psi.html). Optionally, the threshold value can be prefixed with the slice unit under which the pressure will be checked, followed by a `:`. If the slice unit is not specified, the overall system pressure will be measured, instead of a particular cgroup's. `ConditionKernelModuleLoaded=` Test whether the specified kernel module has been loaded and is already fully initialized. `AssertArchitecture=`; `AssertVirtualization=`; `AssertHost=`; `AssertFraction=`; `AssertKernelCommandLine=`; `AssertKernelVersion=`; `AssertVersion=`; `AssertCredential=`; `AssertEnvironment=`; `AssertSecurity=`; `AssertCapability=`; `AssertACPower=`; `AssertNeedsUpdate=`; `AssertFirstBoot=`; `AssertPathExists=`; `AssertPathExistsGlob=`; `AssertPathIsDirectory=`; `AssertPathIsSymbolicLink=`; `AssertPathIsMountPoint=`; `AssertPathIsReadWrite=`; `AssertPathIsEncrypted=`; `AssertPathIsSocket=`; `AssertDirectoryNotEmpty=`; `AssertFileNotEmpty=`; `AssertFileIsExecutable=`; `AssertUser=`; `AssertGroup=`; `AssertControlGroupController=`; `AssertMemory=`; `AssertCPUs=`; `AssertCPUFeature=`; `AssertOSRelease=`; `AssertMachineTag=`; `AssertMemoryPressure=`; `AssertCPUPressure=`; `AssertIOPressure=`; `AssertKernelModuleLoaded=` Similar to the `ConditionArchitecture=`, `ConditionVirtualization=`, …, condition settings described above, these settings add assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a configured assertion does not cause the unit to enter the `failed` state (or in fact result in any state change of the unit), it affects only the job queued for it. Use assertion expressions for units that cannot operate when specific requirements are not met, and when this is something the administrator or user should look into. # Mapping of unit properties to their inverses Unit settings that create a relationship with a second unit usually show up in properties of both units, for example in `systemctl show` output. In some cases the name of the property is the same as the name of the configuration setting, but not always. This table lists the properties that are shown on two units which are connected through some dependency, and shows which property on "source" unit corresponds to which property on the "target" unit.
"Forward" and "reverse" unit properties
"Forward" property "Reverse" property Where used
Before= After= [Unit] section
After= Before=
Requires= RequiredBy= [Unit] section [Install] section
Wants= WantedBy= [Unit] section [Install] section
Upholds= UpheldBy= [Unit] section [Install] section
PartOf= ConsistsOf= [Unit] section an automatic property
BindsTo= BoundBy= [Unit] section an automatic property
Requisite= RequisiteOf= [Unit] section an automatic property
Conflicts= ConflictedBy= [Unit] section an automatic property
Triggers= TriggeredBy= Automatic properties, see notes below
PropagatesReloadTo= ReloadPropagatedFrom= [Unit] section
ReloadPropagatedFrom= PropagatesReloadTo=
PropagatesStopTo= StopPropagatedFrom= [Unit] section
StopPropagatedFrom= PropagatesStopTo=
Following= n/a An automatic property
Note: `WantedBy=`, `RequiredBy=`, and `UpheldBy=` are used in the \[Install\] section to create symlinks in `.wants/`, `.requires/`, and `.upholds/` directories. They cannot be used directly as a unit configuration setting. Note: `ConsistsOf=`, `BoundBy=`, `RequisiteOf=`, `ConflictedBy=` are created implicitly along with their reverses and cannot be specified directly. Note: `Triggers=` is created implicitly between a socket, path unit, or an automount unit, and the unit they activate. By default, a unit with the same name is triggered, but this can be overridden using `Sockets=`, `Service=`, and `Unit=` settings. See `systemd.service(5)`, `systemd.socket(5)`, `systemd.path(5)`, and `systemd.automount(5)` for details. `TriggeredBy=` is created implicitly on the triggered unit. Note: `Following=` is used to group device aliases and points to the "primary" device unit that systemd is using to track device state, usually corresponding to a sysfs path. It does not show up in the "target" unit. # \[Install\] Section Options Unit files may include an \[Install\] section, which carries installation information for the unit. This section is not interpreted by `systemd(1)` during runtime; it is used by the `enable` and `disable` commands of the `systemctl(1)` tool during installation of a unit. `Alias=` A space-separated list of additional names this unit shall be installed under. The names listed here must have the same suffix (i.e. type) as the unit filename. This option may be specified more than once, in which case all listed names are used. At installation time, `systemctl enable` will create symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support aliasing. `WantedBy=`; `RequiredBy=`; `UpheldBy=` This option may be used more than once, or a space-separated list of unit names may be given. A symbolic link is created in the `.wants/`, `.requires/`, or `.upholds/` directory of each of the listed units when this unit is installed by `systemctl enable`. This has the effect of a dependency of type `Wants=`, `Requires=`, or `Upholds=` being added from the listed unit to the current unit. See the description of the mentioned dependency types in the \[Unit\] section for details. In case of template units listing non template units, the listing unit must have `DefaultInstance=` set, or `systemctl enable` must be called with an instance name. The instance (default or specified) will be added to the `.wants/`, `.requires/`, or `.upholds/` list of the listed unit. For example, `WantedBy=getty.target` in a service `getty@.service` will result in `systemctl enable getty@tty2.service` creating a `getty.target.wants/getty@tty2.service` link to `getty@.service`. This also applies to listing specific instances of templated units: this specific instance will gain the dependency. A template unit may also list a template unit, in which case a generic dependency will be added where each instance of the listing unit will have a dependency on an instance of the listed template with the same instance value. For example, `WantedBy=container@.target` in a service `monitor@.service` will result in `systemctl enable monitor@.service` creating a `container@.target.wants/monitor@.service` link to `monitor@.service`, which applies to all instances of `container@.target`. `Also=` Additional units to install/deinstall when this unit is installed/deinstalled. If the user requests installation/deinstallation of a unit with this option configured, `systemctl enable` and `systemctl disable` will automatically install/uninstall units listed in this option as well. This option may be used more than once, or a space-separated list of unit names may be given. `DefaultInstance=` In template unit files, this specifies for which instance the unit shall be enabled if the template is enabled without any explicitly set instance. This option has no effect in non-template unit files. The specified string must be usable as instance identifier. The following specifiers are interpreted in the Install section: %a, %b, %B, %g, %G, %H, %i, %j, %l, %m, %n, %N, %o, %p, %u, %U, %v, %w, %W, %%. For their meaning see the next section. # Specifiers Many settings resolve specifiers which may be used to write generic unit files referring to runtime or unit parameters that are replaced when the unit files are loaded. Specifiers must be known and resolvable for the setting to be valid. The following specifiers are understood: | Specifier | Meaning | Details | |----|----|----| | `%a` | Architecture | A short string identifying the architecture of the local system. A string such as `x86`, `x86-64` or `arm64`. See the architectures defined for `ConditionArchitecture=` above for a full list. | | `%C` | Cache directory root | This is either `/var/cache` (for the system manager) or the path `$XDG_CACHE_HOME` resolves to (for user managers). | | `%d` | Credentials directory | This is the value of the `$CREDENTIALS_DIRECTORY` environment variable if available. See section "Credentials" in `systemd.exec(5)` for more information. | | `%E` | Configuration directory root | This is either `/etc/` (for the system manager) or the path `$XDG_CONFIG_HOME` resolves to (for user managers). | | `%f` | Unescaped filename | This is either the unescaped instance name (if applicable) with `/` prepended (if applicable), or the unescaped prefix name prepended with `/`. This implements unescaping according to the rules for escaping absolute file system paths discussed above. | | `%g` | User group | This is the name of the group running the service manager instance. In case of the system manager this resolves to `root`. | | `%G` | User GID | This is the numeric GID of the user running the service manager instance. In case of the system manager this resolves to `0`. | | `%h` | User home directory | This is the home directory of the *user running the service manager instance*. In case of the system manager this resolves to `/root`. Note that this setting is *not* influenced by the `User=` setting configurable in the \[Service\] section of the service unit. | | `%H` | Host name | The hostname of the running system at the point in time the unit configuration is loaded. | | `%i` | Instance name | For instantiated units this is the string between the first `@` character and the type suffix. Empty for non-instantiated units. | | `%I` | Unescaped instance name | Same as `%i`, but with escaping undone. | | `%j` | Final component of the prefix | This is the string between the last `-` and the end of the prefix name. If there is no `-`, this is the same as `%p`. | | `%J` | Unescaped final component of the prefix | Same as `%j`, but with escaping undone. | | `%l` | Short host name | The hostname of the running system at the point in time the unit configuration is loaded, truncated at the first dot to remove any domain component. | | `%L` | Log directory root | This is either `/var/log` (for the system manager) or the path `$XDG_STATE_HOME` resolves to with `/log` appended (for user managers). | | `%n` | Full unit name | | | `%N` | Full unit name | Same as `%n`, but with the type suffix removed. | | `%p` | Prefix name | For instantiated units, this refers to the string before the first `@` character of the unit name. For non-instantiated units, same as `%N`. | | `%P` | Unescaped prefix name | Same as `%p`, but with escaping undone. | | `%q` | Pretty host name | The pretty hostname of the running system at the point in time the unit configuration is loaded, as read from the `PRETTY_HOSTNAME=` field of `/etc/machine-info`. If not set, resolves to the short hostname. See `machine-info(5)` for more information. | | `%s` | User shell | This is the shell of the user running the service manager instance. | | `%S` | State directory root | This is either `/var/lib` (for the system manager) or the path `$XDG_STATE_HOME` resolves to (for user managers). | | `%t` | Runtime directory root | This is either `/run/` (for the system manager) or the path `$XDG_RUNTIME_DIR` resolves to (for user managers). | | `%u` | User name | This is the name of the *user running the service manager instance*. In case of the system manager this resolves to `root`. Note that this setting is *not* influenced by the `User=` setting configurable in the \[Service\] section of the service unit. | | `%U` | User UID | This is the numeric UID of the *user running the service manager instance*. In case of the system manager this resolves to `0`. Note that this setting is *not* influenced by the `User=` setting configurable in the \[Service\] section of the service unit. | | `%y` | The path to the fragment | This is the path where the main part of the unit file is located. For linked unit files, the real path outside of the unit search directories is used. For units that do not have a fragment file, this specifier will raise an error. | | `%Y` | The directory of the fragment | This is the directory part of `%y`. | Specifiers available in unit files {.specifiers} # Examples
Allowing units to be enabled
The following snippet (highlighted) allows a unit (e.g. `foo.service`) to be enabled via `systemctl enable`: [Unit] Description=Foo [Service] ExecStart=/usr/sbin/foo-daemon [Install] WantedBy=multi-user.target After running `systemctl enable`, a symlink `/etc/systemd/system/multi-user.target.wants/foo.service` linking to the actual unit will be created. It tells systemd to pull in the unit when starting `multi-user.target`. The inverse `systemctl disable` will remove that symlink again.
Overriding vendor settings
There are two methods of overriding vendor settings in unit files: copying the unit file from `/usr/lib/systemd/system` to `/etc/systemd/system` and modifying the chosen settings. Alternatively, one can create a directory named `unit.d/` within `/etc/systemd/system` and place a drop-in file `name.conf` there that only changes the specific settings one is interested in. Note that multiple such drop-in files are read if present, processed in lexicographic order of their filename. The advantage of the first method is that one easily overrides the complete unit, the vendor unit is not parsed at all anymore. It has the disadvantage that improvements to the unit file by the vendor are not automatically incorporated on updates. The advantage of the second method is that one only overrides the settings one specifically wants, where updates to the unit by the vendor automatically apply. This has the disadvantage that some future updates by the vendor might be incompatible with the local changes. This also applies for user instances of systemd, but with different locations for the unit files. See the section on unit load paths for further details. Suppose there is a vendor-supplied unit `/usr/lib/systemd/system/httpd.service` with the following contents: [Unit] Description=Some HTTP Server After=remote-fs.target sqldb.service Requires=sqldb.service AssertPathExists=/srv/webserver [Service] Type=notify ExecStart=/usr/sbin/some-fancy-httpd-server Nice=5 [Install] WantedBy=multi-user.target Now one wants to change some settings as an administrator: firstly, in the local setup, `/srv/webserver` might not exist, because the HTTP server is configured to use `/srv/www` instead. Secondly, the local configuration makes the HTTP server also depend on a memory cache service, `memcached.service`, that should be pulled in (`Requires=`) and also be ordered appropriately (`After=`). Thirdly, in order to harden the service a bit more, the administrator would like to set the `PrivateTmp=` setting (see `systemd.exec(5)` for details). And lastly, the administrator would like to reset the niceness of the service to its default value of 0. The first possibility is to copy the unit file to `/etc/systemd/system/httpd.service` and change the chosen settings: [Unit] Description=Some HTTP Server After=remote-fs.target sqldb.service memcached.service Requires=sqldb.service memcached.service AssertPathExists=/srv/www [Service] Type=notify ExecStart=/usr/sbin/some-fancy-httpd-server Nice=0 PrivateTmp=yes [Install] WantedBy=multi-user.target Alternatively, the administrator could create a drop-in file `/etc/systemd/system/httpd.service.d/local.conf` with the following contents: [Unit] After=memcached.service Requires=memcached.service # Reset all assertions and then re-add the condition we want AssertPathExists= AssertPathExists=/srv/www [Service] Nice=0 PrivateTmp=yes Note that for drop-in files, if one wants to remove entries from a setting that is parsed as a list (and is not a dependency), such as `AssertPathExists=` (or e.g. `ExecStart=` in service units), one needs to first clear the list before re-adding all entries except the one that is to be removed. Dependencies (`After=`, etc.) cannot be reset to an empty list, so dependencies can only be added in drop-ins. If you want to remove dependencies, you have to override the entire unit.
Top level drop-ins with template units
Top level per-type drop-ins can be used to change some aspect of all units of a particular type. For example, by creating the `/etc/systemd/system/service.d/` directory with a drop-in file, the contents of the drop-in file can be applied to all service units. We can take this further by having the top-level drop-in instantiate a secondary helper unit. Consider for example the following set of units and drop-in files where we install an `OnFailure=` dependency for all service units. `/etc/systemd/system/failure-handler@.service`: [Unit] Description=My Failure Handler For %i [Service] Type=oneshot # Perform some special action for when %i exits unexpectedly. ExecStart=/usr/sbin/myfailurehandler %i We can then add an instance of `failure-handler@.service` as an `OnFailure=` dependency for all service units. `/etc/systemd/system/service.d/10-all.conf`: [Unit] OnFailure=failure-handler@%N.service Now, after running `systemctl daemon-reload` all services will have acquired an `OnFailure=` dependency on `failure-handler@%N.service`. The template instance units will also have gained the dependency which results in the creation of a recursive dependency chain. systemd will try to detect these recursive dependency chains where a template unit directly and recursively depends on itself and will remove such dependencies automatically if it finds them. If systemd does not detect the recursive dependency chain, we can break the chain ourselves by disabling the drop-in for the template instance units via a symlink to `/dev/null`: mkdir /etc/systemd/system/failure-handler@.service.d/ ln -s /dev/null /etc/systemd/system/failure-handler@.service.d/10-all.conf systemctl daemon-reload This ensures that if a `failure-handler@.service` instance fails it will not trigger an instance named `failure-handler@failure-handler.service`.
# See Also `systemd(1)`, `systemctl(1)`, `systemd-system.conf(5)`, `systemd.special(7)`, `systemd.service(5)`, `systemd.socket(5)`, `systemd.device(5)`, `systemd.mount(5)`, `systemd.automount(5)`, `systemd.swap(5)`, `systemd.target(5)`, `systemd.path(5)`, `systemd.timer(5)`, `systemd.scope(5)`, `systemd.slice(5)`, `systemd.time(7)`, `systemd-analyze(1)`, `capabilities(7)`, `systemd.directives(7)`, `uname(1)` # systemd.v systemd systemd.v 7 systemd.v Directory with Versioned Resources # Description In various places systemd components accept paths whose trailing components have the `.v/` suffix, pointing to a directory. These components will then automatically look for suitable files inside the directory, do a version comparison and open the newest file found (by version). Available since version v256. Specifically, two expressions are supported: - When looking for files with a suffix \<.SUFFIX\>, and a path `…PATH/NAME.SUFFIX.v/` is specified, then all files `…PATH/NAME.SUFFIX.v/NAME_*.SUFFIX` are enumerated, filtered, sorted and the newest file used. The primary sorting key is the *variable part*, here indicated by the wildcard `*`. - When a path `…PATH.v/NAME___.SUFFIX` is specified (i.e. the penultimate component of the path ends in `.v` and the final component contains a triple underscore), then all files `…PATH.v/NAME_*.SUFFIX` are enumerated, filtered, sorted and the newest file used (again, by the *variable part*, here indicated by the wildcard `*`). To illustrate this in an example, consider a directory `/var/lib/machines/mymachine.raw.v/`, which is populated with three files: - `mymachine_7.5.13.raw` - `mymachine_7.5.14.raw` - `mymachine_7.6.0.raw` Invoke a tool such as `systemd-nspawn(1)` with a command line like the following: # systemd-nspawn --image=/var/lib/machines/mymachine.raw.v --boot Then this would automatically be resolved to the equivalent of: # systemd-nspawn --image=/var/lib/machines/mymachine.raw.v/mymachine_7.6.0.raw --boot Much of systemd's functionality that expects a path to a disk image or OS directory hierarchy support the `.v/` versioned directory mechanism, for example `systemd-nspawn(1)`, `systemd-dissect(1)` or the `RootDirectory=`/`RootImage=` settings of service files (see `systemd.exec(5)`). Use the `systemd-vpick(1)` tool to resolve `.v/` paths from the command line, for example for usage in shell scripts. # Filtering and Sorting The variable part of the filenames in the `.v/` directories are filtered and compared primarily with a version comparison, implementing [UAPI.10 Version Format Specification](https://uapi-group.org/specifications/specs/version_format_specification/). However, additional rules apply: - If the variable part is suffixed by one or two integer values ("tries left" and "tries done") in the formats `+LEFT` or `+LEFT-DONE`, then these indicate usage attempt counters. The idea is that each time before a file is attempted to be used, its "tries left" counter is decreased, and the "tries done" counter increased (simply by renaming the file). When the file is successfully used (which for example could mean for an OS image: successfully booted) the counters are removed from the file name, indicating that the file has been validated to work correctly. This mechanism mirrors the boot assessment counters defined by [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/). Any filenames with no boot counters or with a non-zero "tries left" counter are sorted before filenames with a zero "tries left" counter. - Preceding the use counters (if they are specified), an optional CPU architecture identifier may be specified in the filename (separated from the version with an underscore), as defined in the architecture vocabulary of the `ConditionArchitecture=` unit file setting, as documented in `systemd.unit(5)`. Files whose name indicates an architecture not supported locally are filtered and not considered for the version comparison. - The rest of the variable part is the version string. Or in other words, the files in the `.v/` directories should follow one of these naming structures: - `NAME_VERSION.SUFFIX` - `NAME_VERSION_ARCHITECTURE.SUFFIX` - `NAME_VERSION+LEFT.SUFFIX` - `NAME_VERSION+LEFT-DONE.SUFFIX` - `NAME_VERSION_ARCHITECTURE+LEFT.SUFFIX` - `NAME_VERSION_ARCHITECTURE+LEFT-DONE.SUFFIX` # Example Here's a more comprehensive example, further extending the one described above. Consider a directory `/var/lib/machines/mymachine.raw.v/`, which is populated with the following files: - `mymachine_7.5.13.raw` - `mymachine_7.5.14_x86-64.raw` - `mymachine_7.6.0_arm64.raw` - `mymachine_7.7.0_x86-64+0-5.raw` Now invoke the following command on an x86-64 machine: $ systemd-vpick --suffix=.raw /var/lib/machines/mymachine.raw.v/ This would resolve the specified path to `/var/lib/machines/mymachine.raw.v/mymachine_7.5.14_x86-64.raw`. Explanation: even though `mymachine_7.7.0_x86-64+0-5.raw` has the newest version, it is not preferred because its tries left counter is zero. And even though `mymachine_7.6.0_arm64.raw` has the second newest version it is also not considered in this case, because we operate on an x86_64 system and the image is intended for arm64 CPUs. Finally, the `mymachine_7.5.13.raw` image is not considered because it is older than `mymachine_7.5.14_x86-64.raw`. # See Also `systemd(1)`, `systemd-vpick(1)`, `systemd-nspawn(1)`, `systemd-dissect(1)`, `systemd.exec(5)`, `systemd-sysupdate(8)` # sysupdate.components systemd sysupdate.components 5 sysupdate.components Definition Files for Update Components `/etc/sysupdate.component.component`, `/run/sysupdate.component.component`, `/usr/local/lib/sysupdate.component.component`, `/usr/lib/sysupdate.component.component` # Description A "Component" is a set of `sysupdate.d(5)` transfer definitions that `systemd-sysupdate(8)` updates independently from the rest of the OS. Each component is a self-contained installation with its own version, and its own set of transfer files, stored in a directory named after the component: `sysupdate.component.d/*.transfer` (as opposed to the default, component-less `sysupdate.d/*.transfer`). Components are selected via the `--component=`, `--component-all` or `--component-suggested` switches of `systemd-sysupdate(8)`, and enumerated by its `components` command. Because components are updated separately, they are the right tool for OS resources that shall be versioned and updated independently from the base OS — for example a container image or a portable service image that follows its own release cycle. This is the primary difference between a component and an `sysupdate.features(5)` Optional Feature: the transfers belonging to a feature are updated in lock-step with the target they are part of, while a component is a wholly separate installation. Do not use a component for resources that shall always be updated synchronously with something else; use a feature (or simply additional transfer files in the same directory) for those cases. Besides being defined in the file system, components may also be provided dynamically by *component providers*, i.e. services implementing a Varlink interface, see below. Components defined in the file system always take precedence over those offered by providers. A component does not require a `*.component` file: as soon as a matching `sysupdate.component.d/` directory with transfer definitions exists, the component is available for updating. The `*.component` file described here is optional, and carries metadata about the component (such as a human-readable description and a documentation URL) as well as its enablement state. When a component is disabled (via `Enabled=false`, see below), operations that would download or install new versions — most importantly `update` — refuse to act on it. Other operations, such as `vacuum` and `cleanup`, continue to consider the component's transfers so that previously installed instances remain managed and can be cleaned up. Components are enabled or disabled with the `enable-component` and `disable-component` commands of `systemd-sysupdate(8)`, which write an `Enabled=` setting into a drop-in next to the component definition. Component definitions support drop-in files, which are most commonly used to override the `Enabled=` setting. Drop-ins are read from `sysupdate.component.component.d/*.conf` in the same set of directories as the main file. They can also be masked to hide the component definition entirely. Each `*.component` file contains one section: \[Component\]. # \[Component\] Section Options This section defines general properties of this component. `Description=` A short human-readable description of this component. This may be used as a label for this component, so the string should meaningfully identify the component among the components available on the system. `Documentation=` One or more user-presentable URLs to documentation about this component. This setting may be specified more than once. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect. It supports specifier expansion; see below for details on supported specifiers. `Enabled=` Whether or not this component is enabled. If unspecified, the component is enabled by default. When disabled, `systemd-sysupdate` refuses to download or install new versions of this component, but continues to consider its transfers while vacuuming and in other situations where it needs to determine ownership over previously downloaded system resources. `SuccessAction=` Controls what to do after an update of this component has been installed successfully, when multiple components are updated in one go (i.e. when `systemd-sysupdate update` is invoked with `--component-all`). Takes one of `continue` or `restart`. If `continue`, the update logic proceeds with the next component. If `restart`, the remaining components are skipped and the current update iteration is finished early, so that the next iteration starts from the beginning, re-reading all definition files. This is useful for components that make new transfer files (or components) available, which should be processed before any other components are updated. Note that the next iteration is only started if the `--loop=` switch permits it, see `systemd-sysupdate(8)` for details. Defaults to `continue`. `FailureAction=` Controls what to do if updating this component failed, when multiple components are updated in one go (i.e. when `systemd-sysupdate update` is invoked with `--component-all`). Takes one of `continue` or `fail`. If `continue`, the failure is logged, and the update logic proceeds with the next component (and possibly further update iterations, see `--loop=`), but the tool returns the first error encountered once it is done. If `fail`, the remaining components are skipped and the tool fails immediately. Defaults to `continue`. `MinVersion=`; `MaxVersion=` Specifies the minimum resp. maximum version to permit for all transfers of this component, with the same semantics as the settings of the same name in the \[Transfer\] section of `sysupdate.d(5)`: versions older than `MinVersion=` are considered obsolete, versions newer than `MaxVersion=` are considered too new, and neither are selected for updating. If a transfer of the component specifies its own bounds, the more restrictive one applies. Both settings support specifier expansion. `ProtectVersion=` Takes one or more version strings to mark as "protected" for all transfers of this component, with the same semantics as the setting of the same name in the \[Transfer\] section of `sysupdate.d(5)`: protected versions are never removed while making room for new versions. Versions listed here are added to those a transfer protects on its own. This setting supports specifier expansion. `Suggest=` Takes a boolean argument. If true, this component is suggested for enablement, if false it is not. This does not enable the component on its own, but is a hint surfaced by the update tools (for example via the `--component-suggested` switch of `systemd-sysupdate(8)`) so that the system administrator or higher-level tooling may act on it. If this setting is not specified, the `SuggestOn…=` conditions described below are evaluated instead to determine whether the component is suggested. If neither this setting nor any `SuggestOn…=` condition is specified, the component is not suggested. `SuggestOnArchitecture=`; `SuggestOnFirmware=`; `SuggestOnVirtualization=`; `SuggestOnHost=`; `SuggestOnFraction=`; `SuggestOnKernelCommandLine=`; `SuggestOnVersion=`; `SuggestOnCredential=`; `SuggestOnSecurity=`; `SuggestOnOSRelease=`; `SuggestOnMachineTag=` Suggest this component for enablement depending on system properties. These settings take the same arguments and implement the same semantics — including the leading `!` for negation — as the identically-named `ConditionArchitecture=`, `ConditionFirmware=`, `ConditionVirtualization=`, `ConditionHost=`, `ConditionFraction=`, `ConditionKernelCommandLine=`, `ConditionVersion=`, `ConditionCredential=`, `ConditionSecurity=`, `ConditionOSRelease=` and `ConditionMachineTag=` settings for unit files, which are documented in `systemd.unit(5)`. The component is suggested if all specified conditions apply. As with the `Condition…=` settings, assigning an empty string to one of these resets the list. These conditions are only evaluated if `Suggest=` is not specified. # Specifiers Specifiers may be used in the `Documentation=`, `MinVersion=`, `MaxVersion=` and `ProtectVersion=` settings. The following expansions are understood: | Specifier | Meaning | Details | |-----------|---------|---------| Specifiers available {.specifiers} # Examples
A Separately Updated Container Image
We'll use the hypothetical "foobarOS" described in `sysupdate.d(5)` as our example base OS. foobarOS ships a container image that many, but not all, deployments want to run. The image has its own release cadence and version number, entirely separate from the base OS, so it is a poor fit for an Optional Feature (which would be version-locked to the OS). Instead, let's model it as a component named `webapp`. First, the component definition, carrying its metadata and marking it as disabled by default: # /usr/lib/sysupdate.webapp.component [Component] Description=WebApp Container Image Documentation=https://docs.example.com/foobarOS/webapp Enabled=false Next, the transfer definition for the component, placed in the component's own directory `sysupdate.webapp.d/`: # /usr/lib/sysupdate.webapp.d/50-webapp.transfer [Source] Type=url-file Path=https://download.example.com/ MatchPattern=webapp_@v.raw.xz [Target] Type=regular-file Path=/var/lib/machines MatchPattern=webapp_@v.raw Mode=0444 InstancesMax=2 With these two files, updates for the `webapp` component can be checked and downloaded independently of the base OS, for example with `systemd-sysupdate --component=webapp update`. Because `Enabled=false` was set, the administrator must first opt in with `systemd-sysupdate enable-component webapp`, which writes the following drop-in: # /etc/sysupdate.webapp.component.d/50-systemd-sysupdate-enabled.conf # Generated via 'systemd-sysupdate enable-component' [Component] Enabled=true
A Component Suggested Only on Bare Metal
Suppose foobarOS ships a component with firmware and microcode updates that is only relevant when running on physical hardware, not inside a virtual machine. We can use `SuggestOn…=` to hint that the component should be enabled in that case, without enabling it automatically: # /usr/lib/sysupdate.firmware.component [Component] Description=Firmware and Microcode Updates Documentation=https://docs.example.com/foobarOS/firmware Enabled=false SuggestOnVirtualization=!vm Higher-level tooling can now query the suggested components (via `systemd-sysupdate --component-suggested …`) and enable them as appropriate. On bare metal the `firmware` component is suggested; inside a VM it is not.
# Component Providers In addition to the component definitions found in the file system, `systemd-sysupdate(8)` acquires component definitions from *component providers*: services that bind an `AF_UNIX` stream socket into the `/run/systemd/sysupdate/provider/` directory (directly or via a symlink) and implement the `io.systemd.SysUpdate.Provider` [Varlink](https://varlink.org/) interface on it. It is recommended to name the socket after the service implementing it, in reverse domain name notation. A provider may define additional components, each carrying the same kind of information as the component definition files described above, and the feature and transfer definition files described in `sysupdate.features(5)` and `sysupdate.d(5)`. Note that, unlike in the configuration files, no specifier expansion is applied to strings returned by a provider, and the `SuggestOn…=` conditions are not available. Providers are only consulted while operating on the host (i.e. when none of `--root=`, `--image=`, or `--definitions=` are used). Providers may run unprivileged: whoever is able to place a socket in the directory is trusted. The set of components `systemd-sysupdate` operates on is the union of the components defined in the file system and those defined by providers. Components defined in the file system take precedence: if the file system defines a component — i.e. a `sysupdate.component.component` file, or any feature or transfer definition file in `sysupdate.component.d/` exists — a provider's definition of a component by the same name is ignored. If multiple providers define the same component, the definition of the provider whose socket name sorts first is used, and a message is logged. The default component (i.e. `sysupdate.d/`) is always taken from the file system. Instead of pointing its transfers to resources on a web server, a provider may also serve these resources itself. In that case, it must implement the generic `io.systemd.ResourceProvider` Varlink interface (typically on the same socket), and use URLs of the form `provider:[/run/systemd/sysupdate/provider/name]/resource` in the `Path=` field of the sources of its transfers, see `sysupdate.d(5)` for details. Since the definitions of provider-backed components do not live in the file system, the `enable-component`, `disable-component`, `enable-feature` and `disable-feature` commands of `systemd-sysupdate` refuse to operate on them; it is up to the provider to expose the enablement state it deems appropriate. If a provider that is present cannot be queried successfully (for example because it fails or times out), `systemd-sysupdate` treats the components it might define as being of unknown state rather than as removed, so that the `cleanup` command does not remove resources belonging to them. # See Also `systemd(1)`, `systemd-sysupdate(8)`, `sysupdate.d(5)`, `sysupdate.features(5)` # sysupdate.d systemd sysupdate.d 5 sysupdate.d Transfer Definition Files for Automatic Updates `/etc/sysupdate.d/*.transfer`, `/run/sysupdate.d/*.transfer`, `/usr/local/lib/sysupdate.d/*.transfer`, `/usr/lib/sysupdate.d/*.transfer` # Description These files describe how specific resources on the local system shall be updated from a remote source. Each such file defines one such transfer: typically a remote HTTP/HTTPS resource as source; and a local file, directory or partition as target. This may be used as a simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system extension images — but in fact may be used to update any kind of file from a remote source. The `systemd-sysupdate(8)` command reads these files and uses them to determine which local resources should be updated, and then executes the update. Transfer definitions for components may also be acquired dynamically from component providers, see `sysupdate.components(5)`. Both the remote HTTP/HTTPS source and the local target typically exist in multiple, concurrent versions, in order to implement flexible update schemes, e.g. A/B updating (or a superset thereof, e.g. A/B/C, A/B/C/D, …). Each `*.transfer` file defines one transfer, i.e. describes one resource to update. Typically, multiple of these files (i.e. multiple of such transfers) are defined together, and are bound together by a common version identifier in order to update multiple resources at once on each update operation, for example to update a kernel, a root file system and a Verity partition in a single, combined, synchronized operation, so that only a combined update of all three together constitutes a complete update. We'll call such a collection of transfers a target. `systemd-sysupdate(8)` always operates on a single target. Transfers may be grouped together into sets that can be individually enabled or disabled by the system administrator, called "Optional Features": `sysupdate.features(5)`. Each `*.transfer` file contains three sections: \[Transfer\], \[Source\] and \[Target\]. # Basic Mode of Operation Disk-image based OS updates typically consist of multiple different resources that need to be updated together, for example a secure OS update might consist of a root file system image to drop into a partition, a matching Verity integrity data partition image, and a kernel image prepared to boot into the combination of the two partitions. The first two resources are files that are downloaded and placed in a disk partition, the latter is a file that is downloaded and placed in a regular file in the boot file system (e.g. EFI system partition). Hence, during an update of a hypothetical operating system "foobarOS" to a hypothetical version 47 the following operations should take place: 1. A file `https://download.example.com/foobarOS_47.root.xz` should be downloaded, decompressed and written to a previously unused partition with GPT partition type UUID 4f68bce3-e8cd-4db1-96e7-fbcaf984b709 for x86-64, as per [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). 2. Similarly, a file `https://download.example.com/foobarOS_47.verity.xz` should be downloaded, decompressed and written to a previously empty partition with GPT partition type UUID of 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5 (i.e. the partition type for Verity integrity information for x86-64 root file systems). 3. Finally, a file `https://download.example.com/foobarOS_47.efi` (a unified kernel, as per [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#2) should be downloaded, decompressed and written to the \$BOOT file system, i.e. to `EFI/Linux/foobarOS_47.efi` in the ESP or XBOOTLDR partition. The version-independent generalization of this would be (using the special marker `@v` as wildcard for the version identifier): 1. A transfer of a file `https://download.example.com/foobarOS_@v.root.xz` → a local, previously empty GPT partition of type 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, with the label to be set to `foobarOS_@v`. 2. A transfer of a file `https://download.example.com/foobarOS_@v.verity.xz` → a local, previously empty GPT partition of type 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5, with the label to be set to `foobarOS_@v_verity`. 3. A transfer of a file `https://download.example.com/foobarOS_@v.efi` → a local file `$BOOT/EFI/Linux/foobarOS_@v.efi`. An update can only complete if the relevant URLs provide their resources for the same version, i.e. for the same value of `@v`. The above may be translated into three `*.transfer` files in `sysupdate.d/`, one for each resource to transfer. The `*.transfer` files configure the type of download, and what place to write the download to (i.e. whether to a partition or a file in the file system). Most importantly these files contain the URL, partition name and filename patterns shown above that describe how these resources are called on the source and how they shall be called on the target. In order to enumerate available versions and figuring out candidates to update to, a mechanism is necessary to list suitable files: - For partitions: the surrounding GPT partition table contains a list of defined partitions, including a partition type UUID and a partition label (in this scheme the partition label plays a role for the partition similar to the filename for a regular file). - For regular files: the directory listing of the directory the files are contained in provides a list of existing files in a straightforward way. - For HTTP/HTTPS sources a simple scheme is used: a manifest file `SHA256SUMS`, following the format defined by `sha256sum(1)`, lists file names and their SHA256 hashes. Transfers are done in the alphabetical order of the `.transfer` file names they are defined in. First, the resource data is downloaded directly into a target file/directory/partition. Once this is completed for all defined transfers, in a second step the files/directories/partitions are renamed to their final names as defined by the target `MatchPattern=`, again in the order the `.transfer` transfer file names dictate. This step is not atomic, however it is guaranteed to be executed strictly in order with suitable disk synchronization in place. Typically, when updating an OS one of the transfers defines the entry point when booting. Thus it is generally a good idea to order the resources via the transfer configuration file names so that the entry point is written last, ensuring that any abnormal termination does not leave an entry point around whose backing is not established yet. In the example above it would hence make sense to establish the EFI kernel image last and thus give its transfer configuration file the alphabetically last name. See below for an extended, more specific example based on the above. # Resource Types Each transfer file defines one source resource to transfer to one target resource. The following resource types are supported: 1. Resources of type `url-file` encapsulate a file on a web server, referenced via a HTTP or HTTPS URL, or a resource offered by a local resource provider service, referenced via a `provider:` URL (see `Path=` below). When an update takes place, the file is downloaded and decompressed and then written to the target file or partition. This resource type is only available for sources, not for targets. The list of available versions of resources of this type is encoded in `SHA256SUMS` manifest files, accompanied by `SHA256SUMS.gpg` detached signatures. 2. The `url-tar` resource type is similar, but the file must be a `.tar` archive. When an update takes place, the file is decompressed and unpacked into a directory or btrfs subvolume. This resource type is only available for sources, not for targets. Just like `url-file`, `url-tar` version enumeration makes use of `SHA256SUMS` files, authenticated via `SHA256SUMS.gpg`. 3. The `regular-file` resource type encapsulates a local regular file on disk. During updates the file is uncompressed and written to the target file or partition. This resource type is available both as source and as target. When updating no integrity or authentication verification is done for resources of this type. 4. The `partition` resource type is similar to `regular-file`, and encapsulates a GPT partition on disk. When updating, the partition must exist already, and have the correct GPT partition type. A partition whose GPT partition label is set to `_empty` is considered empty, and a candidate to place a newly downloaded resource in. The GPT partition label is used to store version information, once a partition is updated. This resource type is only available for target resources. 5. The `tar` resource type encapsulates local `.tar` archive files. When an update takes place, the files are uncompressed and unpacked into a target directory or btrfs subvolume. Behaviour of `tar` and `url-tar` is generally similar, but the latter downloads from remote sources, and does integrity and authentication checks while the former does not. The `tar` resource type is only available for source resources. 6. The `directory` resource type encapsulates local directory trees. This type is available both for source and target resources. If an update takes place on a source resource of this type, a recursive copy of the directory is done. 7. The `subvolume` resource type is identical to `directory`, except when used as the target, in which case the file tree is placed in a btrfs subvolume instead of a plain directory, if the backing file system supports it (i.e. is btrfs). As already indicated, only a subset of source and target resource type combinations are supported: | Identifier | Description | |----------------|----------------------------| | `url-file` | HTTP/HTTPS files | | `url-tar` | HTTP/HTTPS `.tar` archives | | `regular-file` | Local files | | `partition` | Local GPT partitions | | `tar` | Local `.tar` archives | | `directory` | Local directories | | `subvolume` | Local btrfs subvolumes | Resource Types The `SHA256SUMS` manifest files used by `url-file` and `url-tar` resource types follow the usual file format generated by GNU's `sha256sum(1)` tool. It is recommended to use `--binary` mode, even if that has no real effect on Linux systems. The listing should only contain ASCII characters. Entries are usually plain file names, but may also be relative subpaths (e.g., `foo_1/bar.efi`). Absolute paths, non-normalized paths containing `./`, `../`, or `//` components, and entries containing a `%` character are rejected. If the `SHA256SUMS` listing contains a special file `BEST-BEFORE-YYYY-MM-DD` (with the year, month, day filled in), then the file listing will not be considered valid past the specified date, and the transfer will fail in such a case. This may be used to detect "freshness" of the manifest file. # Match Patterns Both the source and target resources typically exist in multiple versions concurrently. An update operation is done whenever the newest of the source versions is newer than the newest of the target versions. To determine the newest version of the resources a directory listing, partition listing or manifest listing is used, a subset of qualifying entries selected from that, and the version identifier extracted from the file names or partition labels of these selected entries. Subset selection and extraction of the version identifier (plus potentially other metadata) is done via match patterns, configured in `MatchPattern=` in the \[Source\] and \[Target\] sections. These patterns are strings that describe how files or partitions are named, with named wildcards for specific fields such as the version identifier. The following wildcards are defined: | Wildcard | Description | |----------|-----------------------------------| | `@v` | Version identifier | | `@u` | GPT partition UUID | | `@f` | GPT partition flags | | `@a` | GPT partition flag NoAuto | | `@g` | GPT partition flag GrowFileSystem | | `@r` | Read-only flag | | `@t` | File modification time | | `@m` | File access mode | | `@s` | File size after decompression | | `@d` | Tries done | | `@l` | Tries left | | `@h` | SHA256 hash of compressed file | Match Pattern Wildcards Of these wildcards only `@v` must be present in a valid pattern, all other wildcards are optional. Each wildcard may be used at most once in each pattern. A typical wildcard matching a file system source image could be `MatchPattern=foobar_@v.raw.xz`, i.e. any file whose name begins with `foobar_`, followed by a version ID and suffixed by `.raw.xz`. A source `MatchPattern=` may additionally be prefixed with `**/`. It can not contain `**/` anywhere else nor further subdirectories in the rest of the pattern. This prefix matches any number of nested subdirectories or none, meaning only the basenames get matched against the rest of the pattern. The `**/` prefix is not a wildcard like those in the table above because it captures nothing and can't be used in a target `MatchPattern=`. It's also not supported for the source types `directory` and `subvolume`. Do not confuse the `@` pattern matching wildcard prefix with the `%` specifier expansion prefix. The former encapsulate a variable part of a match pattern string, the latter are simple shortcuts that are expanded while the drop-in files are parsed. For details about specifiers, see below. # \[Transfer\] Section Options This section defines general properties of this transfer. `MinVersion=` Specifies the minimum version to require for this transfer to take place. If the source or target patterns in this transfer definition match files older than this version they will be considered obsolete, and never be considered for the update operation. `MaxVersion=` Specifies the maximum version to permit for this transfer. If the source or target patterns in this transfer definition match files newer than this version they will be considered too new, and never be selected as candidate for the update operation, nor may they be selected explicitly. They are otherwise treated like any other version, i.e. remain subject to vacuuming and cleanup. This is useful to pin an installation to a specific version series. Note that instances newer than this version that are already installed are not removed. `ProtectVersion=` Takes one or more version strings to mark as "protected". Protected versions are never removed while making room for new, updated versions. This is useful to ensure that the currently booted OS version (or auxiliary resources associated with it) is not replaced/overwritten during updates, in order to avoid runtime file system corruptions. Like many of the settings in these configuration files this setting supports specifier expansion. It's particularly useful to set this setting to one of the `%A`, `%B` or `%w` specifiers to automatically refer to the current OS version of the running system. See below for details on supported specifiers. `Verify=` Takes a boolean, defaults to yes. Controls whether to cryptographically verify downloaded resources (specifically: validate the GPG signatures for downloaded `SHA256SUMS` manifest files, via their detached signature files `SHA256SUMS.gpg` in combination with the system keyring consisting of `/usr/lib/systemd/import-pubring.pgp` and the local keyring in `/etc/systemd/import-pubring.pgp` (or, if that does not exist, `/etc/systemd/import-pubring.gpg`). This option is essential to provide integrity guarantees for downloaded resources and thus should be left enabled, outside of test environments. Note that the downloaded payload files are unconditionally checked against the SHA256 hashes listed in the manifest. This option only controls whether the signatures of these manifests are verified. This option only has an effect if the source resource type is selected as `url-file` or `url-tar`, as integrity and authentication checking is only available for transfers from remote sources. `ChangeLog=` Optionally takes a human-presentable URL to a website containing a change-log of the resource being updated. This may be set multiple times in a single transfer definition. If set multiple times, the values are gathered into a list of URLs. Adding a value of the empty string will clear the existing list of all values. This setting supports specifier expansion. See below for details on supported specifiers. This setting will also expand the `@v` wildcard pattern. See above for details. `AppStream=` Optionally takes a URL to an [AppStream catalog](https://www.freedesktop.org/software/appstream/docs/chap-CatalogData.html) XML file. This may be used by software centers (such as GNOME Software or KDE Discover) to present rich metadata about the resources being updated. This includes display names, changelogs, icons, and more. The specified catalog must include [special metadata](https://systemd.io/APPSTREAM_BUNDLE) to be correctly associated with `systemd-sysupdate(8)` by the software centers. This setting supports specifier expansion. See below for details on supported specifiers. `Features=` A space-separated list of `sysupdate.features(5)` that this transfer belongs to, by name. This option may be specified more than once, in which case the specified list of features is merged. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect. For example: `Features=foo bar` specifies that the transfer belongs to `foo.feature` and `bar.feature`. If the list of features is empty, then this transfer is always used. If this transfer belongs to more than one feature, then it will be used if *any* one of the listed features is enabled. A name that does not correspond to a defined feature will resolve to an implicit feature that is always disabled. `RequisiteFeatures=` This is like `Features=`, except that *all* features listed here must be enabled for this transfer to be enabled. If both options are specified, then they both apply: the transfer will be enabled only if all features specified here are enabled, and at least one feature listed in `Features=` is enabled. # \[Source\] Section Options This section defines properties of the transfer source. `Type=` Specifies the resource type of the source for the transfer. Takes one of `url-file`, `url-tar`, `tar`, `regular-file`, `directory` or `subvolume`. For details about the resource types, see above. This option is mandatory. Note that only certain combinations of source and target resource types are supported, see above. `Path=` Specifies where to find source versions of this resource. If the source type is selected as `url-file` or `url-tar` this must be a HTTP/HTTPS URL. The URL is suffixed with `/SHA256SUMS` to acquire the manifest file, with `/SHA256SUMS.gpg` to acquire the detached signature file for it, and with the file names listed in the manifest file in case an update is executed and a resource shall be downloaded. Alternatively, for these two source types a URL of the form `provider:[socket]/resource` may be specified, which refers to a resource offered by a local service implementing the `io.systemd.ResourceProvider` Varlink interface on the `AF_UNIX` socket \ (an absolute path). The \ part is an opaque name the service understands, which may contain slashes, but no `.` or `..` components. Such URLs are suffixed and otherwise treated exactly like HTTP/HTTPS URLs: `/SHA256SUMS`, `/SHA256SUMS.gpg` and the file names from the manifest are appended to the \ part and requested from the service via that interface. Verification hence works the same way as for HTTP/HTTPS sources; in particular `Verify=yes` requires the service to offer the signature file too. This is primarily useful in combination with component providers, see `sysupdate.components(5)`. For all other source resource types this must be a local path in the file system, referring to a local directory to find the versions of this resource in. `MatchPattern=` Specifies one or more file name match patterns that select the subset of files that are update candidates as source for this transfer. See above for details on match patterns. This option is mandatory. Any pattern listed must contain at least the `@v` wildcard, so that a version identifier may be extracted from the filename. All other wildcards are optional. The pattern may contain slash characters. In this case, it will match the file or directory in the corresponding subdirectory. For example `MatchPattern=foo_@v/bar.efi` will match `bar.efi` in directory `foo_1`. For `url-file` and `url-tar` sources, the corresponding `SHA256SUMS` manifest may then list entries as subpaths such as `foo_1/bar.efi`; such entries are fetched from the matching subpath of the source URL. Manifest entries that are absolute, non-normalized (containing `./`, `../`, or `//` components), or that contain a `%` character are rejected. A `**/` prefix on a source `MatchPattern=` matches any number of subdirectories and will as a result only match the basename against the rest of the pattern. For `url-file` and `url-tar` sources, `SHA256SUMS` entries may then list the file under any subpath and the subpath is still used to construct the actual download URL. The pattern after `**/` must not contain further slashes. The prefix is not accepted on target patterns or for the source `Type=directory` and `Type=subvolume`. # \[Target\] Section Options This section defines properties of the transfer target. `Type=` Specifies the resource type of the target for the transfer. Takes one of `partition`, `regular-file`, `directory` or `subvolume`. For details about the resource types, see above. This option is mandatory. Note that only certain combinations of source and target resource types are supported, see above. `Path=` Specifies a file system path where to look for already installed versions or place newly downloaded versions of this configured resource. If `Type=` is set to `partition`, expects a path to a (whole) block device node, or the special string `auto` in which case the block device which contains the root file system of the currently booted system is automatically determined and used. If `Type=` is set to `regular-file`, `directory` or `subvolume`, must refer to a path in the local file system referencing the directory to find or place the version files or directories under. Note that this mechanism cannot be used to create or remove partitions, in case `Type=` is set to `partition`. Partitions must exist already, and a special partition label `_empty` is used to indicate empty partitions. To automatically generate suitable partitions on first boot, use a tool such as `systemd-repart(8)`. `PathRelativeTo=` Specifies what anchor point `Path=` should be relative to. Takes one of `root`, `esp`, `xbootldr`, `boot` or `explicit`. If unspecified, defaults to `root`. If set to `root`, `esp`, `xbootldr`, the specified `Path=` will be resolved relative to the mount point of the corresponding partition, as defined by the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification). If set to `boot`, the specified `Path=` will be resolved relative to the mount point of the \$BOOT partition (i.e. the ESP or XBOOTLDR), as defined by the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification). If set to `explicit`, the specified `Path=` will be resolved relative to the directory specified with `--transfer-source=` when invoking `systemd-sysupdate(8)`. The values `esp`, `xbootldr`, and `boot` are only supported when `Type=` is set to `regular-file` or `directory`. `MatchPattern=` Specifies one or more file name or partition label match patterns that select the subset of files or partitions that are update candidates as targets for this transfer. See above for details on match patterns. This option is mandatory. Any pattern listed must contain at least the `@v` wildcard, so that a version identifier may be extracted from the filename. All other wildcards are optional. This pattern is both used for matching existing installed versions and for determining the name of new versions to install. If multiple patterns are specified, the first specified is used for naming newly installed versions. If the target type is `regular-file` or `directory`, the pattern may contain slash characters. In this case, it will match the file or directory in corresponding subdirectory. For example `MatchPattern=foo_@v/bar.efi` will match `bar.efi` in directory `foo_1`. Directories in the path will be created when file is installed. Empty directories will be removed when file is removed. File and directory targets are a good fit for `.v/` directories, which allow consumers to automatically pick the newest installed version, see `systemd.v(7)`. These expect a much stricter naming scheme than what `MatchPattern=` permits: the entries of a directory `NAME.SUFFIX.v/` should be named `NAME_VERSION.SUFFIX`, optionally with the boot assessment counters appended to the version. Hence, the recommended pattern for such a target is `NAME_@v.SUFFIX` (or `NAME_@v+@l-@d.SUFFIX` if boot assessment counters shall be used). For example, for `Path=/var/lib/machines/foobar.raw.v`, use `MatchPattern=foobar_@v.raw`, and for a `directory` target with `Path=/var/lib/machines/foobar.v`, use `MatchPattern=foobar_@v`. `MatchPartitionType=` When the target `Type=` is chosen as `partition`, specifies the GPT partition type to look for. Only partitions of this type are considered, all other partitions are ignored. If not specified, the GPT partition type `linux-generic` is used. Accepts either a literal type UUID or a symbolic type identifier. For a list of supported type identifiers, see the `Type=` setting in `repart.d(5)`. `PartitionUUID=`; `PartitionFlags=`; `PartitionNoAuto=`; `PartitionGrowFileSystem=` When the target `Type=` is picked as `partition`, selects the GPT partition UUID and partition flags to use for the updated partition. Expects a valid UUID string, a hexadecimal integer, or booleans, respectively. If not set, but the source match pattern includes wildcards for these fields (i.e. `@u`, `@f`, `@a`, or `@g`), the values from the patterns are used. If neither configured with wildcards or these explicit settings, the values are left untouched. If both the overall `PartitionFlags=` flags setting and the individual flag settings `PartitionNoAuto=` and `PartitionGrowFileSystem=` are used (or the wildcards for them), then the latter override the former, i.e. the individual flag bit overrides the overall flags value. See [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification) for details about these flags. Note that these settings are not used for matching, they only have effect on newly written partitions in case a transfer takes place. `PartitionZeroFill=` Takes a boolean. When the target `Type=` is picked as `partition`, controls whether the remainder of the partition is overwritten with zeroes after the payload has been written into it. If disabled, only as much of the partition is written as the payload is large, and whatever data was previously stored in the rest of the partition remains in place. If enabled, everything from the end of the payload up to the end of the partition is zeroed out, so that no remnants of an earlier, larger payload survive. On block devices this is offloaded to the kernel and hence the storage device where possible. If not specified, defaults to on for Verity signature partitions (i.e. if `MatchPartitionType=` selects one of the `*-verity-sig` types) and off for all other partition types. Verity signature partitions carry a JSON object that must be followed by zero bytes only, up to the end of the partition, while the artifacts installed into them (for example as generated via the `--split=` mode of `systemd-repart(8)`) generally do not carry this padding. `ReadOnly=` Controls whether to mark the resulting file, subvolume or partition read-only. If the target type is `partition` this controls the ReadOnly partition flag, as per [UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification), similar to the `PartitionNoAuto=` and `PartitionGrowFileSystem=` flags described above. If the target type is `regular-file`, the writable bit is removed from the access mode. If the target type is `subvolume`, the subvolume will be marked read-only as a whole. Finally, if the target `Type=` is selected as `directory`, the "immutable" file attribute is set, see `chattr(1)` for details. `Mode=` The UNIX file access mode to use for newly created files in case the target resource type is picked as `regular-file`. Expects an octal integer, in typical UNIX fashion. If not set, but the source match pattern includes a wildcard for this field (i.e. `@t`), the value from the pattern is used. Note that this setting is not used for matching, it only has an effect on newly written files when a transfer takes place. `TriesDone=`; `TriesLeft=` These options take positive, decimal integers, and control the number of attempts done and left for this file. These settings are useful for managing kernel images, following the scheme defined in [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT), and only have an effect if the target pattern includes the `@d` or `@l` wildcards. `InstancesMax=` Takes a decimal integer equal to or greater than 2. This configures how many concurrent versions of the resource to keep. Whenever a new update is initiated it is made sure that no more than the number of versions specified here minus one exist in the target. Any excess versions are deleted (in case the target `Type=` of `regular-file`, `directory`, `subvolume` is used) or emptied (in case the target `Type=` of `partition` is used; emptying in this case simply means to set the partition label to the special string `_empty`; note that no partitions are actually removed). After an update is completed the number of concurrent versions of the target resources is equal to or below the number specified here. Note that this setting may be set differently for each transfer. However, it generally is advisable to keep this setting the same for all transfers, since otherwise incomplete combinations of files or partitions will be left installed. If the target `Type=` is selected as `partition`, the number of concurrent versions to keep is additionally restricted by the number of partition slots of the right type in the partition table. I.e. if there are only 2 partition slots for the selected partition type, setting this value larger than 2 is without effect, since no more than 2 concurrent versions could be stored in the image anyway. `RemoveTemporary=` Takes a boolean argument. If this option is enabled (which is the default) before initiating an update, all left-over, incomplete updates from a previous attempt are removed from the target directory. This only has an effect if the target resource `Type=` is selected as `regular-file`, `directory` or `subvolume`. `CurrentSymlink=` Takes a symlink name as argument. If this option is used, as the last step of the update a symlink under the specified name is created/updated pointing to the completed update. This is useful in to provide a stable name always pointing to the newest version of the resource. This is only supported if the target resource `Type=` is selected as `regular-file`, `directory` or `subvolume`. # Specifiers Specifiers may be used in the `MinVersion=`, `MaxVersion=`, `ProtectVersion=`, `Path=`, `MatchPattern=` and `CurrentSymlink=` settings. The following expansions are understood: | Specifier | Meaning | Details | |-----------|---------|---------| Specifiers available {.specifiers} Do not confuse the `%` specifier expansion prefix with the `@` pattern matching wildcard prefix. The former are simple shortcuts that are expanded while the drop-in files are parsed, the latter encapsulate a variable part of a match pattern string. For details about pattern matching wildcards, see above. # Examples
Updates for a Verity Enabled Secure OS
With the following three files we define a root file system partition, a matching Verity partition, and a unified kernel image to update as one. This example is an extension of the example discussed earlier in this man page. # /usr/lib/sysupdate.d/50-verity.transfer [Transfer] ProtectVersion=%A [Source] Type=url-file Path=https://download.example.com/ MatchPattern=foobarOS_@v_@u.verity.xz [Target] Type=partition Path=auto MatchPattern=foobarOS_@v_verity MatchPartitionType=root-verity PartitionFlags=0 ReadOnly=1 The above defines the update mechanism for the Verity partition of the root file system. Verity partition images are downloaded from `https://download.example.com/foobarOS_@v_@u.verity.xz` and written to a suitable local partition, which is marked read-only. Under the assumption this update is run from the image itself the current image version (i.e. the `%A` specifier) is marked as protected, to ensure it is not corrupted while booted. Note that the partition UUID for the target partition is encoded in the source file name. Fixating the partition UUID can be useful to ensure that `roothash=` on the kernel command line is sufficient to pinpoint both the Verity and root file system partition, and also encode the Verity root level hash (under the assumption the UUID in the file names match their top-level hash, the way `systemd-gpt-auto-generator(8)` suggests). # /usr/lib/sysupdate.d/60-root.transfer [Transfer] ProtectVersion=%A [Source] Type=url-file Path=https://download.example.com/ MatchPattern=foobarOS_@v_@u.root.xz [Target] Type=partition Path=auto MatchPattern=foobarOS_@v MatchPartitionType=root PartitionFlags=0 ReadOnly=1 The above defines a matching transfer definition for the root file system. # /usr/lib/sysupdate.d/70-kernel.transfer [Transfer] ProtectVersion=%A [Source] Type=url-file Path=https://download.example.com/ MatchPattern=foobarOS_@v.efi [Target] Type=regular-file Path=/EFI/Linux PathRelativeTo=boot MatchPattern=foobarOS_@v+@l-@d.efi \ foobarOS_@v+@l.efi \ foobarOS_@v.efi Mode=0644 TriesLeft=3 TriesDone=0 InstancesMax=2 The above installs a unified kernel image into the \$BOOT partition, as per [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification) Type \#2. This defines three possible patterns for the names of the kernel images, as per [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT), and ensures when installing new kernels, they are set up with 3 tries left. No more than two parallel kernels are kept. With this setup the web server would serve the following files, for a hypothetical version 7 of the OS: - `SHA256SUMS` – The manifest file, containing available files and their SHA256 hashes - `SHA256SUMS.gpg` – The detached cryptographic signature for the manifest file - `foobarOS_7_8b8186b1-2b4e-4eb6-ad39-8d4d18d2a8fb.verity.xz` – The Verity image for version 7 - `foobarOS_7_f4d1234f-3ebf-47c4-b31d-4052982f9a2f.root.xz` – The root file system image for version 7 - `foobarOS_7.efi` – The unified kernel image for version 7 For each new OS release a new set of the latter three files would be added, each time with an updated version. The `SHA256SUMS` manifest should then be updated accordingly, listing all files for all versions that shall be offered for download.
Updates for Plain Directory Container Image
[Source] Type=url-tar Path=https://download.example.com/ MatchPattern=myContainer_@v.tar.gz [Target] Type=subvolume Path=/var/lib/machines MatchPattern=myContainer_@v CurrentSymlink=myContainer On updates this downloads `https://download.example.com/myContainer_@v.tar.gz` and decompresses/unpacks it to `/var/lib/machines/myContainer_@v`. After each update a symlink `/var/lib/machines/myContainer` is created/updated always pointing to the most recent update.
# See Also `systemd(1)`, `systemd-sysupdate(8)`, `sysupdate.features(5)`, `sysupdate.components(5)`, `systemd-repart(8)` # sysupdate.features systemd sysupdate.features 5 sysupdate.features Definition Files for Optional Features `/etc/sysupdate.d/*.feature`, `/run/sysupdate.d/*.feature`, `/usr/local/lib/sysupdate.d/*.feature`, `/usr/lib/sysupdate.d/*.feature` # Description "Optional Features" are functionality provided by `systemd-sysupdate(8)`, that allow a distribution to define sets of `sysupdate.d(5)` transfer definitions that are intended to be enabled or disabled by the system administrator. When a feature is enabled, transfers belonging to it will be considered when checking for and downloading updates, when vacuuming, and in all other situations. In effect, transfers belonging to a feature will always be updated in lock-step with the rest of their target. This is the primary difference an Optional Feature and a `systemd-sysupdate(8)` component. When a feature is disabled, its transfers will not be considered when checking for and downloading updates, but `systemd-sysupdate` will still consider them while vacuuming and in other situations where it needs to determine ownership over previously downloaded system resources. `systemd-sysupdate` will clean up all instances of the feature's transfers whenever it is disabled, effectively uninstalling it. Optional Features are described by `sysupdate.d/*.feature` files, which are defined below. For components acquired from component providers (see `sysupdate.components(5)`) the equivalent information is part of the component definition returned by the provider. Transfers can declare that they belong to a feature via the `Features=` setting. Feature definitions support drop-in files, which are most commonly used to override the `Enabled=` setting. They can also be masked to hide the availability of the feature entirely. Each `*.feature` file contains one section: \[Feature\]. # \[Feature\] Section Options This section defines general properties of this feature. `Description=` A short human-readable description of this feature. This may be used as a label for this feature, so the string should meaningfully identify the feature among the features available in `sysupdate.d/`. `Documentation=` One or more user-presentable URLs to documentation about this feature. This setting may be specified more than once. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect. It supports specifier expansion; see below for details on supported specifiers. Support for specifying this setting more than once was added in version 262. `AppStream=` A URL to an [AppStream catalog](https://www.freedesktop.org/software/appstream/docs/chap-CatalogData.html) XML file. This may be used by software centers (such as GNOME Software or KDE Discover) to present rich metadata about this feature. This includes display names, changelogs, icons, and more. This setting supports specifier expansion; see below for details on supported specifiers. `Enabled=` Whether or not this feature is enabled. If unspecified, the feature is disabled by default. `Suggest=` Takes a boolean argument. If true, this feature is suggested for enablement, if false it is not. This does not enable the feature on its own, but is a hint surfaced by the update tools (for example via the `--feature-suggested` switch of `systemd-sysupdate(8)`) so that the system administrator or higher-level tooling may act on it. If this setting is not specified, the `SuggestOn…=` conditions described below are evaluated instead to determine whether the feature is suggested. If neither this setting nor any `SuggestOn…=` condition is specified, the feature is not suggested. `SuggestOnArchitecture=`; `SuggestOnFirmware=`; `SuggestOnVirtualization=`; `SuggestOnHost=`; `SuggestOnFraction=`; `SuggestOnKernelCommandLine=`; `SuggestOnVersion=`; `SuggestOnCredential=`; `SuggestOnSecurity=`; `SuggestOnOSRelease=`; `SuggestOnMachineTag=` Suggest this feature for enablement depending on system properties. These settings take the same arguments and implement the same semantics — including the leading `!` for negation — as the identically-named `ConditionArchitecture=`, `ConditionFirmware=`, `ConditionVirtualization=`, `ConditionHost=`, `ConditionFraction=`, `ConditionKernelCommandLine=`, `ConditionVersion=`, `ConditionCredential=`, `ConditionSecurity=`, `ConditionOSRelease=` and `ConditionMachineTag=` settings for unit files, which are documented in `systemd.unit(5)`. The feature is suggested if all specified conditions apply. As with the `Condition…=` settings, assigning an empty string to one of these resets the list. These conditions are only evaluated if `Suggest=` is not specified. # Specifiers Specifiers may be used in the `Documentation=` and `AppStream=` settings. The following expansions are understood: | Specifier | Meaning | Details | |-----------|---------|---------| Specifiers available {.specifiers} # Examples
Development Tools for Image-Based OS
We'll use the hypothetical "foobarOS" described in `sysupdate.d(5)` as our example base OS. The vast majority of foobarOS's users have no need for a compiler, build system, debugger, and other such development tools to be part of their OS. However, the developers of foobarOS itself need this build tooling to be available. So, foobarOS needs to provide a system extension image (see `systemd-sysext(8)`) containing these development tools, and this image must be updated in lock-step with the underlying base OS. This is a great use case for an optional OS feature, so let's define one: # /usr/lib/sysupdate.d/devel.feature [Feature] Description=Development Tools Documentation=https://developer.example.com/foobarOS/getting-started Enabled=false The above defines the `devel` feature, and disables it by default. Now let's define a transfer that's associated with this feature: # /usr/lib/sysupdate.d/50-devel.transfer [Transfer] Features=devel ProtectVersion=%A [Source] Type=url-file Path=https://download.example.com/ MatchPattern=foobarOS_@v_devel.raw.xz [Target] Type=regular-file Path=/var/lib/extensions MatchPattern=foobarOS_@v_devel.raw Mode=0444 InstancesMax=2 With these two files, we have created a feature called `devel` that, when enabled, will download and decompress the appropriate version of `https://download.example.com/foobarOS_@v_devel.raw.xz` into `/var/lib/extensions/foobarOS_@v_devel.raw` during each OS update. The developers of foobarOS can enable the `devel` feature on their workstations by creating the following drop-in: # /etc/sysupdate.d/devel.feature.d/enable.conf [Feature] Enabled=true
Proprietary Drivers
Suppose that many of foobarOS's users have a GPU manufactured by the MVISUAL corporation. Due to lack of documentation and difficulty in reverse-engineering the hardware, the open-source drivers for MVISUAL GPUs are unable to make proper use of available graphics and compute performance. MVISUAL provides a redistributable proprietary driver for their cards, and foobarOS's developers distribute them to address their users' needs. MVISUAL's driver has a couple different parts that must be installed for it to function: a UKI addon to configure the kernel command-line, an initrd system extension image to add the MVISUAL kernel module into the initrd, and a regular system extension image to add the proprietary OpenGL and Vulkan userspace drivers. All of these should be version-locked to the core OS. Let's start by defining an optional feature named `mvisual-driver`: # /usr/lib/sysupdate.d/mvisual-driver.feature [Feature] Description=MVISUAL Proprietary GPU Driver Documentation=https://support.example.com/foobarOS/mvisual AppStream=https://metadata.example.com/mvisual-driver-%A.xml.gz Note that we define AppStream metadata for this feature, because we want software centers to present it to end-users. Next, let's define the corresponding transfers: # /usr/lib/sysupdate.d/50-mvisual-userspace.transfer [Transfer] Features=mvisual-driver ProtectVersion=%A [Source] Type=url-file Path=https://download.example.com/ MatchPattern=foobarOS_@v_mvisual_userspace.raw.xz [Target] Type=regular-file Path=/var/lib/extensions MatchPattern=foobarOS_@v_mvisual.raw Mode=0444 InstancesMax=2 # /usr/lib/sysupdate.d/70-mvisual-initrd.transfer [Transfer] Features=mvisual-driver ProtectVersion=%A [Source] Type=url-file Path=https://download.example.com/ MatchPattern=foobarOS_@v_mvisual_initrd.raw.xz [Target] Type=regular-file Path=/EFI/Linux PathRelativeTo=boot MatchPattern=foobarOS_@v.efi.extra.d/foobarOS_mvisual.raw Mode=0444 InstancesMax=2 # /usr/lib/sysupdate.d/90-mvisual-addon.transfer [Transfer] Features=mvisual-driver ProtectVersion=%A [Source] Type=url-file Path=https://download.example.com/ MatchPattern=foobarOS_@v_mvisual_addon.efi.xz [Target] Type=regular-file Path=/EFI/Linux PathRelativeTo=boot MatchPattern=foobarOS_@v.efi.extra.d/foobarOS_mvisual.addon.efi Mode=0444 InstancesMax=2
Intersecting Features
Suppose that MVISUAL releases special tooling to help a distribution developer troubleshoot crashes in their proprietary driver. Let's define a transfer: # /usr/lib/sysupdate.d/50-mvisual-debugger.transfer [Transfer] RequisiteFeatures=devel mvisual-driver ProtectVersion=%A [Source] Type=url-file Path=https://download.example.com/ MatchPattern=foobarOS_@v_devel.raw.xz [Target] Type=regular-file Path=/var/lib/extensions MatchPattern=foobarOS_@v_devel.raw Mode=0444 InstancesMax=2 This transfer will be used only if both the `devel` and `mvisual-driver` features are enabled.
# See Also `systemd(1)`, `systemd-sysupdate(8)`, `sysupdate.d(5)`, `sysupdate.components(5)` # sysusers.d systemd sysusers.d 5 sysusers.d Declarative allocation of system users and groups `/etc/sysusers.d/*.conf`, `/run/sysusers.d/*.conf`, `/usr/local/lib/sysusers.d/*.conf`, `/usr/lib/sysusers.d/*.conf` #Type Name ID GECOS Home directory Shell u user_name uid "User Description" /home/dir /path/to/shell u user_name uid:gid "User Description" /home/dir /path/to/shell u user_name /file/owned/by/user "User Description" /home/dir /path/to/shell g group_name gid g group_name /file/owned/by/group m user_name group_name r - lowest-highest # Description `systemd-sysusers` uses the files from `sysusers.d` directory to create system users and groups and to add users to groups, at package installation or boot time. This tool may be used to allocate system users and groups only, it is not useful for creating non-system (i.e. regular, "human") users and groups, as it accesses `/etc/passwd` and `/etc/group` directly, bypassing any more complex user databases, for example any database involving NIS or LDAP. # Configuration Directories and Precedence Each configuration file shall be named in the style of `package.conf` or `package-part.conf`. The second variant should be used when it is desirable to make it easy to override just this part of configuration. Files in `/etc/sysusers.d` override files with the same name in `/usr/lib/sysusers.d` and `/run/sysusers.d`. Files in `/run/sysusers.d` override files with the same name in `/usr/lib/sysusers.d`. Packages should install their configuration files in `/usr/lib/sysusers.d`. Files in `/etc/sysusers.d` are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in. If multiple files specify the same path, the entry in the file with the lexicographically earliest name will be applied. All later entries for the same user and group names will be logged as warnings. If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to `/dev/null` in `/etc/sysusers.d/` bearing the same filename. # Configuration File Format The file format is one line per user or group containing name, ID, GECOS field description, home directory, and login shell: #Type Name ID GECOS Home directory Shell u! httpd 404 "HTTP User" u! _authd /usr/bin/authd "Authorization user" u! postgres - "Postgresql Database" /var/lib/pgsql /usr/libexec/postgresdb g input - - m _authd input u root 0 "Superuser" /root /bin/zsh r - 500-900 Empty lines and lines beginning with the `#` character are ignored, and may be used for commenting. ## Type The type consists of a single letter. The following line types are understood: `u` Create a system user and group of the specified name should they not exist yet. The user's primary group will be set to the group bearing the same name unless the ID field specifies it. The account will be created disabled, so that logins are not allowed. Type `u` may be suffixed with an exclamation mark (`u!`) to create a fully locked account. This is recommended, since logins should typically not be allowed for system users. With or without the exclamation mark an invalid password is set. For `u!`, the account is also locked, which makes a difference for non-password forms of authentication, such as SSH or similar. `g` Create a system group of the specified name should it not exist yet. Note that `u` implicitly creates a matching group. The group will be created with no password set. `m` Add a user to a group. If the user or group do not exist yet, they will be implicitly created. `r` Add a range of numeric UIDs/GIDs to the pool to allocate new UIDs and GIDs from. If no line of this type is specified, the range of UIDs/GIDs is set to some compiled-in default. Note that both UIDs and GIDs are allocated from the same pool, in order to ensure that users and groups of the same name are likely to carry the same numeric UID and GID. ## Name The name field specifies the user or group name. The specified name must consist only of the characters a-z, A-Z, 0-9, `_` and `-`, except for the first character which must be one of a-z, A-Z or `_` (i.e. numbers and `-` are not permitted as first character). The user/group name must have at least one character, and at most 31. For further details about the syntax of user/group names, see [User/Group Name Syntax](https://systemd.io/USER_NAMES). It is strongly recommended to pick user and group names that are unlikely to clash with normal users created by the administrator. A good scheme to guarantee this is by prefixing all system and group names with the underscore, and avoiding too generic names. For `m` lines, this field should contain the user name to add to a group. For lines of type `r`, this field should be set to `-`. ## ID For `u` and `g`, the numeric 32-bit UID or GID of the user/group. Do not use IDs 65535 or 4294967295, as they have special placeholder meanings. Specify `-` for automatic UID/GID allocation for the user or group (this is strongly recommended unless it is strictly necessary to use a specific UID or GID). Alternatively, specify an absolute path in the file system. In this case, the UID/GID is read from the path's owner/group. This is useful to create users whose UID/GID match the owners of pre-existing files (such as SUID or SGID binaries). The syntaxes `uid:gid` and `uid:groupname` are supported to allow creating users with specific primary groups. The given group must be created explicitly, or it must already exist. Specifying `-` for the UID in these syntaxes is also supported. For `m` lines, this field should contain the group name to add to a user to. For lines of type `r`, this field should be set to a UID/GID range in the format `FROM-TO`, where both values are formatted as decimal ASCII numbers. Alternatively, a single UID/GID may be specified formatted as decimal ASCII numbers. ## GECOS A short, descriptive string for users to be created, enclosed in quotation marks. Note that this field may not contain colons. Only applies to lines of type `u` and should otherwise be left unset (or `-`). ## Home Directory The home directory for a new system user. If omitted, defaults to the root directory. Only applies to lines of type `u` and should otherwise be left unset (or `-`). It is recommended to omit this, unless software strictly requires a home directory to be set. `systemd-sysusers` only sets the home directory record in the user database. To actually create the directory, consider adding a corresponding `tmpfiles.d(5)` fragment. ## Shell The login shell of the user. If not specified, this will be set to `/usr/sbin/nologin`, except if the UID of the user is 0, in which case `/bin/sh` will be used. Only applies to lines of type `u` and should otherwise be left unset (or `-`). It is recommended to omit this, unless a shell different from `/usr/sbin/nologin` must be used. # Specifiers Specifiers can be used in the `Name`, `ID`, `GECOS`, `Home directory`, and `Shell` fields. An unknown or unresolvable specifier is treated as invalid configuration. The following expansions are understood: | Specifier | Meaning | Details | |-----------|---------|---------| Specifiers available {.specifiers} # Idempotence Note that `systemd-sysusers` will do nothing if the specified users or groups already exist or the users are members of specified groups, so normally there is no reason to override `sysusers.d` vendor configuration, except to block certain users or groups from being created. # See Also `systemd(1)`, `systemd-sysusers(8)` # tc # `Parent=` Configures the parent Queueing Discipline (qdisc). Takes one of `root`, `clsact`, `ingress` or a class identifier. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1–0xffff separated with a colon (`major:minor`). Defaults to `root`. `Handle=` Configures the major number of unique identifier of the qdisc, known as the handle. Takes a hexadecimal number in the range 0x1–0xffff. Defaults to unset. `Parent=` Configures the parent Queueing Discipline (qdisc). Takes one of `root`, or a qdisc identifier. The qdisc identifier is specified as the major and minor numbers in hexadecimal in the range 0x1–0xffff separated with a colon (`major:minor`). Defaults to `root`. `ClassId=` Configures the unique identifier of the class. It is specified as the major and minor numbers in hexadecimal in the range 0x1–0xffff separated with a colon (`major:minor`). Defaults to unset. # threads-aware # All functions listed here are thread-agnostic and only a single thread may operate on a given object at any given time. Different threads may access the same object at different times. Multiple independent objects may be used from different threads in parallel. All functions listed here are thread-safe and may be called in parallel from multiple threads. The code described here uses `getenv(3)`, which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call `setenv(3)` from a parallel thread. It is recommended to only do calls to `setenv()` from an early phase of the program when no other threads have been started. # timedatectl systemd timedatectl 1 timedatectl Control the system time and date timedatectl OPTIONS COMMAND # Description `timedatectl` may be used to query and change the system clock and its settings, and enable or disable time synchronization services. Use `systemd-firstboot(1)` to initialize the system time zone for mounted (but not booted) system images. `timedatectl` may be used to show the current status of time synchronization services, for example `systemd-timesyncd.service(8)`. # Commands The following commands are understood: `status` Show current settings of the system clock and RTC, including whether network time synchronization is active. If no command is specified, this is the implied default. `show` Show the same information as `status`, but in machine readable form. This command is intended to be used whenever computer-parsable output is required. Use `status` if you are looking for formatted human-readable output. By default, empty properties are suppressed. Use `--all` to show those too. To select specific properties to show, use `--property=`. `set-time [TIME]` Set the system clock to the specified timestamp. This will also update the RTC time accordingly. The timestamp may be specified in the format `2012-10-30 18:17:16`. See `systemd.time(7)` for more details about acceptable timestamp format. `set-timezone [TIMEZONE]` Set the system time zone to the specified value. Available timezones can be listed with `list-timezones`. If the RTC is configured to be in the local time, this will also update the RTC time. This call will alter the `/etc/localtime` symlink. See `localtime(5)` for more information. `list-timezones` List available time zones, one per line. Entries from the list can be set as the system timezone with `set-timezone`. `set-local-rtc [BOOL]` Takes a boolean argument. If `0`, the system is configured to maintain the RTC in universal time. If `1`, it will maintain the RTC in local time instead. Note that maintaining the RTC in the local timezone is not fully supported and will create various problems with time zone changes and daylight saving adjustments. If at all possible, keep the RTC in UTC mode. Note that invoking this will also synchronize the RTC from the system clock, unless `--adjust-system-clock` is passed (see above). This command will change the 3rd line of `/etc/adjtime`, as documented in `hwclock(8)`. `set-ntp [BOOL]` Takes a boolean argument. Controls whether network time synchronization is active and enabled (if available). If the argument is true, this enables and starts the first existing network synchronization service. If the argument is false, then this disables and stops the known network synchronization services. The way that the list of services is built is described in `systemd-timedated.service(8)`. ## systemd-timesyncd Commands The following commands are specific to `systemd-timesyncd.service(8)`. `timesync-status` Show current status of `systemd-timesyncd.service(8)`. If `--monitor` is specified, then this will monitor the status updates. `show-timesync` Show the same information as `timesync-status`, but in machine readable form. This command is intended to be used whenever computer-parsable output is required. Use `timesync-status` if you are looking for formatted human-readable output. By default, empty properties are suppressed. Use `--all` to show those too. To select specific properties to show, use `--property=`. `ntp-servers INTERFACE SERVER…` Set the interface specific NTP servers. This command can be used only when the interface is managed by `systemd-networkd`. `revert INTERFACE` Revert the interface specific NTP servers. This command can be used only when the interface is managed by `systemd-networkd`. # Options The following options are understood: `--adjust-system-clock` If `set-local-rtc` is invoked and this option is passed, the system clock is synchronized from the RTC again, taking the new setting into account. Otherwise, the RTC is synchronized from the system clock. `--monitor` If `timesync-status` is invoked and this option is passed, then `timedatectl` monitors the status of `systemd-timesyncd.service(8)` and updates the outputs. Use Ctrl+C to terminate the monitoring. `-a`; `--all` When showing properties of `systemd-timesyncd.service(8)`, show all properties regardless of whether they are set or not. `-p`; `--property=` When showing properties of `systemd-timesyncd.service(8)`, limit display to certain properties as specified as argument. If not specified, all set properties are shown. The argument should be a property name, such as `ServerName`. If specified more than once, all properties with the specified names are shown. `--value` When printing properties with `show-timesync`, only print the value, and skip the property name and `=`. `-P` # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Examples Show current settings: $ timedatectl Local time: Thu 2017-09-21 16:08:56 CEST Universal time: Thu 2017-09-21 14:08:56 UTC RTC time: Thu 2017-09-21 14:08:56 Time zone: Europe/Warsaw (CEST, +0200) System clock synchronized: yes NTP service: active RTC in local TZ: no Enable network time synchronization: $ timedatectl set-ntp true ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp === Authentication is required to control whether network time synchronization shall be enabled. Authenticating as: user Password: ******** ==== AUTHENTICATION COMPLETE === $ systemctl status systemd-timesyncd.service ● systemd-timesyncd.service - Network Time Synchronization Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled) Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago Docs: man:systemd-timesyncd.service(8) Main PID: 595 (systemd-timesyn) Status: "Using Time Server 216.239.38.15:123 (time4.google.com)." CGroup: /system.slice/systemd-timesyncd.service └─595 /usr/lib/systemd/systemd-timesyncd … Show current status of `systemd-timesyncd.service(8)`: $ timedatectl timesync-status Server: 216.239.38.15 (time4.google.com) Poll interval: 1min 4s (min: 32s; max 34min 8s) Leap: normal Version: 4 Stratum: 1 Reference: GPS Precision: 1us (-20) Root distance: 335us (max: 5s) Offset: +316us Delay: 349us Jitter: 0 Packet count: 1 Frequency: -8.802ppm # See Also `systemd(1)`, `hwclock(8)`, `date(1)`, `localtime(5)`, `systemctl(1)`, `systemd-timedated.service(8)`, `systemd-timesyncd.service(8)`, `systemd-firstboot(1)` # timesyncd.conf systemd timesyncd.conf 5 timesyncd.conf timesyncd.conf.d Network Time Synchronization configuration files `/etc/systemd/timesyncd.conf`, `/run/systemd/timesyncd.conf`, `/usr/local/lib/systemd/timesyncd.conf`, `/usr/lib/systemd/timesyncd.conf`, `/etc/systemd/timesyncd.conf.d/*.conf`, `/run/systemd/timesyncd.conf.d/*.conf`, `/usr/local/lib/systemd/timesyncd.conf.d/*.conf`, `/usr/lib/systemd/timesyncd.conf.d/*.conf` # Description These configuration files control NTP network time synchronization. See `systemd.syntax(7)` for a general description of the syntax. # Options The following settings are configured in the \[Time\] section: `NTP=` A space-separated list of NTP server host names or IP addresses. During runtime this list is combined with any per-interface NTP servers acquired from `systemd-networkd.service(8)`. `systemd-timesyncd` will contact all configured system or per-interface servers in turn, until one responds. When the empty string is assigned, the list of NTP servers is reset, and all prior assignments will have no effect. This setting defaults to an empty list. `FallbackNTP=` A space-separated list of NTP server host names or IP addresses to be used as the fallback NTP servers. Any per-interface NTP servers obtained from `systemd-networkd.service(8)` take precedence over this setting, as do any servers set via `NTP=` above. This setting is hence only relevant if no other NTP server information is known. When the empty string is assigned, the list of NTP servers is reset, and all prior assignments will have no effect. If this option is not given, a compiled-in list of NTP servers is used. `RootDistanceMaxSec=` Maximum acceptable root distance, i.e. the maximum estimated time required for a packet to travel to the server we are connected to from the server with the reference clock. If the current server does not satisfy this limit, `systemd-timesyncd` will switch to a different server. Takes a time span value. The default unit is seconds, but other units may be specified, see `systemd.time(7)`. Defaults to 5 seconds. `PollIntervalMinSec=`; `PollIntervalMaxSec=` The minimum and maximum poll intervals for NTP messages. Polling starts at the minimum poll interval, and is adjusted within the specified limits in response to received packets. Each setting takes a time span value. The default unit is seconds, but other units may be specified, see `systemd.time(7)`. `PollIntervalMinSec=` defaults to 32 seconds and must not be smaller than 16 seconds. `PollIntervalMaxSec=` defaults to 34 min 8 s (2048 seconds) and must be larger than `PollIntervalMinSec=`. `ConnectionRetrySec=` Specifies the minimum delay before subsequent attempts to contact a new NTP server are made. Takes a time span value. The default unit is seconds, but other units may be specified, see `systemd.time(7)`. Defaults to 30 seconds and must not be smaller than 1 second. `SaveIntervalSec=` The interval at which the current time is periodically saved to disk, in the absence of any recent synchronisation from an NTP server. This is especially useful for offline systems with no local RTC, as it will guarantee that the system clock remains roughly monotonic across reboots. Takes a time interval value. The default unit is seconds, but other units may be specified, see `systemd.time(7)`. Defaults to 60 seconds. # See Also `systemd(1)`, `systemd-timesyncd.service(8)`, `systemd-networkd.service(8)` # tmpfiles.d systemd tmpfiles.d 5 tmpfiles.d Configuration for creation, deletion, and cleaning of files and directories `/etc/tmpfiles.d/*.conf`, `/run/tmpfiles.d/*.conf`, `/usr/local/lib/tmpfiles.d/*.conf`, `/usr/lib/tmpfiles.d/*.conf` `~/.config/user-tmpfiles.d/*.conf`, `$XDG_RUNTIME_DIR/user-tmpfiles.d/*.conf`, `~/.local/share/user-tmpfiles.d/*.conf`, `…`, `/usr/local/share/user-tmpfiles.d/*.conf`, `/usr/share/user-tmpfiles.d/*.conf` #Type Path Mode User Group Age Argument f /file/to/create mode user group - content f+ /file/to/create-or-truncate mode user group - content w /file/to/write-to - - - - content w+ /file/to/append-to - - - - content d /directory/to/create-and-clean-up mode user group cleanup-age - D /directory/to/create-and-remove mode user group cleanup-age - e /directory/to/clean-up mode user group cleanup-age - v /subvolume-or-directory/to/create mode user group cleanup-age - q /subvolume-or-directory/to/create mode user group cleanup-age - Q /subvolume-or-directory/to/create mode user group cleanup-age - p /fifo/to/create mode user group - - p+ /fifo/to/[re]create mode user group - - L /symlink/to/create - - - - symlink/target/path L+ /symlink/to/[re]create - - - - symlink/target/path c /dev/char-device-to-create mode user group - major:minor c+ /dev/char-device-to-[re]create mode user group - major:minor b /dev/block-device-to-create mode user group - major:minor b+ /dev/block-device-to-[re]create mode user group - major:minor C /target/to/create - - - cleanup-age /source/to/copy C+ /target/to/create - - - cleanup-age /source/to/copy x /path-or-glob/to/ignore/recursively - - - cleanup-age - X /path-or-glob/to/ignore - - - cleanup-age - r /path-or-glob/to/remove - - - - - R /path-or-glob/to/remove/recursively - - - - - z /path-or-glob/to/adjust/mode mode user group - - Z /path-or-glob/to/adjust/mode/recursively mode user group - - t /path-or-glob/to/set/xattrs - - - - xattrs T /path-or-glob/to/set/xattrs/recursively - - - - xattrs h /path-or-glob/to/set/attrs - - - - file attrs H /path-or-glob/to/set/attrs/recursively - - - - file attrs a /path-or-glob/to/set/acls - - - - POSIX ACLs a+ /path-or-glob/to/append/acls - - - - POSIX ACLs A /path-or-glob/to/set/acls/recursively - - - - POSIX ACLs A+ /path-or-glob/to/append/acls/recursively - - - - POSIX ACLs k /path-or-glob/to/set/caps - - - - file capabilities k+ /path-or-glob/to/adjust/caps - - - - file capabilities K /path-or-glob/to/set/caps/recursively - - - - file capabilities K+ /path-or-glob/to/adjust/caps/recursively - - - - file capabilities # Description `tmpfiles.d` configuration files provide a generic mechanism to define the *creation* of regular files, directories, pipes, and device nodes, adjustments to their *access mode, ownership, attributes, quota assignments, and contents*, and finally their time-based *removal*. It is mostly commonly used for volatile and temporary files and directories (such as those located under `/run/`, `/tmp/`, `/var/tmp/`, the API file systems such as `/sys/` or `/proc/`, as well as some other directories below `/var/`). `systemd-tmpfiles(8)` uses this configuration to create volatile files and directories during boot and to do periodic cleanup afterwards. See `systemd-tmpfiles(8)` for the description of `systemd-tmpfiles-setup.service`, `systemd-tmpfiles-clean.service`, and associated units. System daemons frequently require private runtime directories below `/run/` to store communication sockets and similar. For these, it is better to use `RuntimeDirectory=` in their unit files (see `systemd.exec(5)` for details), if the flexibility provided by `tmpfiles.d` is not required. The advantages are that the configuration required by the unit is centralized in one place, and that the lifetime of the directory is tied to the lifetime of the service itself. Similarly, `StateDirectory=`, `CacheDirectory=`, `LogsDirectory=`, and `ConfigurationDirectory=` should be used to create directories under `/var/lib/`, `/var/cache/`, `/var/log/`, and `/etc/`. `tmpfiles.d` should be used for files whose lifetime is independent of any service or requires more complicated configuration. # Configuration Directories and Precedence Each configuration file shall be named in the style of `package.conf` or `package-part.conf`. The second variant should be used when it is desirable to make it easy to override just this part of configuration. Files in `/etc/tmpfiles.d` override files with the same name in `/usr/lib/tmpfiles.d` and `/run/tmpfiles.d`. Files in `/run/tmpfiles.d` override files with the same name in `/usr/lib/tmpfiles.d`. Packages should install their configuration files in `/usr/lib/tmpfiles.d`. Files in `/etc/tmpfiles.d` are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in. If multiple files specify the same path, the entry in the file with the lexicographically earliest name will be applied (note that lines suppressed due to the `!` are filtered before application, meaning that if an early line carries the exclamation mark and is suppressed because of that, a later line matching in path will be applied). All other conflicting entries will be logged as errors. When two lines are prefix path and suffix path of each other, then the prefix line is always created first, the suffix later (and if removal applies to the line, the order is reversed: the suffix is removed first, the prefix later). Lines that take globs are applied after those accepting no globs. If multiple operations shall be applied on the same file (such as ACL, xattr, file attribute adjustments), these are always done in the same fixed order. Except for those cases, the files/directories are processed in the order they are listed. If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to `/dev/null` in `/etc/tmpfiles.d/` bearing the same filename. # Configuration File Format The configuration format is one line per path, containing type, path, mode, ownership, age, and argument fields. The lines are separated by newlines, the fields by whitespace: #Type Path Mode User Group Age Argument… d /run/user 0755 root root 10d - L /tmp/foobar - - - - /dev/null Fields may contain C-style escapes. With the exception of the seventh field (the "argument") all fields may be enclosed in quotes. Note that any whitespace found in the line after the beginning of the argument field will be considered part of the argument field. To begin the argument field with a whitespace character, use C-style escapes (e.g. `\x20`). Line types which do not document use of the argument field reject a non-empty argument field; use `-` to leave the argument field empty. ## Type The type consists of a single letter and optionally one or more modifier characters: a plus sign (`+`), exclamation mark (`!`), minus sign (`-`), equals sign (`=`), tilde character (`~`) and/or caret (`^`). The following line types are understood: `f`; `f+` `f` will create a file if it does not exist yet. If the argument parameter is given and the file did not exist yet, it will be written to the file. `f+` will create or truncate the file. If the argument parameter is given, it will be written to the file. Does not follow symlinks. `w`; `w+` Write the argument parameter to a file, if the file exists. If suffixed with `+`, the line will be appended to the file. If your configuration writes multiple lines to the same file, use `w+`. Lines of this type accept shell-style globs in place of normal path names. The argument parameter will be written without a trailing newline. C-style backslash escapes are interpreted. Follows symlinks. `d` Create a directory. The mode and ownership will be adjusted if specified. Contents of this directory are subject to time-based cleanup if the age argument is specified. `D` Similar to `d`, but in addition the contents of the directory will be removed when `--remove` is used. `e` Adjust the mode and ownership of existing directories and remove their contents based on age. Lines of this type accept shell-style globs in place of normal path names. Contents of the directories are subject to time-based cleanup if the age argument is specified. If the age argument is `0`, contents will be unconditionally deleted every time `systemd-tmpfiles(8)` `--clean` is run. For this entry to be useful, at least one of the mode, user, group, or age arguments must be specified, since otherwise this entry has no effect. As an exception, an entry with no effect may be useful when combined with `!`, see the examples. `v` Create a subvolume if the path does not exist yet, the file system supports subvolumes (btrfs), and the system itself is installed into a subvolume (specifically: the root directory `/` is itself a subvolume). Otherwise, create a normal directory, in the same way as `d`. A subvolume created with this line type is not assigned to any higher-level quota group. For that, use `q` or `Q`, which allow creating simple quota group hierarchies, see below. `q` Create a subvolume or directory the same as `v`, but assign the subvolume to the same higher-level quota groups as the parent. This ensures that higher-level limits and accounting applied to the parent subvolume also include the specified subvolume. On non-btrfs file systems, this line type is identical to `d`. If the subvolume already exists, no change to the quota hierarchy is made, regardless of whether the subvolume is already attached to a quota group or not. Also see `Q` below. See `btrfs-qgroup(8)` for details about the btrfs quota group concept. `Q` Create the subvolume or directory the same as `v`, but assign the new subvolume to a new leaf quota group. Instead of copying the higher-level quota group assignments from the parent as is done with `q`, the lowest quota group of the parent subvolume is determined that is not the leaf quota group. Then, an "intermediary" quota group is inserted that is one level below this level, and shares the same ID part as the specified subvolume. If no higher-level quota group exists for the parent subvolume, a new quota group at level 255 sharing the same ID as the specified subvolume is inserted instead. This new intermediary quota group is then assigned to the parent subvolume's higher-level quota groups, and the specified subvolume's leaf quota group is assigned to it. Effectively, this has a similar effect as `q`, however introduces a new higher-level quota group for the specified subvolume that may be used to enforce limits and accounting to the specified subvolume and children subvolume created within it. Thus, by creating subvolumes only via `q` and `Q`, a concept of "subtree quotas" is implemented. Each subvolume for which `Q` is set will get a "subtree" quota group created, and all child subvolumes created within it will be assigned to it. Each subvolume for which `q` is set will not get such a "subtree" quota group, but it is ensured that they are added to the same "subtree" quota group as their immediate parents. It is recommended to use `Q` for subvolumes that typically contain further subvolumes, and where it is desirable to have accounting and quota limits on all child subvolumes together. Examples for `Q` are typically `/home/` or `/var/lib/machines/`. In contrast, `q` should be used for subvolumes that either usually do not include further subvolumes or where no accounting and quota limits are needed that apply to all child subvolumes together. Examples for `q` are typically `/var/` or `/var/tmp/`. As with `q`, `Q` has no effect on the quota group hierarchy if the subvolume already exists, regardless of whether the subvolume already belong to a quota group or not. `p`; `p+` Create a named pipe (FIFO) if it does not exist yet. If suffixed with `+` and a file already exists where the pipe is to be created, it will be removed and be replaced by the pipe. `L`; `L+`; `L?` Create a symlink if it does not exist yet. If suffixed with `+` and a file or directory already exists where the symlink is to be created, it will be removed and be replaced by the symlink. If suffixed with `?` and the source path does not exist, the symlink is not created. If the argument is omitted, symlinks to files with the same name residing in the directory `/usr/share/factory/` are created. Note that permissions on symlinks are ignored. `c`; `c+` Create a character device node if it does not exist yet. If suffixed with `+` and a file already exists where the device node is to be created, it will be removed and be replaced by the device node. It is recommended to suffix this entry with an exclamation mark to only create static device nodes at boot, as udev will not manage static device nodes that are created at runtime. `b`; `b+` Create a block device node if it does not exist yet. If suffixed with `+` and a file already exists where the device node is to be created, it will be removed and be replaced by the device node. It is recommended to suffix this entry with an exclamation mark to only create static device nodes at boot, as udev will not manage static device nodes that are created at runtime. `C`; `C+` Recursively copy a file or directory, if the destination files or directories do not exist yet or the destination directory is empty. Note that this command will not descend into subdirectories if the destination directory already exists and is not empty, unless the action is suffixed with `+`. Instead, the entire copy operation is skipped. If the argument is omitted, files from the source directory `/usr/share/factory/` with the same name are copied. Does not follow symlinks. Contents of the directories are subject to time-based cleanup if the age argument is specified. `x` Ignore a path during cleaning. Use this type to exclude paths from clean-up as controlled with the Age parameter. Lines of this type accept shell-style globs in place of normal path names. `X` Ignore a path during cleaning. Use this type to exclude paths from clean-up as controlled with the Age parameter. Unlike `x`, this parameter will not exclude the content if path is a directory, but only directory itself. Lines of this type accept shell-style globs in place of normal path names. `r` Remove a file or directory if it exists. This may not be used to remove non-empty directories, use `R` for that. Lines of this type accept shell-style globs in place of normal path names. Does not follow symlinks. When `--clean` is used, the file or directory is subject to time-based cleanup if the age argument is specified. This age handling was added in v262. `R` Recursively remove a path and all its subdirectories (if it is a directory). Lines of this type accept shell-style globs in place of normal path names. Does not follow symlinks. When `--clean` is used, the path is subject to time-based cleanup if the age argument is specified. This age handling was added in v262. `z` Adjust the access mode, user and group ownership, and restore the SELinux security context of a file or directory, if it exists. Lines of this type accept shell-style globs in place of normal path names. Does not follow symlinks. `Z` Recursively set the access mode, user and group ownership, and restore the SELinux security context of a file or directory if it exists, as well as of its subdirectories and the files contained therein (if applicable). Lines of this type accept shell-style globs in place of normal path names. Does not follow symlinks. `t` Set extended attributes, see `attr(5)` for details. The argument field should take one or more assignment expressions in the form \.\=\, for examples see below. Lines of this type accept shell-style globs in place of normal path names. This can be useful for setting SMACK labels. Does not follow symlinks. Please note that extended attributes settable with this line type are a different concept from the Linux file attributes settable with `h`/`H`, see below. `T` Same as `t`, but operates recursively. `h` Set Linux file/directory attributes. Lines of this type accept shell-style globs in place of normal path names. The format of the argument field is `[+-=][aAcCdDeijPsStTu]`. The prefix `+` (the default one) causes the attributes to be added; `-` causes the attributes to be removed; `=` causes the attributes to be set exactly as the following letters. The letters `aAcCdDeijPsStTu` select the new attributes for the files, see `chattr(1)` for further information. Passing only `=` as argument resets all the file attributes listed above. It has to be pointed out that the `=` prefix limits itself to the attributes corresponding to the letters listed here. All other attributes will be left untouched. Does not follow symlinks. Please note that the Linux file attributes settable with this line type are a different concept from the extended attributes settable with `t`/`T`, see above. `H` Sames as `h`, but operates recursively. `a`; `a+` Set POSIX ACLs (access control lists), see `acl(5)`. Additionally, if 'X' is used, the execute bit is set only if the file is a directory or already has execute permission for some user, as mentioned in `setfacl(1)`. If suffixed with `+`, the specified entries will be added to the existing set. `systemd-tmpfiles(8)` will automatically add the required base entries for user and group based on the access mode of the file, unless base entries already exist or are explicitly specified. The mask will be added if not specified explicitly or already present. Lines of this type accept shell-style globs in place of normal path names. This can be useful for allowing additional access to certain files. Does not follow symlinks. `A`; `A+` Same as `a` and `a+`, but recursive. Does not follow symlinks. `k`; `k+` Set file capabilities, see `capabilities(7)`. Lines of this type accept shell-style globs in place of normal path names. Does not follow symlinks. The syntax follows `cap_text_formats(7)`. It also supports `rootuid=INT` for the user namespace root user ID. If suffixed with `+`, current capabilities on the file that are not touched by the expression will be kept. For example, if all `cap_setuid` capabilities need to be removed but others should be kept, one can use `k+` with `cap_setuid=` or `cap_setuid-eip`. `K`; `K+` Same as `k` and `k+`, but recursive. Does not follow symlinks. ## Type Modifiers If the exclamation mark (`!`) is used, this line is only safe to execute during boot, and can break a running system. Lines without the exclamation mark are presumed to be safe to execute at any time, e.g. on package upgrades. `systemd-tmpfiles(8)` will take lines with an exclamation mark only into consideration, if the `--boot` option is given. For example: # Make sure these are created by default so that nobody else can d /tmp/.X11-unix 1777 root root 10d # Unlink the X11 lock files r! /tmp/.X[0-9]*-lock The second line in contrast to the first one would break a running system, and will only be executed with `--boot`. If the minus sign (`-`) is used, this line failing to run successfully during create (and only create) will not cause the execution of `systemd-tmpfiles(8)` to return an error. For example: # Modify sysfs but do not fail if we are in a container with a read-only /proc w- /proc/sys/vm/swappiness - - - - 10 If the equals sign (`=`) is used, the file types of existing objects in the specified path are checked, and removed if they do not match. This includes any implicitly created parent directories (which can be either directories or directory symlinks). For example, if there is a FIFO in place of one of the parent path components it will be replaced with a directory. If the tilde character (`~`) is used, the argument (i.e. 6th) column is [Base64 decoded](https://www.rfc-editor.org/rfc/rfc4648.html) before use. This modifier is only supported on line types that can write file contents, i.e. `f`, `f+`, `w`, `+`. This is useful for writing arbitrary binary data (including newlines and NUL bytes) to files. Note that if this switch is used, the argument is not subject to specifier expansion, neither before nor after Base64 decoding. If the caret character (`^`) is used, the argument (i.e. 6th) column takes a service credential name to read the argument data from. See [System and Service Credentials](https://systemd.io/CREDENTIALS) for details about the credentials concept. This modifier is only supported on line types that can write file contents, i.e. `f`, `f+`, `w`, `w+`. This is useful for writing arbitrary files with contents sourced from elsewhere, including from VM or container managers further up. If the specified credential is not set for the `systemd-tmpfiles` service, the line is silently skipped. If `^` and `~` are combined Base64 decoding is applied to the credential contents. If the dollar sign (`$`) is used, the file becomes subject to removal when `systemd-tmpfiles` is invoked with the `--purge` switch. Lines without this character are unaffected by that switch. Note that for all line types that result in creation of any kind of file node (i.e. `f`, `d`/`D`/`v`/`q`/`Q`, `p`, `L`, `c`/`b` and `C`) leading directories are implicitly created if needed, owned by root with an access mode of 0755. In order to create them with different modes or ownership make sure to add appropriate `d` lines. ## Path The file system path specification supports simple specifier expansion, see below. The path (after expansion) must be absolute. ## Mode The file access mode to use when creating this file or directory. If omitted or when set to `-`, the default is used: 0755 for directories, 0644 for all other file objects. For `z`, `Z` lines, if omitted or when set to `-`, the file access mode will not be modified. This parameter is ignored for `x`, `r`, `R`, `L`, `t`, `a`, and `k` lines. Optionally, if prefixed with `~`, the access mode is masked based on the already set access bits for existing file or directories: if the existing file has all executable bits unset, all executable bits are removed from the new access mode, too. Similarly, if all read bits are removed from the old access mode, they will be removed from the new access mode too, and if all write bits are removed, they will be removed from the new access mode too. In addition, the sticky/SUID/SGID bit is removed unless applied to a directory. This functionality is particularly useful in conjunction with `Z`. By default, the access mode of listed inodes is set to the specified mode regardless of whether it is created anew, or already existed. Optionally, if prefixed with `:`, the configured access mode is only applied when creating new inodes, and if the inode the line refers to already exists, its access mode is left in place unmodified. ## User, Group The user and group to use for this file or directory. This may either be a numeric ID or a user/group name. If omitted or when set to `-`, the user and group of the user who invokes `systemd-tmpfiles(8)` is used. For `z` and `Z` lines, when omitted or when set to `-`, the file ownership will not be modified. These parameters are ignored for `x`, `r`, `R`, `t`, and `a` lines. This field should generally only reference system users/groups, i.e. users/groups that are guaranteed to be resolvable during early boot. If this field references users/groups that only become resolvable during later boot (i.e. after NIS, LDAP or a similar networked directory service become available), execution of the operations declared by the line will likely fail. Also see [Notes on Resolvability of User and Group Names](https://systemd.io/UIDS-GIDS/#notes-on-resolvability-of-user-and-group-names) for more information on requirements on system user/group definitions. By default, the ownership of listed inodes is set to the specified user/group regardless of whether it is created anew, or already existed. Optionally, if prefixed with `:`, the configured user/group information is only applied when creating new inodes, and if the inode the line refers to already exists, its user/group is left in place unmodified. ## Age The date field, when set, is used to decide what files to delete when cleaning. If a file or directory is older than the current time minus the age field, it is deleted. The field format is a series of integers each followed by one of the following suffixes for the respective time units: `s`, `m` or `min`, `h`, `d`, `w`, `ms`, and `us`, meaning seconds, minutes, hours, days, weeks, milliseconds, and microseconds, respectively. Full names of the time units can be used too. If multiple integers and units are specified, the time values are summed. If an integer is given without a unit, `s` is assumed. When the age is set to zero, the files are cleaned unconditionally. The age field only applies to lines starting with `d`, `D`, `e`, `v`, `q`, `Q`, `C`, `r`, `R`, `x` and `X`. If omitted or set to `-`, no automatic clean-up is done. If the age field starts with a tilde character `~`, clean-up is only applied to files and directories one level inside the directory specified, but not the files and directories immediately inside it. For `R` lines, this also skips removing the specified top-level directory itself. This modifier is not supported by `r` lines. The age of a file system entry is determined from its last modification timestamp (mtime), its last access timestamp (atime), and (except for directories) its last status change timestamp (ctime). By default, any of these three (or two) values will prevent cleanup if it is more recent than the current time minus the age field. To restrict the deletion based on particular type of file timestamps, the age-by argument can be used. The age-by argument overrides the timestamp types to be used for the age check. It can be specified by prefixing the age argument with a sequence of characters to specify the timestamp types and a colon (`:`): `age-by...:cleanup-age`. The argument can consist of `a` (`A` for directories), `b` (`B` for directories), `c` (`C` for directories), or `m` (`M` for directories). Those respectively indicate access, creation, last status change, and last modification time of a file system entry. The lower-case letter signifies that the given timestamp type should be considered for files, while the upper-case letter signifies that the given timestamp type should be considered for directories. See `statx(2)` file timestamp fields for more details about timestamp types. If not specified, the age-by field defaults to `abcmABM`, i.e. by default all file timestamps are taken into consideration, with the exception of the last status change timestamp (ctime) for directories. This is because the aging logic itself will alter the ctime whenever it deletes a file inside it. To ensure that running the aging logic does not feed back into the next iteration of itself, ctime for directories is ignored by default. For example: # Files created and modified, and directories accessed more than # an hour ago in "/tmp/foo/bar", are subject to time-based cleanup. d /tmp/foo/bar - - - bmA:1h - Note that while the aging algorithm is run an exclusive BSD file lock (see `flock(2)`) is taken on each directory/file the algorithm decides to remove. If the aging algorithm finds a lock (shared or exclusive) is already taken on some directory/file, it (and everything below it) is skipped. Applications may use this to temporarily exclude certain directory subtrees from the aging algorithm: the applications can take a BSD file lock themselves, and as long as they keep it aging of the directory/file and everything below it is disabled. This behavior can be used to ensure guaranteed cleanup of files or directories whose lifetime should be aligned with the process that created them by having that process create them in a location monitored by `systemd-tmpfiles` with an age of `0`, and having the process immediately lock the directory or file before using it. Because the BSD lock is process specific, the file is guaranteed to be unlocked as soon as the process exits, meaning that even if the process crashes, those files and directories will be unlocked and cleaned up by `systemd-tmpfiles`. ## Argument For `L` lines determines the destination path of the symlink. For `c` and `b`, determines the major/minor of the device node, with major and minor formatted as integers, separated by `:`, e.g. `1:3`. For `f` and `w`, the argument may be used to specify a short string that is written to the file, suffixed by a newline. For `C`, specifies the source file or directory. For `t` and `T`, determines extended attributes to be set. For `a` and `A`, determines ACL attributes to be set. For `h` and `H`, determines the file attributes to set. For `k` and `K`, determines file capabilities to be set. For line types that do not document use of this field, a non-empty argument is rejected; use `-` to leave it unset. This field can contain specifiers, see below. # Specifiers Specifiers can be used in the "path" and "argument" fields. An unknown or unresolvable specifier is treated as invalid configuration. The following expansions are understood: | Specifier | Meaning | Details | |----|----|----| | `%C` | System or user cache directory | In `--user` mode, this is the same as `$XDG_CACHE_HOME`, and `/var/cache` otherwise. | | `%g` | User group | This is the name of the group running the command. In case of the system instance this resolves to `root`. | | `%G` | User GID | This is the numeric GID of the group running the command. In case of the system instance this resolves to `0`. | | `%h` | User home directory | This is the home directory of the user running the command. In case of the system instance this resolves to `/root`. | | `%L` | System or user log directory | In `--user` mode, this is the same as `$XDG_STATE_HOME` with `/log` appended, and `/var/log` otherwise. | | `%S` | System or user state directory | In `--user` mode, this is the same as `$XDG_STATE_HOME`, and `/var/lib` otherwise. | | `%t` | System or user runtime directory | In `--user` mode, this is the same as `$XDG_RUNTIME_DIR`, and `/run/` otherwise. | | `%u` | User name | This is the name of the user running the command. In case of the system instance this resolves to `root`. | | `%U` | User UID | This is the numeric UID of the user running the command. In case of the system instance this resolves to `0`. | Specifiers available {.specifiers} # Examples
Create directories with specific mode and ownership
`screen(1)`, needs two directories created at boot with specific modes and ownership: # /usr/lib/tmpfiles.d/screen.conf d /run/screens 1777 root screen 10d d /run/uscreens 0755 root screen 10d12h Contents of `/run/screens` and /run/uscreens will be cleaned up after 10 and 10½ days, respectively.
Create a directory with a SMACK attribute
D /run/cups - - - - t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar" The directory will be owned by root and have default mode. Its contents are not subject to time-based cleanup, but will be obliterated when `systemd-tmpfiles --remove` runs.
Create a directory and prevent its contents from cleanup
`abrt(1)`, needs a directory created at boot with specific mode and ownership and its content should be preserved from the automatic cleanup applied to the contents of `/var/tmp`: # /usr/lib/tmpfiles.d/tmp.conf d /var/tmp 1777 root root 30d # /usr/lib/tmpfiles.d/abrt.conf d /var/tmp/abrt 0755 abrt abrt -
Apply clean up during boot and based on time
# /usr/lib/tmpfiles.d/dnf.conf r! /var/cache/dnf/*/*/download_lock.pid r! /var/cache/dnf/*/*/metadata_lock.pid r! /var/lib/dnf/rpmdb_lock.pid e /var/cache/dnf/ - - - 30d The lock files will be removed during boot. Any files and directories in `/var/cache/dnf/` will be removed after they have not been accessed in 30 days.
Empty the contents of a cache directory on boot
# /usr/lib/tmpfiles.d/krb5rcache.conf e! /var/cache/krb5rcache - - - 0 Any files and subdirectories in `/var/cache/krb5rcache/` will be removed on boot. The directory will not be created.
Provision SSH public key access for root user via Credentials in QEMU
-smbios type=11,value=io.systemd.credential.binary:tmpfiles.extra=$(echo -e "d /root/.ssh 0750 root root -\nf~ /root/.ssh/authorized_keys 0600 root root - $(ssh-add -L | base64 -w 0)" | base64 -w 0) By passing this line to QEMU, the public key of the current user will be encoded in base64, added to a tmpfiles.d line that tells `systemd-tmpfiles(8)` to decode it into `/root/.ssh/authorized_keys`, encode that line itself in base64 and pass it as a Credential that will be picked up by systemd from SMBIOS on boot.
# `/run/` and `/var/run/` `/var/run/` is a deprecated symlink to `/run/`, and applications should use the latter. `systemd-tmpfiles` will warn if `/var/run/` is used. # See Also `systemd(1)`, `systemd-tmpfiles(8)`, `systemd-delta(1)`, `systemd.exec(5)`, `attr(5)`, `getfattr(1)`, `setfattr(1)`, `setfacl(1)`, `getfacl(1)`, `chattr(1)`, `btrfs-subvolume(8)`, `btrfs-qgroup(8)` # udev.conf systemd udev.conf 5 udev.conf udev.conf.d Configuration for device event managing daemon `/etc/udev/udev.conf`, `/run/udev/udev.conf`, `/usr/local/lib/udev/udev.conf`, `/usr/lib/udev/udev.conf`, `/etc/udev/udev.conf.d/*.conf`, `/run/udev/udev.conf.d/*.conf`, `/usr/local/lib/udev/udev.conf.d/*.conf`, `/usr/lib/udev/udev.conf.d/*.conf` # Description These files contain configuration options for `systemd-udevd(8)`. The syntax of these files is very simple: a list of assignments, one per line. All empty lines or lines beginning with `#` are ignored. The following options can be set: `udev_log=` The log level. Valid values are the numerical syslog priorities or their textual representations: `err`, `info` and `debug`. > [!NOTE] > This option is also honored by `udevadm(8)`. `children_max=` An integer. The maximum number of events executed in parallel. When unspecified or 0 is specified, the maximum is determined based on the system resources. This is the same as the `--children-max=` option. `exec_delay=` An integer. Delay the execution of each `RUN{program}` parameter by the given number of seconds. This option might be useful when debugging system crashes during coldplug caused by loading non-working kernel modules. This is the same as the `--exec-delay=` option. `event_timeout=` An integer. The number of seconds to wait for events to finish. After this time, the event will be terminated. The default is 180 seconds. This is the same as the `--event-timeout=` option. `resolve_names=` Specifies when systemd-udevd should resolve names of users and groups. When set to `early` (the default), names will be resolved when the rules are parsed. When set to `late`, names will be resolved for every event. When set to `never`, names will never be resolved and all devices will be owned by root. This is the same as the `--resolve-names=` option. `timeout_signal=` Specifies a signal that `systemd-udevd` will send on worker timeouts. Note that both workers and spawned processes will be killed using this signal. Defaults to `SIGKILL`. In addition, `systemd-udevd` can be configured by command line options and the kernel command line (see `systemd-udevd(8)`). # See Also `systemd-udevd(8)`, `udev(7)`, `udevadm(8)` # udev systemd udev 7 udev Dynamic device management # Description udev supplies the system software with device events, manages permissions of device nodes and may create additional symlinks in the `/dev/` directory, or renames network interfaces. The kernel usually just assigns unpredictable device names based on the order of discovery. Meaningful symlinks or network device names provide a way to reliably identify devices based on their properties or current configuration. The udev daemon, `systemd-udevd.service(8)`, receives device uevents directly from the kernel whenever a device is added or removed from the system, or it changes its state. When udev receives a device event, it matches its configured set of rules against various device attributes to identify the device. Rules that match may provide additional device information to be stored in the udev database or to be used to create meaningful symlink names. All device information udev processes is stored in the udev database and sent out to possible event subscribers. Access to all stored data and the event sources is provided by the library libudev. # Rules Files The udev rules are read from the files located in the system rules directories `/usr/lib/udev/rules.d` and `/usr/local/lib/udev/rules.d`, the volatile runtime directory `/run/udev/rules.d` and the local administration directory `/etc/udev/rules.d`. All rules files are collectively sorted and processed in lexicographic order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in `/etc/` have the highest priority, files in `/run/` take precedence over files with the same name under `/usr/`. This can be used to override a system-supplied rules file with a local file if needed; a symlink in `/etc/` with the same name as a rules file in `/usr/lib/`, pointing to `/dev/null`, disables the rules file entirely. Rule files must have the extension `.rules`; other extensions are ignored. Every line in the rules file contains at least one key-value pair. A line ending with a backslash (`\`) is joined with the following line, and the result is processed as a single line. Lines beginning with `#` are ignored, even within a continuation. An empty or whitespace-only line ends a pending continuation and is otherwise ignored. There are two kinds of keys: match and assignment. If all match keys match against their values, the rule gets applied and the assignment keys get the specified values assigned. A matching rule may rename a network interface, add symlinks pointing to the device node, or run a specified program as part of the event handling. A rule consists of a comma-separated list of one or more key-operator-value expressions. Each expression has a distinct effect, depending on the key and operator used. ## Operators `==` Compare for equality. (The specified key has the specified value.) `!=` Compare for inequality. (The specified key does not have the specified value, or the specified key is not present at all.) `=` Assign a value to a key. Keys that represent a list are reset and only this single value is assigned. `+=` Add the value to a key that holds a list of entries. `-=` Remove the value from a key that holds a list of entries. `:=` Assign a value to a key finally; disallow any later changes. ## Values Values are written as double quoted strings, such as ("string"). To include a quotation mark (") in the value, precede it by a backslash (\\"). Any other occurrences of a backslash followed by a character are not unescaped. That is, "\t\n" is treated as four characters: backslash, lowercase t, backslash, lowercase n. The string can be prefixed with a lowercase e (e"string\n") to mark the string as C-style escaped, see [Escape sequences in C](https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences). For example, e"string\n" is parsed as 7 characters: 6 lowercase letters and a newline. This can be useful for writing special characters when a kernel driver requires them. The string can be prefixed with a lowercase i (i"string") to mark that the string or pattern will match case-insensitively. For example, i"foo" will match `foo`, `FOO`, `FoO` and so on. The prefix can be used only for match (`==`) or unmatch (`!=`) rules, e.g. `ATTR{foo}==i"abcd"`. Please note that `NUL` is not allowed in either string variant. ## Keys The following key names can be used to match against device properties. Some of the keys also match against properties of the parent devices in sysfs, not only the device that has generated the event. If multiple keys that match a parent device are specified in a single rule, all these keys must match at one and the same parent device. `ACTION` Match the name of the event action. `DEVPATH` Match the devpath of the event device. `KERNEL` Match the name of the event device. `KERNELS` Search the devpath upwards for a matching device name. `NAME` Match the name of a network interface. It can be used once the NAME key has been set in one of the preceding rules. `SYMLINK` Match the name of a symlink targeting the node. It can be used once a SYMLINK key has been set in one of the preceding rules. There may be multiple symlinks; only one needs to match. If the operator is `!=`, the token returns true only if there is no symlink matched. `SUBSYSTEM` Match the subsystem of the event device. `SUBSYSTEMS` Search the devpath upwards for a matching device subsystem name. `DRIVER` Match the driver name of the event device. Only set this key for devices which are bound to a driver at the time the event is generated. `DRIVERS` Search the devpath upwards for a matching device driver name. `ATTR{filename}` Match sysfs attribute value of the event device. Trailing whitespace in the attribute values is ignored unless the specified match value itself contains trailing whitespace. `ATTRS{filename}` Search the devpath upwards for a device with matching sysfs attribute values. If multiple `ATTRS` matches are specified, all of them must match on the same device. Trailing whitespace in the attribute values is ignored unless the specified match value itself contains trailing whitespace. `SYSCTL{kernel parameter}` Match a kernel parameter value. `ENV{key}` Match against a device property value. `CONST{key}` Match against a system-wide constant. Supported keys are: `arch` System's architecture. See `ConditionArchitecture=` in `systemd.unit(5)` for possible values. `virt` System's virtualization environment. See `systemd-detect-virt(1)` for possible values. `cvm` System's confidential virtualization technology. See `systemd-detect-virt(1)` for possible values. Unknown keys will never match. `TAG` Match against one of device tags. It can be used once a TAG key has been set in one of the preceding rules. There may be multiple tags; only one needs to match. If the operator is `!=`, the token returns true only if there is no tag matched. `TAGS` Search the devpath upwards for a device with matching tag. If the operator is `!=`, the token returns true only if there is no tag matched. `TEST{octal mode mask}` Test the existence of a file. An octal mode mask can be specified if needed. `PROGRAM` Execute a program to determine whether there is a match; the key is true if the program returns successfully. The device properties are made available to the executed program in the environment. The program's standard output is available in the `RESULT` key. This can only be used for very short-running foreground tasks. For details, see `RUN`. Note that multiple `PROGRAM` keys may be specified in one rule, and `=`, `:=`, and `+=` have the same effect as `==`. `RESULT` Match the returned string of the last `PROGRAM` call. This key can be used in the same or in any later rule after a `PROGRAM` call. Most of the fields support shell glob pattern matching and alternate patterns. The following special characters are supported: `*` Matches zero or more characters. `?` Matches any single character. `[]` Matches any single character specified within the brackets. For example, the pattern string `tty[SR]` would match either `ttyS` or `ttyR`. Ranges are also supported via the `-` character. For example, to match on the range of all digits, the pattern `[0-9]` could be used. If the first character following the `[` is a `!`, any characters not enclosed are matched. `|` Separates alternative patterns. For example, the pattern string `abc|x*` would match either `abc` or `x*`. The following keys can get values assigned: `NAME` The name to use for a network interface. See `systemd.link(5)` for a higher-level mechanism for setting the interface name. The name of a device node cannot be changed by udev, only additional symlinks can be created. `SYMLINK` The name of a symlink targeting the node. Every matching rule adds this value to the list of symlinks to be created. The set of characters to name a symlink is limited. Allowed characters are `0-9A-Za-z#+-.:=@_/`, valid UTF-8 character sequences, and `\x00` hex encoding. All other characters are replaced by a `_` character. Multiple symlinks may be specified by separating the names by the space character. In case multiple devices claim the same name, the link always points to the device with the highest link_priority. If the current device goes away, the links are re-evaluated and the device with the next highest link_priority becomes the owner of the link. If no link_priority is specified, the order of the devices (and which one of them owns the link) is undefined. Symlink names must never conflict with the kernel's default device node names, as that would result in unpredictable behavior. `OWNER`, `GROUP`, `MODE` The permissions for the device node. Every specified value overrides the compiled-in default value. `SECLABEL{module}` Applies the specified Linux Security Module label to the device node. `ATTR{key}` The value that should be written to a sysfs attribute of the event device. `SYSCTL{kernel parameter}` The value that should be written to kernel parameter. `ENV{key}` Set a device property value. Property names with a leading `.` are neither stored in the database nor exported to events or external tools (run by, for example, the `PROGRAM` match key). `TAG` Attach a tag to a device. This is used to filter events for users of libudev's monitor functionality, or to enumerate a group of tagged devices. The implementation can only work efficiently if only a few tags are attached to a device. It is only meant to be used in contexts with specific device filter requirements, and not as a general-purpose flag. Excessive use might result in inefficient event handling. `RUN{type}` Specify a program to be executed after processing of all the rules for the event. With `+=`, this invocation is added to the list, and with `=` or `:=`, it replaces any previous contents of the list. Please note that both `program` and `builtin` types described below share a common list, so clearing the list with `:=` and `=` affects both types. \ may be: `program` Execute an external program specified as the assigned value. If no absolute path is given, the program is expected to live in `/usr/lib/udev`; otherwise, the absolute path must be specified. This is the default if no \ is specified. `builtin` As `program`, but use one of the built-in programs rather than an external one. The program name and following arguments are separated by spaces. Single quotes can be used to specify arguments with spaces. This can only be used for very short-running foreground tasks. Running an event process for a long period of time may block all further events for this or a dependent device. Note that running programs that access the network or mount/unmount filesystems is not allowed inside of udev rules, due to the default sandbox that is enforced on `systemd-udevd.service`. Starting daemons or other long-running processes is not allowed; the forked processes, detached or not, will be unconditionally killed after the event handling has finished. In order to activate long-running processes from udev rules, provide a service unit and pull it in from a udev device using the `SYSTEMD_WANTS` device property. See `systemd.device(5)` for details. `LABEL` A named label to which a `GOTO` may jump. `GOTO` Jumps to the next `LABEL` with a matching name. `IMPORT{type}` Import a set of variables as device properties, depending on \: `program` Execute an external program specified as the assigned value and, if it returns successfully, import its output, which must be in environment key format. Path specification, command/argument separation, and quoting work like in `RUN`. `builtin` Similar to `program`, but use one of the built-in programs rather than an external one. `file` Import a text file specified as the assigned value, the content of which must be in environment key format. `db` Import a single property specified as the assigned value from the current device database. This works only if the database is already populated by an earlier event. `cmdline` Import a single property from the kernel command line. For simple flags the value of the property is set to `1`. `parent` Import the stored keys from the parent device by reading the database entry of the parent device. The value assigned to `IMPORT{parent}` is used as a filter of key names to import (with the same shell glob pattern matching used for comparisons). This can only be used for very short-running foreground tasks. For details see `RUN`. Note that multiple `IMPORT{}` keys may be specified in one rule, and `=`, `:=`, and `+=` have the same effect as `==`. The key is true if the import is successful, unless `!=` is used as the operator which causes the key to be true if the import failed. `OPTIONS` Rule and device options: `link_priority=value` Specify the priority of the created symlinks. Devices with higher priorities overwrite existing symlinks of other devices. The default is 0. `string_escape=none|replace` When `replace`, possibly unsafe characters in strings assigned to `NAME`, `SYMLINK`, and `ENV{key}` are replaced. When `none`, no replacement is performed. When unset, the replacement is performed for `NAME`, `SYMLINK`, but not for `ENV{key}`. Defaults to unset. `static_node=` Apply the permissions specified in this rule to the static device node with the specified name. Also, for every tag specified in this rule, create a symlink in the directory `/run/udev/static_node-tags/tag` pointing at the static device node with the specified name. Static device node creation is performed by systemd-tmpfiles before systemd-udevd is started. The static nodes might not have a corresponding kernel device; they are used to trigger automatic kernel module loading when they are accessed. `watch` Watch the device node; when the node is closed after being opened for writing, a change uevent is synthesized. `nowatch` Disable the watching of a device node. `db_persist` Set the flag (sticky bit) on the udev database entry of the event device. Device properties are then kept in the database even when `udevadm info --cleanup-db` is called. This option can be useful in certain cases (e.g. Device Mapper devices) for persisting device state on the transition from initrd. `log_level=level` Takes a log level name like `debug` or `info`, or a special value `reset`. When a log level name is specified, the maximum log level is changed to that level. When `reset` is set, then the previously specified log level is revoked. Defaults to the log level of the main process of `systemd-udevd`. This may be useful when debugging events for certain devices. Note that the log level is applied when the line including this rule is processed. So, for debugging, it is recommended that this is specified at earlier place, e.g., the first line of `00-debug.rules`. Example for debugging uevent processing for network interfaces: # /etc/udev/rules.d/00-debug-net.rules SUBSYSTEM=="net", OPTIONS="log_level=debug" `dump` Dump the status of the event currently processing. It may be useful for debugging udev rules by inserting this option. `dump-json` Similar to `dump`, but dump the status of the event in JSON format. The `ENV`, `GROUP`, `MODE`, `NAME`, `OWNER`, `PROGRAM`, `RUN`, `SECLABEL`, and `SYMLINK` fields support simple string substitutions. The `RUN` substitutions are performed after all rules have been processed, right before the program is executed, allowing for the use of device properties set by earlier matching rules. For all other fields, substitutions are performed while the individual rule is being processed. The available substitutions are: `$kernel`, `%k` The kernel name for this device. `$number`, `%n` The kernel number for this device. For example, `sda3` has kernel number 3. `$devpath`, `%p` The devpath of the device. `$id`, `%b` The name of the device matched while searching the devpath upwards for `SUBSYSTEMS`, `KERNELS`, `DRIVERS`, and `ATTRS`. `$driver` The driver name of the device matched while searching the devpath upwards for `SUBSYSTEMS`, `KERNELS`, `DRIVERS`, and `ATTRS`. `$attr{file}`, `%s{file}` The value of a sysfs attribute found at the device where all keys of the rule have matched. If the matching device does not have such an attribute, and a previous `KERNELS`, `SUBSYSTEMS`, `DRIVERS`, or `ATTRS` test selected a parent device, then the attribute from that parent device is used. If the attribute is a symlink, the last element of the symlink target is returned as the value. `$env{key}`, `%E{key}` A device property value. `$major`, `%M` The kernel major number for the device. `$minor`, `%m` The kernel minor number for the device. `$result`, `%c` The string returned by the external program requested with `PROGRAM`. A single part of the string, separated by a space character, may be selected by specifying the part number as an attribute: `%c{N}`. If the number is followed by the `+` character, this part plus all remaining parts of the result string are substituted: `%c{N+}`. `$parent`, `%P` The node name of the parent device. `$name` The current name of the device. If not changed by a rule, it is the name of the kernel device. `$links` A space-separated list of the current symlinks. The value is only set during a remove event or if an earlier rule assigned a value. `$root`, `%r` The udev_root value. `$sys`, `%S` The sysfs mount point. `$devnode`, `%N` The name of the device node. `%%` The `%` character itself. `$$` The `$` character itself. # See Also `systemd-udevd.service(8)`, `udevadm(8)`, `systemd.link(5)` # udev_device_get_syspath systemd udev_device_get_syspath 3 udev_device_get_syspath udev_device_get_sysname udev_device_get_sysnum udev_device_get_devpath udev_device_get_devnode udev_device_get_devnum udev_device_get_devtype udev_device_get_subsystem udev_device_get_driver udev_device_get_udev udev_device_get_parent udev_device_get_parent_with_subsystem_devtype udev_device_get_is_initialized udev_device_get_action Query device properties \#include \ const char \* udev_device_get_syspath struct udev_device \* udev_device const char \* udev_device_get_sysname struct udev_device \* udev_device const char \* udev_device_get_sysnum struct udev_device \* udev_device const char \* udev_device_get_devpath struct udev_device \* udev_device const char \* udev_device_get_devnode struct udev_device \* udev_device dev_t udev_device_get_devnum struct udev_device \* udev_device const char \* udev_device_get_devtype struct udev_device \* udev_device const char \* udev_device_get_subsystem struct udev_device \* udev_device const char \* udev_device_get_driver struct udev_device \* udev_device struct udev \* udev_device_get_udev struct udev_device \* udev_device struct udev_device \* udev_device_get_parent struct udev_device \* udev_device struct udev_device \* udev_device_get_parent_with_subsystem_devtype struct udev_device \* udev_device const char \* subsystem const char \* devtype int udev_device_get_is_initialized struct udev_device \* udev_device const char \* udev_device_get_action struct udev_device \* udev_device # Return Value On success, `udev_device_get_syspath()`, `udev_device_get_sysname()`, `udev_device_get_sysnum()`, `udev_device_get_devpath()`, `udev_device_get_devnode()`, `udev_device_get_devtype()`, `udev_device_get_subsystem()`, `udev_device_get_driver()` and `udev_device_get_action()` return a pointer to a constant string that describes the requested property. The lifetime of this string is bound to the device it was requested on. On failure, each function may return `NULL`. On success, `udev_device_get_devnum()` returns the device type of the passed device. On failure, a device type with minor and major number set to `0` is returned. `udev_device_get_udev()` always returns a valid pointer to the udev context that this device belongs to. On success, `udev_device_get_parent()` and `udev_device_get_parent_with_subsystem_devtype()` return a pointer to the parent device. No additional reference to this device is acquired, but the child device owns a reference to such a parent device. On failure, `NULL` is returned. On success, `udev_device_get_is_initialized()` returns either `1` or `0`, depending on whether the passed device has already been initialized by udev or not. On failure, a negative error code is returned. Note that devices for which no udev rules are defined are never reported initialized. # History `udev_device_get_syspath()`, `udev_device_get_sysname()`, `udev_device_get_sysnum()`, `udev_device_get_devpath()`, `udev_device_get_devnode()`, `udev_device_get_devnum()`, `udev_device_get_devtype()`, `udev_device_get_subsystem()`, `udev_device_get_driver()`, `udev_device_get_udev()`, `udev_device_get_parent()`, `udev_device_get_parent_with_subsystem_devtype()`, `udev_device_get_is_initialized()`, and `udev_device_get_action()` were added in version 221. # See Also `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_device_has_tag(3)`, `udev_enumerate_new(3)`, `udev_monitor_new_from_netlink(3)`, `udev_list_entry(3)`, `systemd(1)` # udev_device_has_tag systemd udev_device_has_tag 3 udev_device_has_tag udev_device_has_current_tag udev_device_get_devlinks_list_entry udev_device_get_properties_list_entry udev_device_get_tags_list_entry udev_device_get_current_tags_list_entry udev_device_get_sysattr_list_entry udev_device_get_property_value udev_device_get_sysattr_value udev_device_set_sysattr_value Retrieve or set device attributes \#include \ int udev_device_has_tag struct udev_device \* udev_device const char \* tag int udev_device_has_current_tag struct udev_device \* udev_device const char \* tag struct udev_list_entry \* udev_device_get_devlinks_list_entry struct udev_device \* udev_device struct udev_list_entry \* udev_device_get_properties_list_entry struct udev_device \* udev_device struct udev_list_entry \* udev_device_get_tags_list_entry struct udev_device \* udev_device struct udev_list_entry \* udev_device_get_current_tags_list_entry struct udev_device \* udev_device struct udev_list_entry \* udev_device_get_sysattr_list_entry struct udev_device \* udev_device const char \* udev_device_get_property_value struct udev_device \* udev_device const char \* key const char \* udev_device_get_sysattr_value struct udev_device \* udev_device const char \* sysattr int udev_device_set_sysattr_value struct udev_device \* udev_device const char \* sysattr const char \* value # Description `udev_device_has_tag()` returns a value larger than zero if the specified device object has the indicated tag assigned to it, and zero otherwise. See `udev(7)` for details on the tags concept. `udev_device_has_current_tag()` executes a similar check, however only determines whether the indicated tag was set as result of the most recent event seen for the device. Tags are "sticky", i.e. once set for a device they remain on the device until the device is unplugged, even if the rules run for later events of the same device do not set them anymore. Any tag for which `udev_device_has_current_tag()` returns true will hence also return true when passed to `udev_device_has_tag()`, but the opposite might not be true, in case a tag is no longer configured by the rules applied to the most recent device even. `udev_device_get_tags_list_entry()` returns a udev_list_entry object, encapsulating a list of tags set for the specified device. Similar, `udev_device_get_current_tags_list_entry()` returns a list of tags set for the specified device as effect of the most recent device event seen (see above for details on the difference). # Return Value On success, `udev_device_has_tag()` and `udev_device_has_current_tag()` return positive or `0`, depending on whether the device has the given tag or not. On failure, a negative error code is returned. On success, `udev_device_get_devlinks_list_entry()`, `udev_device_get_properties_list_entry()`, `udev_device_get_tags_list_entry()`, `udev_device_get_current_tags_list_entry()` and `udev_device_get_sysattr_list_entry()` return a pointer to the first entry of the retrieved list. If that list is empty, or if an error occurred, `NULL` is returned. On success, `udev_device_get_property_value()` and `udev_device_get_sysattr_value()` return a pointer to a constant string of the requested value. On error, `NULL` is returned. Attributes that may contain `NUL` bytes should not be retrieved with `udev_device_get_sysattr_value()`; instead, read them directly from the files within the device's syspath. On success, `udev_device_set_sysattr_value()` returns an integer greater than, or equal to, `0`. On failure, a negative error code is returned. Values that contain `NUL` bytes should not be set with this function; instead, write them directly to the files within the device's syspath. # History `udev_device_get_devlinks_list_entry()`, `udev_device_get_properties_list_entry()`, `udev_device_get_tags_list_entry()`, `udev_device_get_sysattr_list_entry()`, `udev_device_get_property_value()`, `udev_device_has_tag()`, `udev_device_get_sysattr_value()`, and `udev_device_set_sysattr_value()` were added in version 221. `udev_device_has_current_tag()` and `udev_device_get_current_tags_list_entry()` were added in version 247. # See Also `udev(7)`, `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_device_get_syspath(3)`, `udev_enumerate_new(3)`, `udev_monitor_new_from_netlink(3)`, `udev_list_entry(3)`, `systemd(1)` # udev_device_new_from_syspath systemd udev_device_new_from_syspath 3 udev_device_new_from_syspath udev_device_new_from_devnum udev_device_new_from_subsystem_sysname udev_device_new_from_device_id udev_device_new_from_environment udev_device_ref udev_device_unref Create, acquire and release a udev device object \#include \ struct udev_device \* udev_device_new_from_syspath struct udev \* udev const char \* syspath struct udev_device \* udev_device_new_from_devnum struct udev \* udev char type dev_t devnum struct udev_device \* udev_device_new_from_subsystem_sysname struct udev \* udev const char \* subsystem const char \* sysname struct udev_device \* udev_device_new_from_device_id struct udev \* udev const char \* id struct udev_device \* udev_device_new_from_environment struct udev \* udev struct udev_device \* udev_device_ref struct udev_device \* udev_device struct udev_device \* udev_device_unref struct udev_device \* udev_device # Description `udev_device_new_from_syspath()`, `udev_device_new_from_devnum()`, `udev_device_new_from_subsystem_sysname()`, `udev_device_new_from_device_id()`, and `udev_device_new_from_environment()` allocate a new udev device object and returns a pointer to it. This object is opaque and must not be accessed by the caller via different means than functions provided by libudev. Initially, the reference count of the device is 1. You can acquire further references, and drop gained references via `udev_device_ref()` and `udev_device_unref()`. Once the reference count hits 0, the device object is destroyed and freed. `udev_device_new_from_syspath()`, `udev_device_new_from_devnum()`, `udev_device_new_from_subsystem_sysname()`, and `udev_device_new_from_device_id()` create the device object based on information found in `/sys/`, annotated with properties from the udev-internal device database. A syspath is any subdirectory of `/sys/`, with the restriction that a subdirectory of `/sys/devices` (or a symlink to one) represents a real device and as such must contain a `uevent` file. `udev_device_new_from_devnum()` takes a device type, which can be `b` for block devices or `c` for character devices, as well as a devnum (see `makedev(3)`). `udev_device_new_from_subsystem_sysname()` looks up devices based on the provided subsystem and sysname (see `udev_device_get_subsystem(3)` and `udev_device_get_sysname(3)`) and `udev_device_new_from_device_id()` looks up devices based on the provided device ID, which is a special string in one of the following four forms: | Example | Explanation | |-----------------|------------------------------------------| | `b8:2` | block device major:minor | | `c128:1` | char device major:minor | | `n3` | network device ifindex | | `+sound:card29` | kernel driver core subsystem:device name | Device ID strings `udev_device_new_from_environment()` creates a device from the current environment (see `environ(7)`). Each key-value pair is interpreted in the same way as if it was received in an uevent (see `udev_monitor_receive_device(3)`). The keys `DEVPATH`, `SUBSYSTEM`, `ACTION`, and `SEQNUM` are mandatory. # Return Value On success, `udev_device_new_from_syspath()`, `udev_device_new_from_devnum()`, `udev_device_new_from_subsystem_sysname()`, `udev_device_new_from_device_id()` and `udev_device_new_from_environment()` return a pointer to the allocated udev device. On failure, `NULL` is returned, and `errno` is set appropriately. `udev_device_ref()` returns the argument that it was passed, unmodified. `udev_device_unref()` always returns `NULL`. # History `udev_device_new_from_syspath()`, `udev_device_new_from_devnum()`, `udev_device_new_from_subsystem_sysname()`, `udev_device_new_from_device_id()`, `udev_device_new_from_environment()`, `udev_device_ref()`, and `udev_device_unref()` were added in version 221. # See Also `udev_new(3)`, `udev_device_get_syspath(3)`, `udev_device_has_tag(3)`, `udev_enumerate_new(3)`, `udev_monitor_new_from_netlink(3)`, `udev_list_entry(3)`, `systemd(1)` # udev_enumerate_add_match_subsystem systemd udev_enumerate_add_match_subsystem 3 udev_enumerate_add_match_subsystem udev_enumerate_add_nomatch_subsystem udev_enumerate_add_match_sysattr udev_enumerate_add_nomatch_sysattr udev_enumerate_add_match_property udev_enumerate_add_match_sysname udev_enumerate_add_match_tag udev_enumerate_add_match_parent udev_enumerate_add_match_is_initialized Modify filters \#include \ int udev_enumerate_add_match_subsystem struct udev_enumerate \* udev_enumerate const char \* subsystem int udev_enumerate_add_nomatch_subsystem struct udev_enumerate \* udev_enumerate const char \* subsystem int udev_enumerate_add_match_sysattr struct udev_enumerate \* udev_enumerate const char \* sysattr const char \* value int udev_enumerate_add_nomatch_sysattr struct udev_enumerate \* udev_enumerate const char \* sysattr const char \* value int udev_enumerate_add_match_property struct udev_enumerate \* udev_enumerate const char \* property const char \* value int udev_enumerate_add_match_sysname struct udev_enumerate \* udev_enumerate const char \* sysname int udev_enumerate_add_match_tag struct udev_enumerate \* udev_enumerate const char \* tag int udev_enumerate_add_match_parent struct udev_enumerate \* udev_enumerate struct udev_device \* parent int udev_enumerate_add_match_is_initialized struct udev_enumerate \* udev_enumerate # Return Value On success, `udev_enumerate_add_match_subsystem()`, `udev_enumerate_add_nomatch_subsystem()`, `udev_enumerate_add_match_sysattr()`, `udev_enumerate_add_nomatch_sysattr()`, `udev_enumerate_add_match_property()`, `udev_enumerate_add_match_sysname()`, `udev_enumerate_add_match_tag()`, `udev_enumerate_add_match_parent()` and `udev_enumerate_add_match_is_initialized()` return an integer greater than, or equal to, `0`. # History `udev_enumerate_add_match_subsystem()`, `udev_enumerate_add_nomatch_subsystem()`, `udev_enumerate_add_match_sysattr()`, `udev_enumerate_add_nomatch_sysattr()`, `udev_enumerate_add_match_property()`, `udev_enumerate_add_match_sysname()`, `udev_enumerate_add_match_tag()`, `udev_enumerate_add_match_parent()`, and `udev_enumerate_add_match_is_initialized()` were added in version 221. # See Also `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_enumerate_new(3)`, `udev_enumerate_scan_devices(3)`, `udev_monitor_new_from_netlink(3)`, `udev_list_entry(3)`, `systemd(1)` # udev_enumerate_new systemd udev_enumerate_new 3 udev_enumerate_new udev_enumerate_ref udev_enumerate_unref Create, acquire and release a udev enumerate object \#include \ struct udev_enumerate \* udev_enumerate_new struct udev \* udev struct udev_enumerate \* udev_enumerate_ref struct udev_enumerate \* udev_enumerate struct udev_enumerate \* udev_enumerate_unref struct udev_enumerate \* udev_enumerate # Description `udev_enumerate_new()` creates an enumeration context to scan `/sys/`. `udev_enumerate_ref()` takes a reference of an enumeration context. `udev_enumerate_unref()` drops a reference of an enumeration context. If the refcount reaches zero, all resources of the enumeration context will be released. # Return Value On success, `udev_enumerate_new()` returns a pointer to the allocated enumeration object. On failure, `NULL` is returned. `udev_enumerate_ref()` returns the argument that it was passed, unmodified. `udev_enumerate_unref()` always returns `NULL`. # History `udev_enumerate_new()`, `udev_enumerate_ref()`, and `udev_enumerate_unref()` were added in version 221. # See Also `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_enumerate_add_match_subsystem(3)`, `udev_enumerate_scan_devices(3)`, `udev_monitor_new_from_netlink(3)`, `udev_list_entry(3)`, `systemd(1)` # udev_enumerate_scan_devices systemd udev_enumerate_scan_devices 3 udev_enumerate_scan_devices udev_enumerate_scan_subsystems udev_enumerate_get_list_entry udev_enumerate_add_syspath udev_enumerate_get_udev Query or modify a udev enumerate object \#include \ int udev_enumerate_scan_devices struct udev_enumerate \* udev_enumerate int udev_enumerate_scan_subsystems struct udev_enumerate \* udev_enumerate struct udev_list_entry \* udev_enumerate_get_list_entry struct udev_enumerate \* udev_enumerate int udev_enumerate_add_syspath struct udev_enumerate \* udev_enumerate const char \* syspath struct udev \* udev_enumerate_get_udev struct udev_enumerate \* udev_enumerate # Return Value On success, `udev_enumerate_scan_devices()`, `udev_enumerate_scan_subsystems()` and `udev_enumerate_add_syspath()` return an integer greater than, or equal to, `0`. On success, `udev_enumerate_get_list_entry()` returns a pointer to the first entry in the list of found devices. If the list is empty, or on failure, `NULL` is returned. `udev_enumerate_get_udev()` always returns a pointer to the udev context that this enumerated object is associated with. # History `udev_enumerate_scan_devices()`, `udev_enumerate_scan_subsystems()`, `udev_enumerate_get_list_entry()`, `udev_enumerate_add_syspath()`, and `udev_enumerate_get_udev()` were added in version 221. # See Also `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_enumerate_new(3)`, `udev_enumerate_add_match_subsystem(3)`, `udev_monitor_new_from_netlink(3)`, `udev_list_entry(3)`, `systemd(1)` # udev_list_entry systemd udev_list_entry 3 udev_list_entry udev_list_entry_get_next udev_list_entry_get_by_name udev_list_entry_get_name udev_list_entry_get_value Iterate and access udev lists \#include \ struct udev_list_entry \* udev_list_entry_get_next struct udev_list_entry \* list_entry struct udev_list_entry \* udev_list_entry_get_by_name struct udev_list_entry \* list_entry const char \* name const char \* udev_list_entry_get_name struct udev_list_entry \* list_entry const char \* udev_list_entry_get_value struct udev_list_entry \* list_entry # Return Value On success, `udev_list_entry_get_next()` and `udev_list_entry_get_by_name()` return a pointer to the requested list entry. If no such entry can be found, or on failure, `NULL` is returned. On success, `udev_list_entry_get_name()` and `udev_list_entry_get_value()` return a pointer to a constant string representing the requested value. The string is bound to the lifetime of the list entry itself. On failure, `NULL` is returned. # History `udev_list_entry_get_next()`, `udev_list_entry_get_by_name()`, `udev_list_entry_get_name()`, and `udev_list_entry_get_value()` were added in version 221. # See Also `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_enumerate_new(3)`, `udev_monitor_new_from_netlink(3)`, `systemd(1)` # udev_monitor_filter_update systemd udev_monitor_filter_update 3 udev_monitor_filter_update udev_monitor_filter_remove udev_monitor_filter_add_match_subsystem_devtype udev_monitor_filter_add_match_tag Modify filters \#include \ int udev_monitor_filter_update struct udev_monitor \* udev_monitor int udev_monitor_filter_remove struct udev_monitor \* udev_monitor int udev_monitor_filter_add_match_subsystem_devtype struct udev_monitor \* udev_monitor const char \* subsystem const char \* devtype int udev_monitor_filter_add_match_tag struct udev_monitor \* udev_monitor const char \* tag # Return Value On success, `udev_monitor_filter_update()`, `udev_monitor_filter_remove()`, `udev_monitor_filter_add_match_subsystem_devtype()` and `udev_monitor_filter_add_match_tag()` return an integer greater than, or equal to, `0`. On failure, a negative error code is returned. # History `udev_monitor_filter_update()`, `udev_monitor_filter_remove()`, `udev_monitor_filter_add_match_subsystem_devtype()`, and `udev_monitor_filter_add_match_tag()` were added in version 221. # See Also `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_enumerate_new(3)`, `udev_monitor_new_from_netlink(3)`, `udev_monitor_receive_device(3)`, `udev_list_entry(3)`, `systemd(1)` # udev_monitor_new_from_netlink systemd udev_monitor_new_from_netlink 3 udev_monitor_new_from_netlink udev_monitor_ref udev_monitor_unref Create, acquire and release a udev monitor object \#include \ struct udev_monitor \* udev_monitor_new_from_netlink struct udev \* udev const char \* name struct udev_monitor \* udev_monitor_ref struct udev_monitor \* udev_monitor struct udev_monitor \* udev_monitor_unref struct udev_monitor \* udev_monitor # Return Value On success, `udev_monitor_new_from_netlink()` returns a pointer to the allocated udev monitor. On failure, `NULL` is returned. `udev_monitor_ref()` returns the argument that it was passed, unmodified. `udev_monitor_unref()` always returns `NULL`. # History `udev_monitor_new_from_netlink()`, `udev_monitor_ref()`, and `udev_monitor_unref()` were added in version 221. # See Also `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_enumerate_new(3)`, `udev_monitor_filter_update(3)`, `udev_monitor_receive_device(3)`, `udev_list_entry(3)`, `systemd(1)` # udev_monitor_receive_device systemd udev_monitor_receive_device 3 udev_monitor_receive_device udev_monitor_enable_receiving udev_monitor_set_receive_buffer_size udev_monitor_get_fd udev_monitor_get_udev Query and modify device monitor \#include \ struct udev_device \* udev_monitor_receive_device struct udev_monitor \* udev_monitor int udev_monitor_enable_receiving struct udev_monitor \* udev_monitor int udev_monitor_set_receive_buffer_size struct udev_monitor \* udev_monitor int size int udev_monitor_get_fd struct udev_monitor \* udev_monitor struct udev \* udev_monitor_get_udev struct udev_monitor \* udev_monitor # Return Value On success, `udev_monitor_receive_device()` returns a pointer to a newly referenced device that was received via the monitor. The caller is responsible to drop this reference when done. On failure, `NULL` is returned. On success, `udev_monitor_enable_receiving()` and `udev_monitor_set_receive_buffer_size()` return an integer greater than, or equal to, `0`. On failure, a negative error code is returned. On success, `udev_monitor_get_fd()` returns the file descriptor used by this monitor. On failure, a negative error code is returned. `udev_monitor_get_udev()` always returns a pointer to the udev context that this monitor is associated with. # History `udev_monitor_receive_device()`, `udev_monitor_enable_receiving()`, `udev_monitor_set_receive_buffer_size()`, `udev_monitor_get_fd()`, and `udev_monitor_get_udev()` were added in version 221. # See Also `udev_new(3)`, `udev_device_new_from_syspath(3)`, `udev_enumerate_new(3)`, `udev_monitor_new_from_netlink(3)`, `udev_monitor_filter_update(3)`, `udev_list_entry(3)`, `systemd(1)` # udev_new systemd udev_new 3 udev_new udev_ref udev_unref Create, acquire and release a udev context object \#include \ struct udev \* udev_new void struct udev \* udev_ref struct udev \* udev struct udev \* udev_unref struct udev \* udev # Description `udev_new()` allocates a new udev context object and returns a pointer to it. This object is opaque and must not be accessed by the caller via different means than functions provided by libudev. Initially, the reference count of the context is 1. You can acquire further references, and drop gained references via `udev_ref()` and `udev_unref()`. Once the reference count hits 0, the context object is destroyed and freed. # Return Value On success, `udev_new()` returns a pointer to the allocated udev context. On failure, `NULL` is returned. `udev_ref()` returns the argument that it was passed, unmodified. `udev_unref()` always returns `NULL`. # History `udev_new()`, `udev_ref()`, and `udev_unref()` were added in version 221. # See Also `systemd(1)`, `systemd-udevd.service(8)` # udevadm systemd udevadm 8 udevadm udev management tool udevadm --debug --version --help udevadm info options devpath \| syspath \| id \| unit udevadm trigger options devpath \| syspath \| id \| unit udevadm settle options udevadm control options udevadm monitor options udevadm test options devpath \| syspath \| id \| unit udevadm test-builtin options command devpath \| syspath \| id \| unit udevadm verify options files udevadm cat options files udevadm wait options devpath \| syspath udevadm lock options command # Description `udevadm` expects a command and command specific options. It controls the runtime behavior of `systemd-udevd`, requests kernel events, manages the event queue, and provides simple debugging mechanisms. # Options `-d`; `--debug` Print debug messages to standard error. This option is implied in `udevadm test` and `udevadm test-builtin` commands. ## udevadm info \[\…\] \[\\|\\|\\|\…\] Query the udev database for device information. Positional arguments should be used to specify one or more devices. Each one may be a device name (in which case it must start with `/dev/`), a sys path (in which case it must start with `/sys/`), a device ID (such as `n1`, `c5:1`, or `b259:1`, see `sd_device_get_device_id(3)`). or a systemd device unit name (in which case it must end with `.device`, see `systemd.device(5)`). `-q`; `--query=TYPE` Query the database for the specified type of device data. Valid \s are: `name`, `symlink`, `path`, `property`, `all`. `--property=NAME` When showing device properties using the `--query=property` option, limit display to properties specified in the argument. The argument should be a comma-separated list of property names. If not specified, all known properties are shown. `--value` When showing device properties using the `--query=property` option, print only their values, and skip the property name and `=`. When showing device symlinks using the `--query=symlink` option, print one path per line instead of separating paths with spaces. An empty line is printed after each device, including the last one. Cannot be used together with `-x/--export` or `-P/--export-prefix`. `-p`; `--path=DEVPATH` The `/sys/` path of the device to query, e.g. `/sys//class/block/sda`. This option is an alternative to the positional argument with a `/sys/` prefix. `udevadm info --path=/class/block/sda` is equivalent to `udevadm info /sys/class/block/sda`. `-n`; `--name=FILE` The name of the device node or a symlink to query, e.g. `/dev//sda`. This option is an alternative to the positional argument with a `/dev/` prefix. `udevadm info --name=sda` is equivalent to `udevadm info /dev/sda`. `-r`; `--root` Print absolute paths in `name` or `symlink` query. `-a`; `--attribute-walk` Print all sysfs properties of the specified device that can be used in udev rules to match the specified device. It prints all devices along the chain, up to the root of sysfs that can be used in udev rules. This switch supports JSON output mode (see `--json=` below). Note that because this switch generates multiple JSON objects, JSON-SEQ mode is automatically enabled (RFC7464). (Note: tools such as [jq](https://jqlang.github.io/jq/manual/) natively support JSON-SEQ via the `--seq` switch.) `-t`; `--tree` Display a sysfs tree. This recursively iterates through the sysfs hierarchy and displays it in a tree structure. If a path is specified only the subtree below and its parent directories are shown. This will show both device and subsystem items. `-x`; `--export` Print output as key/value pairs. Values are enclosed in single quotes. This takes effects only when `--query=property` or `--device-id-of-file=FILE` is specified. `-P`; `--export-prefix=NAME` Add a prefix to the key name of exported values. This implies `--export`. `-d`; `--device-id-of-file=FILE` Print major/minor numbers of the underlying device, where the file lives on. If this is specified, no positional arguments are accepted. `-e`; `--export-db` Export the content of the udev database. `-c`; `--cleanup-db` Cleanup the udev database. `-wSECONDS`; `--wait-for-initialization=SECONDS` Wait for device to be initialized. If argument \ is not specified, the default is to wait forever. `--subsystem-match=SUBSYSTEM`; `--subsystem-nomatch=SUBSYSTEM` When used with `--export-db`, only show devices of or not of the given subsystem respectively. `--attr-match=FILE[=VALUE]`; `--attr-nomatch=FILE[=VALUE]` When used with `--export-db`, only show devices matching or not matching the given attribute respectively. `--property-match=KEY=VALUE` When used with `--export-db`, only show devices matching the given property and value. `--tag-match=TAG` When used with `--export-db`, only show devices with the given tag. `--sysname-match=NAME` When used with `--export-db`, only show devices with the given `/sys` path. `--name-match=NAME` When used with `--export-db`, only show devices with the given name in `/dev`. `--parent-match=NAME` When used with `--export-db`, only show devices with the given parent device. `--initialized-match`; `--initialized-nomatch` When used with `--export-db`, only show devices that are initialized or not initialized respectively. The generated output shows the current device database entry in a terse format. Each line shown is prefixed with one of the following characters: | Prefix | Meaning | |----|----| | `P:` | Device path in `/sys/` | | `M:` | Device name in `/sys/` (i.e. the last component of `P:`) | | `R:` | Device number in `/sys/` (i.e. the numeric suffix of the last component of `P:`) | | `J:` | Device ID | | `U:` | Kernel subsystem | | `B:` | Driver subsystem | | `T:` | Kernel device type within subsystem | | `D:` | Kernel device node major/minor | | `I:` | Network interface index | | `N:` | Kernel device node name | | `L:` | Device node symlink priority | | `S:` | Device node symlink | | `Q:` | Block device sequence number (DISKSEQ) | | `V:` | Attached driver | | `E:` | Device property | `udevadm info` output prefixes ## udevadm trigger \[\…\] \[\\|\\|\\|\…\] Request device events from the kernel. Primarily used to replay events at system coldplug time. Takes device specifications as positional arguments. See the description of `udevadm info` above. `-v`; `--verbose` Print the list of devices which will be triggered. `-n`; `--dry-run` Do not actually trigger the event. `-q`; `--quiet` Suppress error logging in triggering events. `-t`; `--type=TYPE` Trigger a specific type of devices. Valid types are `all`, `devices`, and `subsystems`. The default value is `devices`. `-c`; `--action=ACTION` Type of event to be triggered. Possible actions are `add`, `remove`, `change`, `move`, `online`, `offline`, `bind`, and `unbind`. Also, the special value `help` can be used to list the possible actions. The default value is `change`. `--prioritized-subsystem=SUBSYSTEM,SUBSYSTEM…` Takes a comma separated list of subsystems. When triggering events for devices, the devices from the specified subsystems and their parents are triggered first. For example, if `--prioritized-subsystem=block,net`, then firstly all block devices and their parents are triggered, in the next all network devices and their parents are triggered, and lastly the other devices are triggered. This option can be specified multiple times, and in that case the lists of the subsystems will be merged. That is, `--prioritized-subsystem=block --prioritized-subsystem=net` is equivalent to `--prioritized-subsystem=block,net`. `-s`; `--subsystem-match=SUBSYSTEM` Trigger events for devices which belong to a matching subsystem. This option supports shell style pattern matching. When this option is specified more than once, then each matching result is ORed, that is, all the devices in each subsystem are triggered. `-S`; `--subsystem-nomatch=SUBSYSTEM` Do not trigger events for devices which belong to a matching subsystem. This option supports shell style pattern matching. When this option is specified more than once, then each matching result is ANDed, that is, devices which do not match all specified subsystems are triggered. `-a`; `--attr-match=ATTRIBUTE=VALUE` Trigger events for devices with a matching sysfs attribute. If a value is specified along with the attribute name, the content of the attribute is matched against the given value using shell style pattern matching. If no value is specified, the existence of the sysfs attribute is checked. When this option is specified multiple times, then each matching result is ANDed, that is, only devices which have all specified attributes are triggered. `-A`; `--attr-nomatch=ATTRIBUTE=VALUE` Do not trigger events for devices with a matching sysfs attribute. If a value is specified along with the attribute name, the content of the attribute is matched against the given value using shell style pattern matching. If no value is specified, the existence of the sysfs attribute is checked. When this option is specified multiple times, then each matching result is ANDed, that is, only devices which have none of the specified attributes are triggered. `-p`; `--property-match=PROPERTY=VALUE` Trigger events for devices with a matching property value. This option supports shell style pattern matching. When this option is specified more than once, then each matching result is ORed, that is, devices which have one of the specified properties are triggered. `-g`; `--tag-match=TAG` Trigger events for devices with a matching tag. When this option is specified multiple times, then each matching result is ANDed, that is, devices which have all specified tags are triggered. `-y`; `--sysname-match=NAME` Trigger events for devices for which the last component (i.e. the filename) of the `/sys/` path matches the specified \. This option supports shell style pattern matching. When this option is specified more than once, then each matching result is ORed, that is, all devices which have any of the specified \ are triggered. `--name-match=NAME` Trigger events for devices with a matching device path. When this option is specified more than once, then each matching result is ORed, that is, all specified devices are triggered. `-b`; `--parent-match=SYSPATH` Trigger events for all children of a given device. When this option is specified more than once, then each matching result is ORed, that is, all children of each specified device are triggered. `--initialized-match`; `--initialized-nomatch` When `--initialized-match` is specified, trigger events for devices that are already initialized by `systemd-udevd`, and skip devices that are not initialized yet. When `--initialized-nomatch` is specified, trigger events for devices that are not initialized by `systemd-udevd` yet, and skip devices that are already initialized. Typically, it is essential that applications which intend to use such a match, make sure a suitable udev rule is installed that sets at least one property on devices that shall be matched. See also Initialized Devices section below for more details. > [!WARNING] > `--initialized-nomatch` can potentially save a significant amount of time compared to re-triggering all devices in the system and e.g. can be used to optimize boot time. However, this is not safe to be used in a boot sequence in general. Especially, when udev rules for a device depend on its parent devices (e.g. `ATTRS` or `IMPORT{parent}` keys, see `udev(7)` for more details), the final state of the device becomes easily unstable with this option. `--include-parents` Trigger parent devices of found devices even if the parents will not match the filter condition. This is useful if we are interested to limit the coldplug activities to some devices or subsystems. `-w`; `--settle` Apart from triggering events, also waits for those events to finish. Note that this is different from calling `udevadm settle`. `udevadm settle` waits for all events to finish. This option only waits for events triggered by the same command to finish. `--uuid` Trigger the synthetic device events, and associate a randomized UUID with each. These UUIDs are printed to standard output, one line for each event. These UUIDs are included in the uevent environment block (in the `SYNTH_UUID=` property) and may be used to track delivery of the generated events. `--wait-daemon[=SECONDS]` Before triggering uevents, wait for systemd-udevd daemon to be initialized. Optionally takes timeout value. Default timeout is 5 seconds. This is equivalent to invoking `udevadm control --ping` before `udevadm trigger`. In addition, optional positional arguments can be used to specify device names or sys paths. They must start with `/dev/` or `/sys/` respectively. ## udevadm settle \[\…\] Watches the udev event queue, and exits if all current events are handled. `-t`; `--timeout=SECONDS` Maximum number of seconds to wait for the event queue to become empty. The default value is 120 seconds. A value of 0 will check if the queue is empty and always return immediately. A non-zero value will return an exit code of 0 if queue became empty before timeout was reached, non-zero otherwise. `-E`; `--exit-if-exists=FILE` Stop waiting if file exists. See `systemd-udev-settle.service(8)` for more information. ## udevadm control \… Modify the internal state of the running udev daemon. `-e`; `--exit` Signal and wait for systemd-udevd to exit. No option except for `--timeout` can be specified after this option. Note that `systemd-udevd.service` contains `Restart=always` and so as a result, this option restarts systemd-udevd. If you want to stop `systemd-udevd.service`, please use the following: systemctl stop systemd-udevd-kernel.socket systemd-udevd-varlink.socket systemd-udevd.service `-l`; `--log-level=value` Set the internal log level of `systemd-udevd`. Valid values are the numerical syslog priorities or their textual representations: `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, and `debug`. `-s`; `--stop-exec-queue` Signal systemd-udevd to stop executing new events. Incoming events will be queued. `-S`; `--start-exec-queue` Signal systemd-udevd to enable the execution of events. `-R`; `--reload` Signal systemd-udevd to reload the rules files and other databases like the kernel module index. Reloading rules and databases does not apply any changes to already existing devices; the new configuration will only be applied to new events. `-p`; `--property=KEY=value` Set a global property for all events. `-m`; `--children-max=value` Set the maximum number of events, systemd-udevd will handle at the same time. When 0 is specified, then the maximum is determined based on the system resources. `--ping` Send a ping message to systemd-udevd and wait for the reply. This may be useful to check that systemd-udevd daemon is running. `--trace=BOOL` Enable/disable trace logging in `systemd-udevd`. `--revert` Revert settings previously set with `udevadm control` command. When specified, settings set with `-l/--log-level=`, `--trace`, `-m/--children-max=`, and `-p/--property=` will be cleared. `-t`; `--timeout=seconds` The maximum number of seconds to wait for a reply from systemd-udevd. `--load-credentials` When specified, the following credentials are used when passed in: `udev.conf.*` These credentials should contain valid `udev.conf(5)` configuration data. From each matching credential a separate file is created. Example: a passed credential `udev.conf.50-foobar` will be copied into a configuration file `/run/udev/udev.conf.d/50-foobar.conf`. `udev.rules.*` These credentials should contain valid `udev(7)` rules. From each matching credential a separate file is created. Example: a passed credential `udev.rules.50-foobar` will be copied into a configuration file `/run/udev/rules.d/50-foobar.rules`. Note, this *does not* imply `--reload` option. So, if `systemd-udevd` is already running, please consider to also specify `-reload` to make the copied udev rules files used by `systemd-udevd`. ## udevadm monitor \[\…\] Listens to the kernel uevents and events sent out by a udev rule and prints the devpath of the event to the console. It can be used to analyze the event timing, by comparing the timestamps of the kernel uevent and the udev event. `-k`; `--kernel` Print the kernel uevents. `-u`; `--udev` Print the udev event after the rule processing. `-p`; `--property` Also print the properties of the event. `-s`; `--subsystem-match=string[/string]` Filter kernel uevents and udev events by subsystem\[/devtype\]. Only events with a matching subsystem value will pass. When this option is specified more than once, then each matching result is ORed, that is, all devices in the specified subsystems are monitored. `-t`; `--tag-match=string` Filter udev events by tag. Only udev events with a given tag attached will pass. When this option is specified more than once, then each matching result is ORed, that is, devices which have one of the specified tags are monitored. ## udevadm test \[\…\] \\|\\|\\|\ Simulate a udev event run for the given device, and print debug output. The option `--json=` may be useful for parsing the final result. See also Example section. `-a`; `--action=ACTION` Type of event to be simulated. Possible actions are `add`, `remove`, `change`, `move`, `online`, `offline`, `bind`, and `unbind`. Also, the special value `help` can be used to list the possible actions. The default value is `add`. `-N`; `--resolve-names=early|late|never` Specify when `udevadm` should resolve names of users and groups specified in udev rules. When set to `early` (the default), names will be resolved when the rules are parsed. When set to `late`, names will be resolved during the event being processed. When set to `never`, names will never be resolved and relevant udev rules will be ignored. `-D DIR`; `--extra-rules-dir=DIR` Also load udev rules files from the specified directory. This option can be specified multiple times. It may be useful for debugging udev rules by copying some udev rules files to a temporary directory, editing them, and specifying the directory with this option. Files found in the specified directories have a higher priority than rules files in the default `udev/rules.d` directories used by `systemd-udevd`. See `udev(7)` for more details about the search paths. `-v`; `--verbose` Shows verbose logs in processing udev rules. ## udevadm test-builtin \[\…\] \ \\|\\|\ Run a built-in command \ for device \, and print debug output. `-a`; `--action=ACTION` Type of event to be simulated. Possible actions are `add`, `remove`, `change`, `move`, `online`, `offline`, `bind`, and `unbind`. Also, the special value `help` can be used to list the possible actions. The default value is `add`. ## udevadm verify \[\…\] \[\…\] Verify syntactic, semantic, and stylistic correctness of udev rules files. Positional arguments can be used to specify one or more files to check. Each argument must be an absolute path to a udev rules file or a directory that contains rules files, or a file name of udev rules file (e.g. `99-systemd.rules`). If a file name is specified, the file will be searched in the `udev/rules.d` directories that are processed by `systemd-udevd`, and searched in the current working directory if not found. If no files are specified, the udev rules are read from the files located in the same `udev/rules.d` directories that are processed by `systemd-udevd`. See `udev(7)` for more details about the search paths. The exit status is `0` if all specified udev rules files are syntactically, semantically, and stylistically correct, and a non-zero error code otherwise. `-N`; `--resolve-names=early|late|never` Specify when `udevadm` should resolve names of users and groups specified in udev rules. When set to `early` (the default), names will be resolved when the rules are parsed. When set to `late`, names will not be verified, as `systemd-udevd` resolves names during each event being processed. When set to `never`, names will never be resolved and relevant rules will be ignored. `--root=PATH` When looking for udev rules files located in the `udev/rules.d` directories, operate on files underneath the specified root path \. When a file name is specified, and it is not found in the `udev/rules.d` directories, the file will be searched in the specified root path \, rather than the current working directory. `--no-summary` Do not show summary. `--no-style` Ignore style issues. When specified, even if style issues are found in udev rules files, the exit status is `0` if no syntactic or semantic errors are found. ## udevadm cat \[\…\] \[\…\] Show udev rules files or udev.conf. Positional arguments can be used to specify one or more files to show. Each argument must be an absolute path to a udev rules file or a directory that contains rules files, or a file name of udev rules file (e.g. `99-systemd.rules`). If a file name is specified, the file will be searched in the `udev/rules.d` directories that are processed by `systemd-udevd`, and searched in the current working directory if not found. If no files are specified, the udev rules are read from the files located in the same `udev/rules.d` directories that are processed by `systemd-udevd`. See `udev(7)` for more details about the search paths. `--root=PATH` When looking for udev rules files located in the `udev/rules.d` directories, operate on files underneath the specified root path \. When a file name is specified, and it is not found in the `udev/rules.d` directories, the file will be searched in the specified root path \, rather than the current working directory. `--tldr` Only print the "interesting" parts of the configuration files, skipping comments and empty lines and section headers followed only by comments and empty lines. `--config` Shows `udev.conf(5)` files, rather than udev rules files. When specified, no udev rules file cannot be specified. ## udevadm wait \[\…\] \… Wait for devices or device symlinks being created and initialized by `systemd-udevd`. Each device path must start with `/dev/` or `/sys/`, e.g. `/dev/sda`, `/dev/disk/by-path/pci-0000:3c:00.0-nvme-1-part1`, `/sys/devices/pci0000:00/0000:00:1f.6/net/eth0`, or `/sys/class/net/eth0`. This can take multiple devices. This may be useful for waiting for devices being processed by `systemd-udevd` after e.g. partitioning or formatting the devices. `-t`; `--timeout=SECONDS` Maximum number of seconds to wait for the specified devices or device symlinks being created, initialized, or removed. The default value is `infinity`. `--initialized=BOOL` Check if `systemd-udevd` initialized devices. Defaults to true. When false, the command only checks if the specified devices exist. Set false to this setting if there is no udev rules for the specified devices, as the devices will never be considered as initialized in that case. See Initialized Devices section below for more details. `--removed` When specified, the command wait for devices being removed instead of created or initialized. If this is specified, `--initialized=` will be ignored. `--settle` When specified, also watches the udev event queue, and wait for all queued events being processed by `systemd-udevd`. ## udevadm lock \[\…\] \… `udevadm lock` takes an (advisory) exclusive lock on a block device (or all specified devices), as per [Locking Block Device Access](https://systemd.io/BLOCK_DEVICE_LOCKING) and invokes a program with the locks taken. When the invoked program exits the locks are automatically released and its return value is propagated as exit code of `udevadm lock`. This tool is in particular useful to ensure that `systemd-udevd.service(8)` does not probe a block device while changes are made to it, for example partitions created or file systems formatted. Note that many tools that interface with block devices natively support taking relevant locks, see for example `sfdisk(8)`'s `--lock` switch. The command expects at least one block device specified via `--device=` or `--backing=`, and a command line to execute as arguments. `--device=DEVICE`; `-d DEVICE` Takes a path to a device node of the device to lock. This switch may be used multiple times (and in combination with `--backing=`) in order to lock multiple devices. If a partition block device node is specified the containing "whole" block device is automatically determined and used for the lock, as per the specification. If multiple devices are specified, they are deduplicated, sorted by the major/minor of their device nodes and then locked in order. This switch must be used at least once, to specify at least one device to lock. (Alternatively, use `--backing=`, see below.) `--backing=PATH`; `-b PATH` If a path to a device node is specified, identical to `--device=`. However, this switch alternatively accepts a path to a regular file or directory, in which case the block device of the file system the file/directory resides on is automatically determined and used as if it was specified with `--device=`. `--timeout=SECS`; `-t SECS` Specifies how long to wait at most until all locks can be taken. Takes a value in seconds, or in the usual supported time units, see `systemd.time(7)`. If specified as zero the lock is attempted and if not successful the invocation will immediately fail. If passed as `infinity` (the default) the invocation will wait indefinitely until the lock can be acquired. If the lock cannot be taken in the specified time the specified command will not be executed and the invocation will fail. `--print`; `-p` Instead of locking the specified devices and executing a command, just print the device paths that would be locked, and execute no command. This command is useful to determine the "whole" block device in case a partition block device is specified. The devices will be sorted by their device node major number as primary ordering key and the minor number as secondary ordering key (i.e. they are shown in the order they'd be locked). Note that the number of lines printed here can be less than the number of `--device=` and `--backing=` switches specified in case these resolve to the same "whole" devices. # Initialized Devices Initialized devices are those for which at least one udev rule already completed execution – for any action but `remove` — that set a property or other device setting (and thus has an entry in the udev device database). Devices are no longer considered initialized if a `remove` action is seen for them (which removes their entry in the udev device database). Note that devices that have no udev rules are never considered initialized, but might still be announced via the sd-device API (or similar). # Example
Format a File System
Take a lock on the backing block device while creating a file system, to ensure that `systemd-udevd` does not probe or announce the new superblock before it is comprehensively written: # udevadm lock --device=/dev/sda1 mkfs.ext4 /dev/sda1
Format a RAID File System
Similar, but take locks on multiple devices at once: # udevadm lock --device=/dev/sda1 --device=/dev/sdb1 mkfs.btrfs /dev/sda1 /dev/sdb1
Copy in a File System
Take a lock on the backing block device while copying in a prepared file system image, to ensure that `systemd-udevd` does not probe or announce the new superblock before it is fully written: # udevadm lock -d /dev/sda1 dd if=fs.raw of=/dev/sda1
Predict Network Interface Renaming
To predict a network interface name, `udevadm test` can be used: $ udevadm test /sys/class/net/wlan0 --json=pretty 2>/dev/null | jq .networkInterface.name "wlp59s0"
Predict Symbolic links of a Device Node
To predict symbolic links to a device node, `udevadm test` can be used: $ udevadm test /dev/nvme0n1p1 --json=pretty 2>/dev/null | jq .node.symlinks [ "/dev/disk/by-diskseq/1-part1", "/dev/disk/by-id/nvme-WDC_PC_SN720_SDAQNTW-512G-1001_192290802247-part1", "/dev/disk/by-id/nvme-WDC_PC_SN720_SDAQNTW-512G-1001_192290802247_1-part1", "/dev/disk/by-id/nvme-eui.1922908022470001001b448b44ccb9d6-part1", "/dev/disk/by-path/pci-0000:3c:00.0-nvme-1-part/by-partnum/1", "/dev/disk/by-path/pci-0000:3c:00.0-nvme-1-part1" ] $ udevadm test /dev/input/event3 --json=pretty 2>/dev/null | jq .node.symlinks [ "/dev/input/by-path/platform-i8042-serio-0-event-kbd" ]
# See Also `udev(7)`, `systemd-udevd.service(8)`, `udev.conf(5)` # ukify systemd ukify 1 ukify Combine components into a signed Unified Kernel Image for UEFI systems ukify OPTIONS build ukify OPTIONS genkey ukify OPTIONS inspect FILE ukify completion SHELL # Description `ukify` is a tool whose primary purpose is to combine components (usually a kernel, an initrd, and the `systemd-stub(7)` UEFI stub) to create a [UAPI.5 Unified Kernel Image (UKI)](https://uapi-group.org/specifications/specs/unified_kernel_image/) — a single PE binary that boots the system. When the UKI is executed, the stub extracts and boots the embedded linux kernel. The UKI can be started directly by the firmware or through a boot loader. When used with [qemu](https://www.qemu.org/docs/master/), a UKI can also be executed through "direct kernel boot", see example below. `ukify` can also be used to generate other types of UKI-like images, in particular extensions. See the description of the `build` verb below. `ukify` can also generate certificates and keys for SecureBoot and PCR signing, see the description of the `genkey` verb below. `ukify` can also print detailed information about unified kernel images, see the description of `inspect` verb below. # Commands The following commands are understood: ## `build` This command creates a Unified Kernel Image. The two primary options that should be specified for the `build` verb are `Linux=`/`--linux=`, and `Initrd=`/`--initrd=`. `Initrd=` accepts multiple whitespace-separated paths and `--initrd=` can be specified multiple times. Additional sections will be inserted into the UKI, either automatically or only if a specific option is provided. See the discussions of `Microcode=`/`--microcode=`, `Cmdline=`/`--cmdline=`, `OSRelease=`/`--os-release=`, `DeviceTree=`/`--devicetree=`, `DeviceTreeAuto=`/`--devicetree-auto=`, `HWIDs=`/`--hwids=`, `Splash=`/`--splash=`, `PCRPKey=`/`--pcrpkey=`, `Uname=`/`--uname=`, `SBAT=`/`--sbat=`, and `--section=` below. `ukify` can also be used to assemble a PE binary that is not executable but contains auxiliary data, for example additional kernel command line entries. If PCR signing keys are provided via the `PCRPrivateKey=`/`--pcr-private-key=` and `PCRPublicKey=`/`--pcr-public-key=` or `PCRCertificate=`/`--pcr-certificate=` options, PCR values that will be seen after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded in the UKI. `systemd-measure(1)` is used to perform this calculation and signing. The calculation of PCR values is done for specific boot phase paths. Those can be specified with the `Phases=`/`--phases=` option. If not specified, the default provided by `systemd-measure` is used. It is also possible to specify the `PCRPrivateKey=`/`--pcr-private-key=`, `PCRPublicKey=`/`--pcr-public-key=` or `PCRCertificate=`/`--pcr-certificate=`, and `Phases=`/`--phases=` arguments more than once. Signatures will then be performed with each of the specified keys. On the command line, when both `--phases=` and `--pcr-private-key=` are used, they must be specified the same number of times, and then the n-th boot phase path set will be signed by the n-th key. This can be used to build different trust policies for different phases of the boot. In the config file, `PCRPrivateKey=`, `PCRPublicKey=`, and `Phases=` are grouped into separate sections, describing separate boot phases. If one of `SigningEngine=`/`--signing-engine=` or `SigningProvider=`/`--signing-provider=` is specified, then the private key arguments will be passed verbatim to `openssl(1)` as URIs, and the public key arguments will be loaded as X.509 certificates, so that signing can be performed with an OpenSSL engine or provider respectively. If a SecureBoot signing key is provided via the `SecureBootPrivateKey=`/`--secureboot-private-key=` option, the resulting PE binary will be signed as a whole, allowing the resulting UKI to be trusted by SecureBoot. Also see the discussion of automatic enrollment in `systemd-boot(7)`. If the stub and/or the kernel contain `.sbat` sections they will be merged in the UKI so that revocation updates affecting either are considered when the UKI is loaded by Shim. For more information on SBAT see [Shim documentation](https://github.com/rhboot/shim/blob/main/SBAT.md). ## `genkey` This command creates the keys for PCR signing and the key and certificate used for SecureBoot signing. The same configuration options that determine what keys and in which paths will be needed for signing when `build` is used, here determine which keys will be created. See the discussion of `PCRPrivateKey=`/`--pcr-private-key=`, `PCRPublicKey=`/`--pcr-public-key=`, and `SecureBootPrivateKey=`/`--secureboot-private-key=` below. The generated certificate's name and lifetime are set with `SecureBootCertificateCommonName=`/`--secureboot-certificate-common-name=` and `SecureBootCertificateValidity=`/`--secureboot-certificate-validity=`. The output files must not exist. ## `inspect` Display information about the sections in a given binary or binaries. If `--all` is given, all sections are shown. Otherwise, if `--section=` option is specified at least once, only those sections are shown. Otherwise, well-known sections that are typically included in an UKI are shown. For each section, its name, size, and sha256-digest is printed. For text sections, the contents are printed. Also see the description of `-j`/`--json=` and `--section=`. Other tools that may be useful for inspect UKIs: `llvm-objdump(1)` `-p` and `pe-inspect`. ## `completion` \ Generate a shell completion script and write it to standard output. The arguments `bash` and `zsh` are supported. # Configuration settings Settings can appear in configuration files (the syntax with `SomeSetting=value`) and on the command line (the syntax with `--some-setting=value`). For some command line parameters, a single-letter shortcut is also allowed. In the configuration files, the setting must be in the appropriate section, so the descriptions are grouped by section below. When the same setting appears in the configuration file and on the command line, generally the command line setting has higher priority and overwrites the config file setting completely. If some setting behaves differently, this is described below. If no config file is provided via the option `--config=PATH`, `ukify` will try to look for a default configuration file in the following paths in this order: `/etc/systemd/ukify.conf`, `/run/systemd/ukify.conf`, `/usr/local/lib/systemd/ukify.conf`, and `/usr/lib/systemd/ukify.conf`, and then load the first one found. `ukify` will proceed normally if no configuration file is specified and no default one is found. The \ and \ positional arguments, or the equivalent `Linux=` and `Initrd=` settings, are optional. If more than one initrd is specified, they will all be combined into a single PE section. This is useful to, for example, prepend microcode before the actual initrd. The following options and settings are understood: ## Command line-only options `--config=PATH` Load configuration from the given config file. In general, settings specified in the config file have lower precedence than the settings specified via options. In cases where the command line option does not fully override the config file setting are explicitly mentioned in the descriptions of individual options. `--measure`; `--no-measure` Enable or disable a call to `systemd-measure(1)` to print pre-calculated PCR values. Defaults to false. `--policy-digest`; `--no-policy-digest` Enable or disable a call to `systemd-measure(1)` to print pre-calculated TPM2 policy digests. Useful for offline signing of PCR policies. Defaults to false. `--section=NAME:TEXT|@PATH`; `--section=NAME:text|binary@PATH` For all verbs except `inspect`, the first syntax is used. Specify an arbitrary additional section `NAME`. The argument may be a literal string, or `@` followed by a path name. This option may be specified more than once. Any sections specified in this fashion will be inserted (in order) before the `.linux` section which is always last. For the `inspect` verb, the second syntax is used. The section \ will be inspected (if found). If the second argument is `text`, the contents will be printed. If the third argument is given, the contents will be saved to the file named \. Note that the name is used as-is, and if the section name should start with a dot, it must be included in \. `--join-profile=PATH` Takes a path to an existing PE file containing an additional profile to add to the unified kernel image. The profile can be generated beforehand with `ukify`. The profile does not need to be signed or contain PCR measurements. All UKI PE sections of the specified PE file are copied into the generated UKI. This is useful for generating multi-profile UKIs. Note that this only copies PE sections that are defined by the UKI specification, and ignores any other, for example `.text` or similar. `--sign-profile=ID` Takes a profile ID for which signed PCR measurements should be generated by ukify. This option can be used together with `--join-profile=` when building the final unified kernel image. If not specified, signed PCR measurements will be added for all profiles. `--join-pcrsig=PATH`; `--pcrsig=TEXT|@PATH` `--join-pcrsig=` takes a path to an existing PE file containing a previously built UKI. `--pcrsig=` takes a path to an existing pcrsig JSON blob, or a verbatim inline blob. They must be used together, and without specifying any other UKI section parameters. `ukify` will attach the pcrsig JSON blob to the UKI. This is useful in combination with `--policy-digest` to create a UKI and then sign the TPM2 policy digests offline. `--tools=DIRS` Specify one or more directories with helper tools. `ukify` will look for helper tools in those directories first, and if not found, try to load them from `$PATH` in the usual fashion. `--output=FILENAME` The output filename. If not specified, the name of the \ argument, with the suffix `.unsigned.efi` or `.signed.efi` will be used, depending on whether signing for SecureBoot was performed. `--summary` Print a summary of loaded config and exit. This is useful to check how the options from the configuration file and the command line are combined. `--all` Print all sections (with `inspect` verb). `--json` Generate JSON output (with `inspect` verb). The output is an object whose keys are the names of the sections shared between all profiles (i.e. those preceding the first `.profile` section), each mapping to an object describing the section by its `size` and `sha256`, plus a `text` field for textual sections. UKI sections that can occur multiple times (in the same profile) are represented as array. If the image contains profiles, an additional `_profiles` key holds an array with one object per profile, each keyed by section name in the same way (starting with its `.profile` section). ## \[UKI\] section `Linux=LINUX`; `--linux=LINUX` A path to the kernel binary. `OSRelease=TEXT|@PATH`; `--os-release=TEXT|@PATH` The os-release description (the `.osrel` section). The argument may be a literal string, or `@` followed by a path name. If not specified, the `os-release(5)` file will be picked up from the host system. If explicitly set to an empty string, the ".osrel" section is omitted from the UKI (this is not recommended in most cases, and causes the resulting artifact to not be recognized as a UKI by other tools like `kernel-install` and `bootctl`). `Cmdline=TEXT|@PATH`; `--cmdline=TEXT|@PATH` The kernel command line (the `.cmdline` section). The argument may be a literal string, or `@` followed by a path name. If not specified, no command line will be embedded. `Initrd=INITRD...`; `--initrd=LINUX` Zero or more initrd paths. In the configuration file, items are separated by whitespace. The initrds are combined in the order of specification, with the initrds specified in the config file first. `Microcode=UCODE`; `--microcode=UCODE` Path to initrd containing microcode updates. If not specified, the section will not be present. `Splash=PATH`; `--splash=PATH` A picture to display during boot (the `.splash` section). The argument is a path to a BMP file. If not specified, the section will not be present. `DeviceTree=PATH`; `--devicetree=PATH` The devicetree description (the `.dtb` section). The argument is a path to a compiled binary DeviceTree file. If not specified, the section will not be present. `DeviceTreeAuto=PATH...`; `--devicetree-auto=PATH` Zero or more automatically selectable DeviceTree files. In the configuration file, items are separated by whitespace. Each DeviceTree will be in a separate `.dtbauto` section. `HWIDs=PATH`; `--hwids=PATH` The hardware ID device table (the `.hwids` section). The argument is a path to a directory with JSON HWID device description files. Each file needs to contain a single JSON object with a `name`, `compatible` and `hwids` keys. The `name` and `compatible` keys must have string values and the `hwids` key must have a list of strings as value, where the strings must be valid UUIDs that represent CHIDs/HWIDs. Example: Here `Example Laptop 16 Gen 7` is the device `name` (as defined by the manufacturer), `example,laptop-16-g7` is the `compatible` (as defined by the kernel) and `hwids` is an array of CHIDs/HWIDs (extracted i.e. from `fwupdtool hwids` output). If not specified, and the `/usr/lib/systemd/boot/hwids/[EFI_ARCH]/` directory exists, then the section will be automatically populated from that directory (specify an empty string as the parameter for this option to disable this behavior), otherwise it will not be present. It is recommended to specify this parameter if automatically selectable DeviceTrees are to be used. `Uname=VERSION`; `--uname=VERSION` Specify the kernel version (as in `uname -r`, the `.uname` section). If not specified, an attempt will be made to extract the version string from the kernel image. It is recommended to pass this explicitly if known, because the extraction is based on heuristics and not very reliable. If not specified and extraction fails, the section will not be present. `SBAT=TEXT|@PATH`; `--sbat=TEXT|@PATH` SBAT metadata associated with the UKI or addon. SBAT policies are useful to revoke whole groups of UKIs or addons with a single, static policy update that does not take space in DBX/MOKX. If not specified manually, a default metadata entry consisting of uki,1,UKI,uki,1,https://uapi-group.org/specifications/specs/unified_kernel_image/ for UKIs and uki-addon,1,UKI Addon,addon,1,https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html for addons will be used, to ensure it is always possible to revoke them. For more information on SBAT see [Shim documentation](https://github.com/rhboot/shim/blob/main/SBAT.md). `PCRPKey=PATH`; `--pcrpkey=PATH` A path to a public key to embed in the `.pcrpkey` section. If not specified, and there's exactly one `PCRPublicKey=`/`--pcr-public-key=` or `PCRCertificate=`/`--pcr-certificate=` argument, that key will be used. Otherwise, the section will not be present. `Profile=PATH`; `--profile=PATH` A path to a UKI profile to place in an `.profile` section. This option is useful for creating multi-profile UKIs, and is typically used in combination with `--join-profile=`, to extend the specified UKI with an additional profile. `PCRBanks=PATH`; `--pcr-banks=PATH` A comma or space-separated list of PCR banks to sign a policy for. If not present, all known banks will be used (`sha1`, `sha256`, `sha384`, `sha512`), which will fail if not supported by the system. `SignInitrdPCRs=BOOL`; `--sign-initrd-pcrs`; `--no-sign-initrd-pcrs` Enable or disable signing of additional PCR policies that are bound to the initrd phase (after `enter-initrd` and before `leave-initrd`) and the `initrd` policy reference. These additional signed policies are consumed by `systemd-tpm2-setup-early.service(8)` to authorize the initialization of NvPCRs. They are also useful for enrolling TPM keyslots to encrypted volumes that can only be unlocked from the initrd with `systemd-cryptenroll(1)`, by using the `--tpm2-public-key-policyref=initrd` option. The extra signatures reuse the first `PCRPrivateKey=`/`--pcr-private-key=`, hence one must be specified, unless `--policy-digest` is used to generate the policies for offline signing. Defaults to false. `SecureBootSigningTool=SIGNER`; `--signtool=SIGNER` Whether to use `sbsign`, `pesign`, or `systemd-sbsign`. Depending on this choice, different parameters are required in order to sign an image. Defaults to `sbsign`. `SecureBootPrivateKey=SB_KEY`; `--secureboot-private-key=SB_KEY` A path to a private key to use for signing of the resulting binary. If the `SigningEngine=`/`--signing-engine=` or `SigningProvider=`/`--signing-provider=` option is used, this may also be an engine or provider specific designation. This option is required by `SecureBootSigningTool=sbsign`/`--signtool=sbsign` and `SecureBootSigningTool=systemd-sbsign`/`--signtool=systemd-sbsign`. `SecureBootCertificate=SB_CERT`; `--secureboot-certificate=SB_CERT` A path to a certificate to use for signing of the resulting binary. If the `SigningEngine=`/`--signing-engine=` or `SigningProvider=`/`--signing-provider=` option is used, this may also be an engine or provider specific designation. This option is required by `SecureBootSigningTool=sbsign`/`--signtool=sbsign` and `SecureBootSigningTool=systemd-sbsign`/`--signtool=systemd-sbsign`. `SecureBootCertificateCommonName=CN`; `--secureboot-certificate-common-name=CN` The common name and issuer name (certificate is self-signed) of a certificate created by `genkey`. Defaults to `SecureBoot signing key on host HOST` with the fully qualified domain name of the machine it runs on. Must not be empty or longer than 64 bytes (X.509 CN limit). `SecureBootCertificateDir=SB_PATH`; `--secureboot-certificate-dir=SB_PATH` A path to a nss certificate database directory to use for signing of the resulting binary. Takes effect when `SecureBootSigningTool=pesign`/`--signtool=pesign` is used. Defaults to `/etc/pki/pesign`. `SecureBootCertificateName=SB_CERTNAME`; `--secureboot-certificate-name=SB_CERTNAME` The name of the nss certificate database entry to use for signing of the resulting binary. This option is required by `SecureBootSigningTool=pesign`/`--signtool=pesign`. `SecureBootCertificateValidity=DAYS`; `--secureboot-certificate-validity=DAYS` Period of validity (in days) for a certificate created by `genkey`. Defaults to 3650, i.e. 10 years. `SigningEngine=ENGINE`; `--signing-engine=ENGINE` An OpenSSL engine to be used for signing the resulting binary and PCR measurements, see `openssl-engine(1)`. `SigningProvider=PROVIDER`; `--signing-provider=PROVIDER` An OpenSSL provider to be used for signing the resulting binary and PCR measurements, see `provider(7)`. This option can only be used when `systemd-sbsign` is used as the signing tool. `CertificateProvider=PROVIDER`; `--certificate-provider=PROVIDER` An OpenSSL provider to be used for loading the certificate used to sign the resulting binary and PCR measurements, see `provider(7)`. This option can only be used when `systemd-sbsign` is used as the signing tool. `SignKernel=BOOL`; `--sign-kernel`; `--no-sign-kernel` Override the detection of whether to sign the Linux binary itself before it is embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is provided via the `SecureBootPrivateKey=`/`--secureboot-private-key=` option and the binary has not already been signed. If `SignKernel=`/`--sign-kernel` is true, and the binary has already been signed, the signature will be appended anyway. ## \[PCRSignature:\\] section In the config file, those options are grouped by section. On the command line, they must be specified in the same order. The sections specified in both sources are combined. `PCRPrivateKey=PATH`; `--pcr-private-key=PATH` A private key to use for signing PCR policies. On the command line, this option may be specified more than once, in which case multiple signatures will be made. `PCRPublicKey=PATH`; `--pcr-public-key=PATH` A public key to use for signing PCR policies. On the command line, this option may be specified more than once, similarly to the `--pcr-private-key=` option. If not present, the public keys will be extracted from the private keys. On the command line, if present, this option must be specified the same number of times as the `--pcr-private-key=` option. Cannot be specified if `--pcr-certificate=` is used. `PCRCertificate=PATH`; `--pcr-certificate=PATH` An X.509 certificate to use for signing PCR policies. On the command line, this option may be specified more than once, similarly to the `--pcr-private-key=` option. If not present, the public keys will be extracted from the private keys. On the command line, if present, this option must be specified the same number of times as the `--pcr-private-key=` option. Cannot be specified if `--pcr-public-key=` is used. `Phases=LIST`; `--phases=LIST` A comma or space-separated list of colon-separated phase paths to sign a policy for. Each set of boot phase paths will be signed with the corresponding private key. If not present, the default of `systemd-measure(1)` will be used. On the command line, when this argument is present, it must appear the same number of times as the `--pcr-private-key=` option. `PolicyRef=STRING`; `--policyref=STRING` A policy reference to bind the generated signature to. The policy reference is an opaque string that is included in the data that is signed, and is also incorporated into the authorization policy of any TPM2 resource that is locked against these signatures (via the `TPM2_PolicyAuthorize` assertion). As a result, a signed policy is only accepted for a resource whose authorization policy was created with the same policy reference. Signed policies created with a different policy reference are rejected, even if they are produced with the same signing key. On the command line, when this argument is present, it must appear the same number of times as the `--pcr-private-key=` option. # Examples
Minimal invocation
$ ukify build \ --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ --cmdline='quiet rw' This creates an unsigned UKI `./vmlinuz.unsigned.efi`.
Direct kernel boot in a virtual machine
When using [qemu](https://www.qemu.org/docs/master/) with [OVMF](https://www.linux-kvm.org/downloads/lersek/ovmf-whitepaper-c770f8c.txt) (UEFI Firmware for virtual machines) the `-kernel` switch can be used directly with a UKI. Example: `qemu-kvm -drive if=pflash,format=qcow2,readonly=on,file=/usr/share/edk2/ovmf/OVMF_CODE_4M.qcow2 -kernel ./vmlinuz.unsigned.efi [ ... ]` (The path to the firmware file might need to be adjusted depending on the distribution.) Usually, another `-drive` argument would to be used to attach an actual disk image, but this is not required.
All the bells and whistles
$ ukify build \ --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ --initrd=early_cpio \ --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md uki.author.myimage,1,UKI for System,uki.author.myimage,1,https://uapi-group.org/specifications/specs/unified_kernel_image/' \ --pcr-private-key=tpm2-pcr-initrd-private-key.pem \ --pcr-public-key=tpm2-pcr-initrd-public-key.pem \ --phases='enter-initrd' \ --pcr-private-key=tpm2-pcr-private-key-system.pem \ --pcr-public-key=tpm2-pcr-public-key-system.pem \ --phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \ enter-initrd:leave-initrd:sysinit:ready' \ --pcr-banks=sha384,sha512 \ --secureboot-private-key=secureboot-private-key.pem \ --secureboot-certificate=secureboot-certificate.pem \ --sign-kernel \ --cmdline='quiet rw rhgb' This creates a signed UKI `./vmlinuz.signed.efi`. The initrd section contains two concatenated parts, `early_cpio` and `initramfs-6.0.9-300.fc37.x86_64.img`. The policy embedded in the `.pcrsig` section will be signed for the initrd (the `enter-initrd` phase) with the key `tpm2-pcr-initrd-private-key.pem`, and for the main system (phases `leave-initrd`, `sysinit`, `ready`) with the key `tpm2-pcr-private-key-system.pem`. The Linux binary and the resulting combined image will be signed with the SecureBoot key `secureboot-private-key.pem`.
All the bells and whistles, via a config file
This is the same as the previous example, but this time the configuration is stored in a file: $ cat ukify.conf [UKI] Initrd=early_cpio Cmdline=quiet rw rhgb SecureBootPrivateKey=secureboot-private-key.pem SecureBootCertificate=secureboot-certificate.pem SignKernel=yes PCRBanks=sha384,sha512 [PCRSignature:initrd] PCRPrivateKey=tpm2-pcr-initrd-private-key.pem PCRPublicKey=tpm2-pcr-initrd-public-key.pem Phases=enter-initrd [PCRSignature:system] PCRPrivateKey=tpm2-pcr-private-key-system.pem PCRPublicKey=tpm2-pcr-public-key-system.pem Phases=enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit enter-initrd:leave-initrd:sysinit:ready $ ukify -c ukify.conf build \ --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img One "initrd" (`early_cpio`) is specified in the config file, and the other initrd (`initramfs-6.0.9-300.fc37.x86_64.img`) is specified on the command line. This may be useful for example when the first initrd contains microcode for the CPU and does not need to be updated when the kernel version changes, unlike the actual initrd.
Kernel command line PE addon
ukify build \ --secureboot-private-key=secureboot-private-key.pem \ --secureboot-certificate=secureboot-certificate.pem \ --cmdline='debug' \ --sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md uki-addon.author,1,UKI Addon for System,uki-addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html' --output=debug.addon.efi This creates a signed PE binary that contains the additional kernel command line parameter `debug` with SBAT metadata referring to the owner of the addon.
Decide signing policy, and create certificate and keys
First, let's create a configuration file that specifies what signatures shall be made: # cat >/etc/kernel/uki.conf <
Multi-Profile UKI
First, create a few profiles: $ ukify build \ --profile='TITLE=Base' \ --output=profile0.efi Add a second profile (@1): $ ukify build \ --profile='TITLE=Boot into Storage Target Mode ID=storagetm' \ --cmdline='quiet rw rd.systemd.unit=storage-target-mode.target' \ --output=profile1.efi Add a third profile (@2): $ ukify build \ --profile='TITLE=Factory Reset ID=factory-reset' \ --cmdline='quiet rw systemd.unit=factory-reset.target' \ --output=profile2.efi Then, create a UKI and include all the generated profiles: $ ukify build \ --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ --cmdline='quiet rw' \ --join-profile=profile0.efi \ --join-profile=profile1.efi \ --join-profile=profile2.efi \ --output=base.efi The resulting UKI `base-with-profile-0-1-2.efi` will now contain three profiles.
Offline signing of pcrsig section
First, create a UKI and save the PCR JSON blob: $ ukify build \ --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \ --cmdline='quiet rw' \ --pcr-public-key=tpm2-pcr-initrd-public-key.pem \ --policy-digest \ --sign-initrd-pcrs \ --json=short \ --output=base.efi >base.pcrs Then, sign the PCR digests offline and insert them in the JSON blob: #!/usr/bin/python3 import base64, json, subprocess priv_key = '/home/zbyszek/src/systemd/tpm2-pcr-private.pem' base_file = 'base.pcrs' base = json.load(open(base_file)) for bank,policies in base.items(): for policy in policies: tbs = base64.b16decode(policy['tbs'].upper()) call = subprocess.run(['openssl', 'dgst', '-sha256', '-sign', priv_key], input=tbs, check=True, capture_output=True) sig = base64.b64encode(call.stdout).decode() policy['sig'] = sig print(json.dumps(base)) Finally, attach the updated JSON blob to the UKI: $ ukify build \ --join-pcrsig=base.efi \ --pcrsig=@base.pcrs \ --json=short \ --output=base-signed.efi The resulting UKI `base-signed.efi` will now contain the signed PCR digests.
# See Also `systemd(1)`, `systemd-stub(7)`, `systemd-boot(7)`, `systemd-measure(1)`, `systemd-pcrphase.service(8)` # unit-states # | State | Description | |----|----| | `active` | Started, bound, plugged in, …, depending on the unit type. | | `inactive` | Stopped, unbound, unplugged, …, depending on the unit type. | | `failed` | Similar to `inactive`, but the unit failed in some way (process returned error code on exit, crashed, an operation timed out, or after too many restarts). | | `activating` | Changing from `inactive` to `active`. | | `deactivating` | Changing from `active` to `inactive`. | | `maintenance` | Unit is `inactive` and a maintenance operation is in progress. | | `reloading` | Unit is `active` and it is reloading its configuration. | | `refreshing` | Unit is `active` and a new mount is being activated in its namespace. | Unit ACTIVE states {#table} # updatectl systemd updatectl 1 updatectl Control the system update service updatectl OPTIONS COMMAND TARGET # Description `updatectl` may be used to check for and install system updates managed by `systemd-sysupdated.service(8)`. # Commands The following commands are understood: `list` \[\\[@\\]\] Show information about targets and their versions. When no \ is specified, this command lists all available targets. When a \ is specified without a \, this command lists all known versions of the specified target. If a \ is specified, this command lists all known information about the specific version. See the example below for details of the output. `check` \[\…\] Check if any updates are available for the specified targets. If no targets are specified, all available targets will be checked for updates. See the example below for details of the output. `update` \[\\[@\\]…\] Update the specified targets to the specified versions. If a target is specified without a version, then it will be updated to the latest version. If no targets are specified, then all available targets will be updated to the latest version. `vacuum` \[\…\] Clean up old versions of the specified targets. If no targets are specified, all available targets will be vacuumed. `features` \[\\] When no \ is specified, this command lists all optional features. When a \ is specified, this command lists all known information about that feature. `enable` \…; `disable` \… These commands enable or disable optional features. See `sysupdate.features(5)`. These commands always operate on the host system. By default, these commands will only change the system's configuration by creating or deleting drop-in files; they will not immediately download the enabled features, or clean up after the disabled ones. Enabled features will be downloaded and installed the next time the target is updated, and disabled transfers will be cleaned up the next time the target is updated or vacuumed. Pass `--now` to immediately apply these changes. # Options The following commands are understood: `--reboot` When used with the `update` command, reboots the system after updates finish applying. If any update fails, the system will not reboot. When used with the `enable` or `disable` commands and the `--now` flag, reboots the system after download or clean-up finish applying. `--offline` When used with the `list` command, disables fetching metadata from the network. This makes the `list` command only return information that is available locally (i.e. about versions already installed on the system). `--now` When used with the `enable` command, downloads and installs the enabled features. When used with the `disable` command, deletes all resources downloaded by the disabled features. # Exit status On success, 0 is returned, a non-zero failure code otherwise. # Examples Note that these examples are just here for demonstration purposes, and the output of these commands is free to change. These commands are intended for display to a user. If you'd like machine-readable output, use the `org.freedesktop.sysupdate1(5)` D-Bus API directly.
Output from `list`
$ updatectl list TARGET VERSION PATH host 48 sysupdate.d machine:fedora 38 /var/lib/machines/fedora.raw component:shim 15.7 sysupdate.shim.d $ updatectl list host VERSION STATUS ↻ 50 candidate 49 available ● 48 current 47 available 46 available 45 available [...] × 25 available+obsolete × 24 available+obsolete × 23 available+obsolete [...] $ updatectl list host@49 ↻ Version: 50 State: candidate ChangeLog: https://vendor.com/os/v50.html TYPE PATH PTUUID PTFLAGS SHA256 url-file http://dl.vendor.com/os/uki_50 - - 90f6534282dd720f7a222fa781086990dc9c83e5c7499f085970a8e75e3ac349 url-file http://dl.vendor.com/os/usr_50_981a5b84-a301-c819-f681-3e575fe16f16 981a5b84-a301-c819-f681-3e575fe16f16 - c0596ab1095258ec6f16c7c281a50d71c419a9f587c1ef858cfbbb69fb0a16f3 url-file http://dl.vendor.com/os/verity_50_2f8d0f3b-f80a-6ddc-a556-3722bfbb5b79 2f8d0f3b-f80a-6ddc-a556-3722bfbb5b79 - e1e90a128e038b3a53455e55d1ca717c743aba31fe6b4b4624109df0243c6338 url-file http://dl.vendor.com/os/verity_sig_50 - - ca3d163bab055381827226140568f3bef7eaac187cebd76878e0b63e9e442356
Checking for and installing updates
$ updatectl check TARGET UPDATE host 48 → 50 machine:fedora 38 → 40 $ updatectl update host machine:fedora@39 [...] ✓ host@50 ✓ machine:fedora@39
# See Also `systemd(1)`, `systemd-sysupdate(8)` `systemd-sysupdated.service(8)` `sysupdate.d(5)`, # user-system-options `--user` Talk to the service manager of the calling user, rather than the service manager of the system. `--system` Talk to the service manager of the system. This is the implied default. `-H`; `--host=` Execute the operation remotely. Specify a hostname, or a username and hostname separated by `@`, to connect to. The hostname may optionally be suffixed by a port ssh is listening on, separated by `:`, and then a container name, separated by `/`, which connects directly to a specific container on the specified host. This will use SSH to talk to the remote machine manager instance. Container names may be enumerated with `machinectl -H HOST`. Put IPv6 addresses in brackets. `-M`; `--machine=` Execute operation on a local container. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating `@` character. If the special string `.host` is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user's user bus: `--user --machine=lennart@.host`). If the `@` syntax is not used, the connection is made as root user. If the `@` syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and `.host` are implied. `-C`; `--capsule=` Execute operation on a capsule. Specify a capsule name to connect to. See `capsule@.service(5)` for details about capsules. # user@.service systemd user@.service 5 user@.service user-runtime-dir@.service systemd-user-runtime-dir System units to start the user manager `user@UID.service` `user-runtime-dir@UID.service` `/usr/lib/systemd/systemd-user-runtime-dir` `user-UID.slice` # Description The `systemd(1)` system manager (PID 1) starts user manager instances as `user@UID.service`, with the user's numerical UID used as the instance identifier. These instances use the same executable as the system manager, but running in a mode where it starts a different set of units. Each `systemd --user` instance manages a hierarchy of units specific to that user. See `systemd(1)` for a discussion of units and `systemd.special(7)` for a list of units that form the basis of the unit hierarchies of system and user units. `user@UID.service` is accompanied by the system unit `user-runtime-dir@UID.service`, which creates the user's runtime directory `/run/user/UID` when started, and removes it when it is stopped. It also might apply runtime quota settings on `/tmp/` and/or `/dev/shm/` for the user. `user-runtime-dir@UID.service` executes the `systemd-user-runtime-dir` binary to do the actual work. User processes may be started by the `user@.service` instance, in which case they will be part of that unit in the system hierarchy. They may also be started elsewhere, for example by `sshd(8)` or a display manager like `gdm`, in which case they form a .scope unit (see `systemd.scope(5)`). Both `user@UID.service` and the scope units are collected under the `user-UID.slice`. Individual `user-UID.slice` slices are collected under `user.slice`, see `systemd.special(7)`. # Controlling resources for logged-in users Options that control resources available to logged-in users can be configured at a few different levels. As described in the previous section, `user.slice` contains processes of all users, so any resource limits on that slice apply to all users together. The usual way to configure them would be through drop-ins, e.g. `/etc/systemd/system/user.slice.d/resources.conf`. The processes of a single user are collected under `user-UID.slice`. Resource limits for that user can be configured through drop-ins for that unit, e.g. `/etc/systemd/system/user-1000.slice.d/resources.conf`. If the limits should apply to all users instead, they may be configured through drop-ins for the truncated unit name, `user-.slice`. For example, configuration in `/etc/systemd/system/user-.slice.d/resources.conf` is included in all `user-UID.slice` units, see `systemd.unit(5)` for a discussion of the drop-in mechanism. When a user logs in and a .scope unit is created for the session (see previous section), the creation of the scope may be managed through `pam_systemd(8)`. This PAM module communicates with `systemd-logind(8)` to create the session scope and provide access to hardware resources. Resource limits for the scope may be configured through the PAM module configuration, see `pam_systemd(8)`. Configuring them through the normal unit configuration is also possible, but since the name of the slice unit is generally unpredictable, this is less useful. In general any resources that apply to units may be set for `user@UID.service` and the slice units discussed above, see `systemd.resource-control(5)` for an overview. # Examples
Hierarchy of control groups with two logged in users
$ systemd-cgls Control group /: -.slice ├─user.slice │ ├─user-1000.slice │ │ ├─user@1000.service │ │ │ ├─pulseaudio.service │ │ │ │ └─2386 /usr/bin/pulseaudio --daemonize=no │ │ │ └─gnome-terminal-server.service │ │ │ └─init.scope │ │ │ ├─ 4127 /usr/libexec/gnome-terminal-server │ │ │ └─ 4198 zsh │ │ … │ │ └─session-4.scope │ │ ├─ 1264 gdm-session-worker [pam/gdm-password] │ │ ├─ 2339 /usr/bin/gnome-shell │ │ … │ │ ├─session-19.scope │ │ ├─6497 sshd: zbyszek [priv] │ │ ├─6502 sshd: zbyszek@pts/6 │ │ ├─6509 -zsh │ │ └─6602 systemd-cgls --no-pager │ … │ └─user-1001.slice │ ├─session-20.scope │ │ ├─6675 sshd: guest [priv] │ │ ├─6708 sshd: guest@pts/6 │ │ └─6717 -bash │ └─user@1001.service │ ├─init.scope │ │ ├─6680 /usr/lib/systemd/systemd --user │ │ └─6688 (sd-pam) │ └─sleep.service │ └─6706 /usr/bin/sleep 30 … User with UID 1000 is logged in using `gdm` (`session-4.scope`) and `ssh(1)` (`session-19.scope`), and also has a user manager instance running (`user@1000.service`). User with UID 1001 is logged in using `ssh` (`session-20.scope`) and also has a user manager instance running (`user@1001.service`). Those are all (leaf) system units, and form part of the slice hierarchy, with `user-1000.slice` and `user-1001.slice` below `user.slice`. User units are visible below the `user@.service` instances (`pulseaudio.service`, `gnome-terminal-server.service`, `init.scope`, `sleep.service`).
Default user resource limits
$ systemctl cat user-1000.slice # /usr/lib/systemd/system/user-.slice.d/10-defaults.conf # … [Unit] Description=User Slice of UID %j After=systemd-user-sessions.service [Slice] TasksMax=33% The `user-UID.slice` units by default do not have a unit file. The resource limits are set through a drop-in, which can be easily replaced or extended following standard drop-in mechanisms discussed in the first section.
# See Also `systemd(1)`, `systemd.service(5)`, `systemd.slice(5)`, `systemd.resource-control(5)`, `systemd.exec(5)`, `systemd.special(7)`, `capsule@.service(5)`, `pam(8)` # userdbctl systemd userdbctl 1 userdbctl Inspect users, groups and group memberships userdbctl OPTIONS COMMAND NAME # Description `userdbctl` may be used to inspect user and groups (as well as group memberships) of the system. This client utility inquires user/group information provided by various system services, both operating on JSON user/group records (as defined by the [JSON User Records](https://systemd.io/USER_RECORD) and [JSON Group Records](https://systemd.io/GROUP_RECORD) definitions), and classic UNIX NSS/glibc user and group records. This tool is primarily a client to the [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API), and may also pick up drop-in JSON user and group records from `/etc/userdb/`, `/run/userdb/`, `/run/host/userdb/`, `/usr/lib/userdb/` (see `nss-systemd(8)` for details about drop-in user records). # Options The following options are understood: `--output=MODE` Chooses the output mode. Takes one of `classic`, `friendly`, `table` or `json`. If `classic`, an output very close to the format of `/etc/passwd` or `/etc/group` is generated. If `friendly`, a more comprehensive and user friendly, human-readable output is generated. If `table`, a minimal, tabular output is generated. If `json`, a JSON formatted output is generated. Defaults to `friendly` if a user/group is specified on the command line, `table` otherwise. Note that most output formats do not show all available information. In particular, `classic` and `table` show only the most important fields. Various modes also do not show password hashes. Use `json` to view all fields, including any authentication fields. `--json=FORMAT` Selects JSON output mode (like `--output=json`) and selects the precise display mode. Takes one of `pretty` or `short`. If `pretty`, human-friendly whitespace and newlines are inserted in the output to make the JSON data more readable. If `short`, all superfluous whitespace is suppressed. `--service=SERVICE:SERVICE…`; `-s` \:\ Controls which services to query for users/groups. Takes a list of one or more service names, separated by `:`. See below for a list of well-known service names. If not specified, all available services are queried at once. `--with-nss=BOOL` Controls whether to include classic glibc/NSS user/group lookups in the output. If `--with-nss=no` is used, any attempts to resolve or enumerate users/groups provided only via glibc NSS is suppressed. If `--with-nss=yes` is specified, such users/groups are included in the output (which is the default). `--with-varlink=BOOL` Controls whether to include Varlink user/group lookups in the output, i.e. those done via the [User/Group Record Lookup API via Varlink](https://systemd.io/USER_GROUP_API). If `--with-varlink=no` is used, any attempts to resolve or enumerate users/groups provided only via Varlink are suppressed. If `--with-varlink=yes` is specified, such users/groups are included in the output (which is the default). `--with-dropin=BOOL` Controls whether to include user/group lookups in the output that are defined using drop-in files in `/etc/userdb/`, `/run/userdb/`, `/run/host/userdb/`, `/usr/lib/userdb/`. If `--with-dropin=no` is used, these records are suppressed. If `--with-dropin=yes` is specified, such users/groups are included in the output (which is the default). `--synthesize=BOOL` Controls whether to synthesize records for the root and nobody users/groups if they are not defined otherwise, as well as the user/groups for the "foreign" UID range. By default (or with `yes`), such records are implicitly synthesized if otherwise missing since they have special significance to the OS. When `no`, this synthesizing is turned off. `-N` This option is short for `--with-nss=no` `--synthesize=no`. Use this option to show only records that are natively defined as JSON user or group records, with all NSS/glibc compatibility and all implicit synthesis turned off. `--multiplexer=BOOL` Controls whether to do lookups via the multiplexer service (if specified as true, the default) or do lookups in the client (if specified as false). Using the multiplexer service is typically preferable, since it runs in a locked down sandbox. `--chain` When used with the `ssh-authorized-keys` command, this will allow passing an additional command line after the user name that is chain executed after the lookup completed. This allows chaining multiple tools that show SSH authorized keys. `--fuzzy`; `-z` When used with the `user` or `group` command, do a fuzzy string search. Any specified arguments will be matched against the user name, the real name of the user record, the email address, and other descriptive strings of the user or group record. Moreover, instead of precise matching, a substring match or a match allowing slight deviations in spelling is applied. `--disposition=` When used with the `user` or `group` command, filters by disposition of the record. Takes one of `intrinsic`, `system`, `regular`, `dynamic`, `container`. May be used multiple times, in which case only users matching any of the specified dispositions are shown. `-I`; `-S`; `-R` Shortcuts for `--disposition=intrinsic`, `--disposition=system`, `--disposition=regular`, respectively. `--uid-min=`; `--uid-max=` When used with the `user` or `group` command, filters the output by UID/GID ranges. Takes numeric minimum or maximum UID/GID values, respectively. Shows only records within the specified range. When applied to the `user` command, it matches against UIDs. When applied to the `group` command, matches against GIDs (despite the name of the switch). If unspecified, defaults to 0 (for the minimum) and 4294967294 (for the maximum), i.e. by default, no filtering is applied, as the whole UID/GID range is covered. `--uuid=` When used with the `user` or `group` command, filters the output to the record with the specified UUID. If unspecified, no UUID-based filtering is applied. `--boundaries=` When used with the `user` or `group` command, controls whether to show relevant UID/GID range boundary information in the tabular output. Takes a boolean. Defaults to true. `-B` Shortcut for `--boundaries=no`. `--from-file=PATH`; `-F` When used with the `user` or `group` command, read the user definition in JSON format from the specified file, instead of querying it from the system. If the path is specified as `-`, reads the JSON data from standard input. This is useful to validate and introspect JSON user or group records quickly, and check how they would be interpreted on the local system. # Commands The following commands are understood: `user` \[\…\] List all known users records or show details of one or more specified user records. Use `--output=` to tweak output mode. If used in conjunction with `--from-file=` the user record data is read in JSON format from the specified file instead of querying it from the system. For details see above. `group` \[\…\] List all known group records or show details of one or more specified group records. Use `--output=` to tweak the output mode. If used in conjunction with `--from-file=` the group record data is read in JSON format from the specified file instead of querying it from the system. For details see above. `users-in-group` \[\…\] List users that are members of the specified groups. If no groups are specified, list all user/group memberships defined. Use `--output=` to tweak the output mode. `groups-of-user` \[\…\] Lists groups that the specified users are members of. If no users are specified, lists all user/group memberships defined (in this case, `groups-of-user` and `users-in-group` are equivalent). Use `--output=` to tweak the output mode. `services` List all services currently providing user/group definitions to the system. See below for a list of well-known services providing user information. `ssh-authorized-keys` Show SSH authorized keys for this account. This command is intended to be used to allow the SSH daemon to pick up authorized keys from user records, see below. `load-credentials` When specified, the following credentials are used when passed in: `userdb.user.*`; `userdb.group.*`; `userdb.transient.user.*`; `userdb.transient.group.*` These credentials should contain valid [JSON User](https://systemd.io/USER_RECORD) and [JSON Group](https://systemd.io/GROUP_RECORD) records. For `userdb.user.*` and `userdb.group.*` credentials, records are placed in `/etc/userdb/`, while for `userdb.transient.user.*` and `userdb.transient.group.*` credentials they are placed in `/run/userdb/`. These records implement the interface described in `nss-systemd(8)`. Any passed user records must contain valid UID and GID fields. Any passed group records must contain a GID field (i.e. automatic UID/GID allocation is not supported). For both user and group records, the credential suffix (for `userdb.user.foobar` the suffix is `foobar`) must match the user or group name encoded in the record. # Well-Known Services The `userdbctl services` command will list all currently running services that provide user or group definitions to the system. The following well-known services are shown among this list: `io.systemd.DynamicUser` This service is provided by the system service manager itself (i.e. PID 1) and makes all users (and their groups) synthesized through the `DynamicUser=` setting in service unit files available to the system (see `systemd.exec(5)` for details about this setting). `io.systemd.Home` This service is provided by `systemd-homed.service(8)` and makes all users (and their groups) belonging to home directories managed by that service available to the system. `io.systemd.Machine` This service is provided by `systemd-machined.service(8)` and synthesizes records for all users/groups used by a container that employs user namespacing. `io.systemd.Multiplexer` This service is provided by `systemd-userdbd.service(8)` and multiplexes user/group look-ups to all other running lookup services. This is the primary entry point for user/group record clients, as it simplifies client side implementation substantially, since they can ask a single service for lookups instead of asking all running services in parallel. `userdbctl` uses this service preferably, too, unless `--with-nss=` or `--service=` are used, in which case finer control over the services to talk to is required. `io.systemd.NameServiceSwitch` This service is (also) provided by `systemd-userdbd.service(8)` and converts classic NSS/glibc user and group records to JSON user/group records, providing full backwards compatibility. Use `--with-nss=no` to disable this compatibility, see above. Note that compatibility is actually provided in both directions: `nss-systemd(8)` will automatically synthesize classic NSS/glibc user/group records from all JSON user/group records provided to the system, thus using both APIs is mostly equivalent and provides access to the same data, however the NSS/glibc APIs necessarily expose a more reduced set of fields only. `io.systemd.DropIn` This service is (also) provided by `systemd-userdbd.service(8)` and picks up JSON user/group records from `/etc/userdb/`, `/run/userdb/`, `/run/host/userdb/`, `/usr/lib/userdb/`. Note that `userdbctl` has internal support for NSS-based lookups too. This means that if neither `io.systemd.Multiplexer` nor `io.systemd.NameServiceSwitch` are running, look-ups into the basic user/group databases will still work. # Integration with SSH The `userdbctl` tool may be used to make the list of SSH authorized keys possibly contained in a user record available to the SSH daemon for authentication. For that, configure the following in `sshd_config(5)`: … AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u AuthorizedKeysCommandUser root … Sometimes, it is useful to allow chain invocation of another program to list SSH authorized keys. By using the `--chain` option, such a tool may be chain executed by `userdbctl ssh-authorized-keys` once a lookup completes, regardless of whether an SSH key was found or not. Example: … AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u --chain /usr/bin/othertool %u AuthorizedKeysCommandUser root … The above will first query the userdb database for SSH keys, and then chain execute `/usr/bin/othertool` to also be queried. # Exit status On success, 0 is returned, and a non-zero failure code otherwise. # See Also `systemd(1)`, `systemd-userdbd.service(8)`, `systemd-homed.service(8)`, `nss-systemd(8)`, `getent(1)` # varlinkctl systemd varlinkctl 1 varlinkctl Introspect with and invoke Varlink services varlinkctl OPTIONS info ADDRESS varlinkctl OPTIONS list-interfaces ADDRESS varlinkctl OPTIONS list-methods ADDRESS INTERFACE varlinkctl OPTIONS introspect ADDRESS INTERFACE varlinkctl OPTIONS call ADDRESS METHOD ARGUMENTS varlinkctl OPTIONS --exec call ADDRESS METHOD ARGUMENTS -- CMDLINE varlinkctl OPTIONS serve METHOD CMDLINE varlinkctl OPTIONS list-registry varlinkctl OPTIONS list-sockets varlinkctl OPTIONS validate-idl FILE # Description `varlinkctl` may be used to introspect and invoke [Varlink IPC](https://varlink.org/) services, following the [UAPI.20 Varlink IPC](https://uapi-group.org/specifications/specs/varlink/) specification. Services are referenced by one of the following: - A Varlink service reference starting with the `unix:` string, followed by an absolute `AF_UNIX` socket path, or by `@` and an arbitrary string (the latter for referencing sockets in the abstract namespace). In this case, a stream socket connection is made to the specified socket. - A Varlink service reference starting with the `exec:` string, followed by an absolute path of a binary to execute. In this case, the specified process is forked off locally, with a connected stream socket passed in. - A Varlink service reference starting with the `ssh-unix:` string, followed by an SSH host specification, followed by `:`, followed by an absolute `AF_UNIX` socket path. (This requires OpenSSH 9.4 or newer on the server side, and abstract namespace sockets are not supported.) - A Varlink service reference starting with the `ssh-exec:` string, followed by an SSH host specification, followed by `:`, followed by a command line. In this case, the command is invoked and the Varlink protocol is spoken on the standard input and output of the invoked command. For convenience, these two simpler (redundant) service address syntaxes are also supported: - A file system path to an `AF_UNIX` socket, either absolute (i.e. begins with `/`) or relative (in which case it must begin with `./`). - A file system path to an executable, either absolute or relative (as above, must begin with `/` or `./`, respectively). # Commands The following commands are understood: `info` \ Shows brief information about the specified service, including vendor name and list of implemented interfaces. Expects a service address in one of the formats described above. `list-interfaces` \ Shows a list of interfaces implemented by the specified service. Expects a service address in one of the formats described above. `list-methods` \ \[\\] Shows a list of methods implemented by the specified service. Expects a service address in one of the formats described above as well as one or more interface names. If no interface name is specified, lists all methods of all interfaces implemented by the service, otherwise just the methods in the specified interfaces. If standard output and standard error are connected to a terminal, methods that are marked as experimental are highlighted and suffixed with `(experimental)`. `introspect` \ \[\\] Shows the interface definitions of the specified interfaces provided by the specified service. Expects a service address in one of the formats described above and optionally one or more Varlink interface names. If no interface names are specified, shows all provided interfaces by the service. `call` \ \ \[\\] Calls the specified method of the specified service. Expects a service address in the format described above, a fully qualified Varlink method name, and a JSON arguments object. If the arguments object is not specified, it is read from STDIN instead. To pass an empty list of parameters, specify the empty object `{}`. The reply parameters are written as JSON objects to STDOUT. If standard error is connected to a terminal and `--quiet` is not specified, the interface description is queried first, and a notice is shown if the method is marked as experimental. `serve` \ \ Run a Varlink server that accepts protocol upgrade requests for the specified method and connects the upgraded connection to the standard input and output of the specified command. This can act as a server-side counterpart to `call` `--upgrade`. The listening socket must be passed via socket activation (i.e. the `$LISTEN_FDS` protocol), making this command suitable for use in socket-activated service units. When a client calls the specified method with the upgrade flag, the server sends a reply confirming the upgrade, then forks and executes the given command line with the upgraded connection on its standard input and output. This effectively turns any command that speaks a protocol over standard input/output into a Varlink service, discoverable via the service registry and authenticated via socket credentials. Because each connection is handled by a forked child process, the service unit can apply systemd's sandboxing options (such as `ProtectSystem=`, etc.) and does not operate in the caller's environment. Use `--polkit-action=` to require polkit authorization of the client before the connection is upgraded. `list-registry` Shows a list of Varlink services currently registered in the service registry, plus their entrypoint sockets. (Currently, this simply enumerates the sockets and symlinked sockets in `/run/varlink/registry/`, see below.) `list-sockets` Shows a list of listening `AF_UNIX` stream sockets on the local system that are marked as Varlink entrypoints, along with whether the calling user has write (i.e. connect) access to each of them. A socket is considered a Varlink entrypoint if its inode carries the `user.varlink` extended attribute set to `entrypoint`. Sockets are enumerated via the kernel's `sock_diag` netlink interface, and hence this is not restricted to sockets in `/run/varlink/registry/` (as `list-registry` is), but covers all file-system bound listening Varlink sockets, regardless of their location. This requires kernel support for extended attributes on socket inodes, which is available since Linux 7.0. `validate-idl` \[\\] Reads a Varlink interface definition file, parses and validates it, then outputs it with syntax highlighting. This checks for syntax and internal consistency of the interface. Expects a file name to read the interface definition from. If omitted, reads the interface definition from STDIN. `help` Shows command syntax help. # Options The following options are understood: `--more` When used with `call`: expect multiple method replies. If this flag is set, the method call is sent with the `more` flag set, which tells the service to generate multiple replies, if needed. The command remains running until the service sends a reply message that indicates it is the last in the series (or if the configured timeout is reached, see below). This flag should be set only for method calls that support this mechanism. If this mode is enabled, output is automatically switched to JSON-SEQ mode, so that individual reply objects can be easily discerned. This switch has no effect on the method call timeout applied by default. Regardless of whether `--more` is specified or not, the default timeout will be 45s. Use `--timeout=` (see below) to change or disable the timeout. When invoking a method call that continuously returns updates, it is typically desirable to disable the timeout with `--timeout=infinity`. On the other hand, when invoking a `--more` method call for the purpose of enumerating objects (which likely will complete quickly), it is typically beneficial to leave the timeout logic enabled, for robustness reasons. `-E` A shortcut for `--more --timeout=infinity`. This switch is useful for method calls that implement subscription to a continuous stream of updates. `--collect` This is similar to `--more`, but collects all responses in a JSON array, and prints it, rather than in JSON-SEQ mode. `--oneway` When used with `call`: do not expect a method reply. If this flag is set, the method call is sent with the `oneway` flag set (the command exits immediately after), which tells the service not to generate a reply. `--upgrade` When used with `call`: request a protocol upgrade. The method call is sent with the `upgrade` flag set. The service is expected to send a single reply confirming the upgrade. After the reply, the Varlink protocol is no longer in effect on the connection. If `--exec` is not specified, `varlinkctl` acts as a bidirectional proxy: data read from standard input is forwarded to the upgraded connection, and data received from the connection is written to standard output. If `--exec` is specified, the upgraded connection socket is placed on both standard input and standard output of the invoked process. This is similar to the regular `--exec` behavior (without `--upgrade`), which places the method call reply on standard input. The invoked process can thus simply read from and write to stdin/stdout to communicate over the upgraded protocol. This option may not be combined with `--more`, `--oneway`, `--collect`, `--graceful=`, or `--push-fd=`. `--json=MODE` Selects the JSON output formatting, either `pretty` for nicely indented, colorized output, or `short` for terse output with minimal whitespace and no newlines. Defaults to `short`. `-j` Equivalent to `--json=pretty` when invoked interactively from a terminal. Otherwise, it is equivalent to `--json=short`, in particular when the output is piped to some other program. `--quiet`; `-q` Suppress output of method call replies. `--graceful=` Takes a qualified Varlink error name, i.e. an interface name, suffixed by an error name, separated by a dot, e.g. `org.varlink.service.InvalidParameter`. Ensures that, if a method call fails with the specified error, this will be treated as success, i.e. will cause the `varlinkctl` invocation to exit with a zero exit status. This option may be used more than once in order to treat multiple different errors as successes. `--timeout=` Expects a timeout in seconds as parameter. By default, a timeout of 45s is enforced. To turn off the timeout, specify `infinity` or an empty string. `--exec` Once the method call issued via `call` completed successfully, chainload the specified command line, with the method call output parameters serialized to JSON passed into standard input (and standard output and standard error inherited from the invoking process). Moreover any file descriptors passed back on the underlying communication socket are passed to the invoked process via the usual `$LISTEN_FDS` protocol. This functionality may be used to consume replies that come with associated file descriptors in a reasonable way. Now that if `--exec` is specified the third parameter to `call` is not optional (i.e. the method call parameters). `--push-fd=` Takes a numeric file descriptor number as parameter. May be used to pass a file descriptor along with the method call, if the underlying transport supports this. May be used multiple times to pass multiple file descriptors, retaining the order in which they are specified. The specified file descriptors must be passed to the `varlinkctl` invocation. Optionally, in place of a numeric file descriptor number an absolute or relative file system path (the latter must be prefixed with `./`) may be specified, which is opened in read-only mode. `--polkit-action=ACTION` When used with `serve`: before upgrading a connection, verify via polkit that the client is authorized for the specified polkit action ID. The client's identity is taken from the peer credentials of the connection. Clients running as root or as the same user as the server are always authorized. If authorization is denied, the method call fails with `org.varlink.service.PermissionDenied` and no command is executed. If polkit support is not available, all other clients are denied. `--system`; `--user` Determines whether to query to the per-system or per-user registry when using the `list-registry` command. By default, the per-system registry is queried. # Files & Directories `/run/varlink/registry/` Directory containing `AF_UNIX` entrypoint socket inodes (or symlinks to them) of well-known, public Varlink interfaces on the local system. They are named after the Varlink interface they implement. Use `varlinkctl list-registry` to show the contents of this directory. (Inodes that neither qualify as socket inodes nor as symlinks to them shall be ignored. A future extension might introduce regular files and directories to enhance the registry functionality.) # Examples
Investigating a Service
The following three commands inspect the `io.systemd.Resolve` service implemented by `systemd-resolved.service(8)`, listing general service information and implemented interfaces, and then displaying the interface definition of its primary interface: $ varlinkctl info /run/systemd/resolve/io.systemd.Resolve Vendor: The systemd Project Product: systemd (systemd-resolved) Version: 254 (254-1522-g4790521^) URL: https://systemd.io/ Interfaces: io.systemd io.systemd.Resolve org.varlink.service $ varlinkctl list-interfaces /run/systemd/resolve/io.systemd.Resolve io.systemd io.systemd.Resolve org.varlink.service $ varlinkctl introspect /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve interface io.systemd.Resolve type ResolvedAddress( ifindex: ?int, … (Interface definition has been truncated in the example above, in the interest of brevity.)
Invoking a Method
The following command resolves a hostname via `systemd-resolved.service(8)`'s `ResolveHostname` method call. $ varlinkctl call /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve.ResolveHostname '{"name":"systemd.io","family":2}' -j { "addresses" : [ { "ifindex" : 2, "family" : 2, "address" : [ 185, 199, 111, 153 ] } ], "name" : "systemd.io", "flags" : 1048577 }
Investigating a Service Executable
The following command inspects the `/usr/lib/systemd/systemd-pcrextend` executable and the IPC APIs it provides. It then invokes a method on it: # varlinkctl info /usr/lib/systemd/systemd-pcrextend Vendor: The systemd Project Product: systemd (systemd-pcrextend) Version: 254 (254-1536-g97734fb) URL: https://systemd.io/ Interfaces: io.systemd io.systemd.PCRExtend org.varlink.service # varlinkctl introspect /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend interface io.systemd.PCRExtend method Extend( pcr: int, text: ?string, data: ?string ) -> () # varlinkctl call /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend.Extend '{"pcr":15,"text":"foobar"}' {}
Invoking a method remotely via SSH
The following command acquires a report about the identity of a remote host `somehost` from `systemd-hostnamed.service(8)` by connecting via SSH to the `AF_UNIX` socket the service listens on: # varlinkctl call ssh-unix:somehost:/run/systemd/io.systemd.Hostname io.systemd.Hostname.Describe '{}' To invoke a Varlink service binary directly on the remote host, rather than talking to a service via `AF_UNIX` can be done like this: # varlinkctl call ssh-exec:somehost:systemd-creds org.varlink.service.GetInfo '{}'
Serving a Sandboxed Decompressor via Protocol Upgrade
The following socket and service units expose `xz` decompression as a Varlink service. Clients connect and send compressed data over the upgraded connection, receiving decompressed output in return. # /etc/systemd/system/varlink-decompress-xz.socket [Socket] ListenStream=/run/varlink/registry/com.example.Decompress.XZ [Install] WantedBy=sockets.target # /etc/systemd/system/varlink-decompress-xz.service [Service] ExecStart=varlinkctl serve com.example.Decompress.XZ xz -d DynamicUser=yes PrivateNetwork=yes ProtectSystem=strict ProtectHome=yes NoNewPrivileges=yes SystemCallFilter=~@privileged @resources MemoryMax=256M A client can then decompress data through this service: $ echo "hello" | xz | varlinkctl call --upgrade \ unix:/run/varlink/registry/com.example.Decompress.XZ \ com.example.Decompress.XZ '{}' hello For quick testing without unit files, `systemd-socket-activate` can be used to provide the listening socket: $ systemd-socket-activate -l /tmp/decompress.sock -- varlinkctl serve com.example.Decompress.XZ xz -d & $ echo "hello" | xz | varlinkctl call --upgrade unix:/tmp/decompress.sock com.example.Decompress.XZ '{}' hello
# See Also `busctl(1)`, [Varlink](https://varlink.org/) # veritytab systemd veritytab 5 veritytab Configuration for verity block devices `/etc/veritytab` # Description The `/etc/veritytab` file describes verity protected block devices that are set up during system boot. Empty lines and lines starting with the `#` character are ignored. Each of the remaining lines describes one verity protected block device. Fields are delimited by white space. Each line is in the form volume-name data-device hash-device roothash options The first four fields are mandatory, the remaining one is optional. The first field contains the name of the resulting verity volume; its block device is set up below `/dev/mapper/`. The second field contains a path to the underlying block data device, or a specification of a block device via `UUID=` followed by the \. The third field contains a path to the underlying block hash device, or a specification of a block device via `UUID=` followed by the \. The fourth field is the \ in hexadecimal. If this field is specified as dash, it is attempted to read the root hash from the udev property `ID_DISSECT_PART_ROOTHASH=` (encoded in hexadecimal) of the data device. The fifth field, if present, is a comma-delimited list of options. The following options are recognized: `superblock=BOOL` Use dm-verity with or without permanent on-disk superblock. `format=NUMBER` Specifies the hash version type. Format type `0` is original Chrome OS version. Format type `1` is modern version. `data-block-size=BYTES` Used block size for the data device. (Note kernel supports only page-size as maximum here; Multiples of 512 bytes.) `hash-block-size=BYTES` Used block size for the hash device. (Note kernel supports only page-size as maximum here; Multiples of 512 bytes.) `data-blocks=BLOCKS` Number of blocks of data device used in verification. If not specified, the whole device is used. `hash-offset=BYTES` Offset of hash area/superblock on `hash-device`. (Multiples of 512 bytes.) `salt=HEX` Salt used for format or verification. Format is a hexadecimal string; 256 bytes long maximum; `-` is the special value for empty. `uuid=UUID` Use the provided \ instead of generating new one. The \ must be provided in standard UUID format, e.g. `12345678-1234-1234-1234-123456789abc`. `ignore-corruption`; `restart-on-corruption`; `panic-on-corruption` Defines what to do if a data verity problem is detected (data corruption). Without these options kernel fails the IO operation with I/O error. With `--ignore-corruption` option the corruption is only logged. With `--restart-on-corruption` or `--panic-on-corruption` the kernel is restarted (panicked) immediately. (You have to provide way how to avoid restart loops.) `ignore-zero-blocks` Instruct kernel to not verify blocks that are expected to contain zeroes and always directly return zeroes instead. > [!WARNING] > Use this option only in very specific cases. This option is available since Linux kernel version 4.5. `check-at-most-once` Instruct kernel to verify blocks only the first time they are read from the data device, rather than every time. > [!WARNING] > It provides a reduced level of security because only offline tampering of the data device's content will be detected, not online tampering. This option is available since Linux kernel version 4.17. `hash=HASH` Hash algorithm for dm-verity. This should be the name of the algorithm, like "sha1". For default see `veritysetup --help`. `fec-device=PATH` Use forward error correction (FEC) to recover from corruption if hash verification fails. Use encoding data from the specified device. The fec device argument can be block device or file image. If fec device path does not exist, it will be created as file. Note: block sizes for data and hash devices must match. Also, if the verity data_device is encrypted the fec_device should be too. `fec-offset=BYTES` This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding data. (Aligned on 512 bytes.) `fec-roots=NUM` Number of generator roots. This equals to the number of parity bytes in the encoding data. In RS(M, N) encoding, the number of roots is M-N. M is 255 and M-N is between 2 and 24 (including). `root-hash-signature=PATH|base64:BASE64|auto` A Base64 string encoding the root hash signature prefixed by `base64:`, or an absolute path to a root hash signature file used to verify the root hash (in kernel). If the special string `auto` is specified, the root hash signature is attempted to be read from the udev property `ID_DISSECT_PART_ROOTHASH_SIG=` (in Base64 format) of the data device. This feature requires Linux kernel version 5.4 or more recent. `_netdev` Marks this veritysetup device as requiring network. It will be started after the network is available, similarly to `systemd.mount(5)` units marked with `_netdev`. The service unit to set up this device will be ordered between `remote-fs-pre.target` and `remote-veritysetup.target`, instead of `veritysetup-pre.target` and `veritysetup.target`. Hint: if this device is used for a mount point that is specified in `fstab(5)`, the `_netdev` option should also be used for the mount point. Otherwise, a dependency loop might be created where the mount point will be pulled in by `local-fs.target`, while the service to configure the network is usually only started *after* the local file system has been mounted. `noauto` This device will not be added to `veritysetup.target`. This means that it will not be automatically enabled on boot, unless something else pulls it in. In particular, if the device is used for a mount point, it'll be enabled automatically during boot, unless the mount point itself is also disabled with `noauto`. `nofail` This device will not be a hard dependency of `veritysetup.target`. It'll still be pulled in and started, but the system will not wait for the device to show up and be enabled, and boot will not fail if this is unsuccessful. Note that other units that depend on the enabled device may still fail. In particular, if the device is used for a mount point, the mount point itself also needs to have the `nofail` option, or the boot will fail if the device is not enabled successfully. `x-initrd.attach` Setup this verity protected block device in the initrd, similarly to `systemd.mount(5)` units marked with `x-initrd.mount`. Although it is not necessary to mark the mount entry for the root file system with `x-initrd.mount`, `x-initrd.attach` is still recommended with the verity protected block device containing the root file system as otherwise systemd will attempt to detach the device during the regular system shutdown while it is still in use. With this option the device will still be detached but later after the root file system is unmounted. All other verity protected block devices that contain file systems mounted in the initrd should use this option. `tpm2-measure-nvpcr=` Takes a boolean argument, or an NvPCR name as argument. May be used to enable automatic measurement of the volume name and Verity root hash, as well as the serials and issuers of the certificates used to generate the provided signatures (if any) will be measured. Passing false disables the mechanism. Passing true enables measurement into the `verity` NvPCR. If any other string is specified this selects the NvPCR to measure into by name. At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by `systemd-veritysetup-generator(8)`. # Examples
/etc/veritytab example
Set up two verity protected block devices. One using device blocks, another using files. usr PARTUUID=783e45ae-7aa3-484a-beef-a80ff9c19cbb PARTUUID=21dc1dfe-4c33-8b48-98a9-918a22eb3e37 36e3f740ad502e2c25e2a23d9c7c17bf0fdad2300b7580842d4b7ec1fb0fa263 auto data /etc/data /etc/hash a5ee4b42f70ae1f46a08a7c92c2e0a20672ad2f514792730f5d49d7606ab8fdf auto
# See Also `systemd(1)`, `systemd-veritysetup@.service(8)`, `systemd-veritysetup-generator(8)`, `fstab(5)`, `veritysetup(8)` # version-info # Added in version 183. Added in version 184. Added in version 185. Added in version 186. Added in version 187. Added in version 188. Added in version 189. Added in version 190. Added in version 191. Added in version 192. Added in version 193. Added in version 194. Added in version 195. Added in version 196. Added in version 197. Added in version 198. Added in version 199. Added in version 200. Added in version 201. Added in version 202. Added in version 203. Added in version 204. Added in version 205. Added in version 206. Added in version 207. Added in version 208. Added in version 209. Added in version 210. Added in version 211. Added in version 212. Added in version 213. Added in version 214. Added in version 215. Added in version 216. Added in version 217. Added in version 218. Added in version 219. Added in version 220. Added in version 221. Added in version 222. Added in version 223. Added in version 224. Added in version 225. Added in version 226. Added in version 227. Added in version 228. Added in version 229. Added in version 230. Added in version 231. Added in version 232. Added in version 233. Added in version 234. Added in version 235. Added in version 236. Added in version 237. Added in version 238. Added in version 239. Added in version 240. Added in version 241. Added in version 242. Added in version 243. Added in version 244. Added in version 245. Added in version 246. Added in version 247. Added in version 248. Added in version 249. Added in version 250. Added in version 251. Added in version 252. Added in version 253. Added in version 254. Added in version 255. Added in version 256. Added in version 257. Added in version 258. Added in version 259. Added in version 260. Added in version 261. Added in version 262. Added in version 263. Added in version 264. # vpick # In place of the image path a `.v/` versioned directory may be specified, see `systemd.v(7)` for details. In place of the directory path a `.v/` versioned directory may be specified, see `systemd.v(7)` for details.