systemd-sysext

title: systemd-sysext(8)

summary: Activates System Extension Images

text:
# systemd-sysext(8)

## NAME
systemd-sysext, systemd-sysext.service, systemd-confext, systemd-confext.service - Activates System Extension Images

## SYNOPSIS
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; see "Mutability" below for more information.

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 Discoverable Partitions Specification[1]

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.

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 OS extension images are activated automatically, if the systemd-sysext.service is enabled. Note that this service runs only after the underlying file systems where system extensions may be located have been mounted. This means they are not suitable for shipping resources that are processed by subsystems running in earliest boot. Specifically, OS extension images are not suitable for shipping system services or systemd-sysusers(8) definitions. See the Portable Services[2] page for a simple mechanism for shipping system services in disk images, in a similar fashion to OS extensions. Note the different isolation on these two mechanisms: while system extension directly extend the underlying OS image with additional files that appear in a way very similar to 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. The systemd-sysext.service service is guaranteed to finish start-up before basic.target is reached; i.e. at the time regular services initialize (those which do not use DefaultDependencies=no), the files and directories system extensions provide are available in /usr/ and /opt/ and may be accessed.

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.

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. Note that for the reasons mentioned earlier, Portable Services[2] remain the recommended way to ship system services. 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 if 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.

Added in version 256.

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

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

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

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

list

A brief list of installed extension images is shown. Added in version 248.

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.

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

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

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

--mutable=BOOL|auto|import

Set mutable mode. no

force immutable mode even with write routing directories present. This is the default. Added in version 256.

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

yes

force mutable mode. Write routing directories will be created in /var/lib/extensions.mutable/ if not present. Added in version 256.

import

immutable mode, but with contents of write routing directories in /var/lib/extensions.mutable/ also merged into the host file system. Added in version 256.

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

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

Added in version 256.

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

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

--no-pager

Do not pipe output into a pager.

--no-legend

Do not print the legend, i.e. column headers and the footer with hints.

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

## EXIT STATUS
On success, 0 is returned.

## SEE ALSO
systemd(1), systemd-nspawn(1), systemd-stub(7), importctl(1)

## NOTES
1.

Discoverable Partitions Specification

https://uapi-group.org/specifications/specs/discoverable_partitions_specification

2.

Portable Services

https://systemd.io/PORTABLE_SERVICES


systemd-system-update-generator

package: systemd

title: systemd-system-update-generator(8)

text:
# systemd-system-update-generator(8)

## NAME
systemd-system-update-generator - Generator for redirecting boot to offline update mode

## SYNOPSIS
/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-sysusers

title: systemd-sysusers(8)

summary: Allocate system users and groups

text:
# systemd-sysusers(8)

## NAME
systemd-sysusers, systemd-sysusers.service - Allocate system users and groups

## SYNOPSIS
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 PATH. 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 root path, including config search paths. Added in version 215.

--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 Discoverable Partitions Specification[1]. For further information on supported disk images, see systemd-nspawn(1)'s switch of the same name. Added in version 247.

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

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

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

Added in version 238.

--dry-run

Process the configuration and figure out what entries would be created, but do not actually write anything. Added in version 250.

--inline

Treat each positional argument as a separate configuration line instead of a file name. Added in version 238.

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

--no-pager

Do not pipe output into a pager.

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.

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

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

passwd.shell.user

Specifies the shell binary to use for the specified account when creating it. Added in version 249.

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

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[2], systemd.exec(5), mkpasswd(1)

## NOTES
1.

Discoverable Partitions Specification

https://uapi-group.org/specifications/specs/discoverable_partitions_specification

2.

Users, Groups, UIDs and GIDs on systemd systems

https://systemd.io/UIDS-GIDS


systemd-sysv-generator

title: systemd-sysv-generator(8)

summary: Unit generator for SysV init scripts

text:
# systemd-sysv-generator(8)

## NAME
systemd-sysv-generator - Unit generator for SysV init scripts

## SYNOPSIS
/usr/lib/systemd/system-generators/systemd-sysv-generator

## DESCRIPTION
Note: this component is deprecated and scheduled for removal. Please replace remaining SysV init scripts with native unit files.

systemd-sysv-generator is a generator that creates wrapper .service units for System V init[1] scripts in /etc/init.d/* at boot and when configuration of the system manager is reloaded. This allows systemd(1) to support them similarly to native units.

LSB headers[2] in SysV init scripts are interpreted, and the ordering specified in the header is turned into dependencies between the generated unit and other units. The LSB facilities "$remote_fs", "$network", "$named", "$portmap", "$time" are supported and will be turned into dependencies on specific native systemd targets. See systemd.special(7) for more details.

Note that compatibility is quite comprehensive but not 100%, for more details see Compatibility with SysV[3].

SysV runlevels have corresponding systemd targets (runlevelX.target). The wrapper unit that is generated will be wanted by those targets which correspond to runlevels for which the script is enabled.

systemd does not support SysV scripts as part of early boot, so all wrapper units are ordered after basic.target.

systemd-sysv-generator implements systemd.generator(7).

## SEE ALSO
systemd(1), systemd.service(5), systemd.target(5)

## NOTES
1.

System V init

https://savannah.nongnu.org/projects/sysvinit

2.

LSB headers

http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html

3.

Compatibility with SysV

https://systemd.io/INCOMPATIBILITIES


systemd-timedated.service

title: systemd-timedated.service(8)

summary: Time and date bus mechanism

text:
# systemd-timedated.service(8)

## NAME
systemd-timedated.service, systemd-timedated - Time and date bus mechanism

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

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

Example 2. 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-tmpfiles

title: systemd-tmpfiles(8)

text:
# systemd-tmpfiles(8)

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

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

Added in version 256.

--user

Execute "user" configuration, i.e. tmpfiles.d/ files in user configuration directories. Added in version 236.

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

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

--dry-run

Process the configuration and print what operations would be performed, but do not actually change anything in the file system. Added in version 256.

--prefix=path

Only apply rules with paths that start with the specified prefix. This option can be specified multiple times. Added in version 212.

--exclude-prefix=path

Ignore rules with paths that start with the specified prefix. This option can be specified multiple times. Added in version 207.

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

--root=root

Takes a directory path as an argument. All paths will be prefixed with the given alternate root 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.

Added in version 212.

--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 Discoverable Partitions Specification[1]. For further information on supported disk images, see systemd-nspawn(1)'s switch of the same name. Implies -E.

Added in version 247.

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

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

Added in version 238.

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

--no-pager

Do not pipe output into a pager.

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.

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

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
$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_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_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 [2]). 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. When true, systemd and related utilities will use colors in their output, otherwise the output will be monochrome. Additionally, the variable can take one of the following special values: "16", "256" to restrict the use of colors to the base 16 or 256 ANSI colors, respectively. This can be specified to override the automatic decision based on $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.

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

## NOTES
1.

Discoverable Partitions Specification

https://uapi-group.org/specifications/specs/discoverable_partitions_specification

2.

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


title: systemd-tpm2-generator(8)

text:
# systemd-tpm2-generator(8)

## NAME
systemd-tpm2-generator - Generator for inserting TPM2 synchronization point in the boot process

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

systemd-tpm2-generator implements systemd.generator(7).

## SEE ALSO
systemd(1), systemd.special(7), kernel-command-line(7)


title: systemd-tpm2-setup.service(8)

text:
# systemd-tpm2-setup.service(8)

## NAME
systemd-tpm2-setup.service, systemd-tpm2-setup-early.service, systemd-tpm2-setup - Set up the TPM2 Storage Root Key (SRK) at boot

## SYNOPSIS
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) if it has not been generated yet, and stores it in the TPM.

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

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

## SEE ALSO
systemd(1)


systemd-update-done.service

title: systemd-update-done.service(8)

summary: Mark /etc/ and /var/ fully updated

text:
# systemd-update-done.service(8)

## NAME
systemd-update-done.service, systemd-update-done - Mark /etc/ and /var/ fully updated

## SYNOPSIS
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) of the stamp files /etc/.updated and /var/.updated to the modification time of the /usr/ directory, unless the stamp files are already newer.

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.

## SEE ALSO
systemd(1), systemd.unit(5), touch(1)


systemd-update-utmp.service

title: systemd-update-utmp.service(8)

text:
# systemd-update-utmp.service(8)

## NAME
systemd-update-utmp.service, systemd-update-utmp-runlevel.service, systemd-update-utmp - Write audit and utmp updates at bootup, runlevel changes and shutdown

## SYNOPSIS
systemd-update-utmp.service

systemd-update-utmp-runlevel.service

/usr/lib/systemd/systemd-update-utmp

## DESCRIPTION
systemd-update-utmp-runlevel.service is a service that writes SysV runlevel changes to utmp and wtmp, as well as the audit logs, as they occur. systemd-update-utmp.service does the same for system reboots and shutdown requests.

## SEE ALSO
systemd(1), utmp(5), auditd(8)


systemd-user-sessions.service

title: systemd-user-sessions.service(8)

text:
# systemd-user-sessions.service(8)

## NAME
systemd-user-sessions.service, systemd-user-sessions - Permit user logins after boot, prohibit user logins at shutdown

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

title: systemd-userdbd.service(8)

text:
# systemd-userdbd.service(8)

## NAME
systemd-userdbd.service, systemd-userdbd - JSON User/Group Record Query Multiplexer/NSS Compatibility

## SYNOPSIS
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" extension.

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[1] and JSON Group Record[2] definitions. This service implements the User/Group Record Lookup API via Varlink[3], 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[4] 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)

## NOTES
1.

JSON User Records

https://systemd.io/USER_RECORD

2.

JSON Group Record

https://systemd.io/GROUP_RECORD

3.

User/Group Record Lookup API via Varlink

https://systemd.io/USER_GROUP_API

4.

Varlink

https://varlink.org/


systemd-vconsole-setup.service

title: systemd-vconsole-setup.service(8)

summary: Configure the virtual consoles

text:
# systemd-vconsole-setup.service(8)

## NAME
systemd-vconsole-setup.service, systemd-vconsole-setup - Configure the virtual consoles

## SYNOPSIS
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 TTY 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(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).

Added in version 253.

vconsole.font, vconsole.font_map, vconsole.font_unimap

The console font settings to apply. The matching options in vconsole.conf and on the kernel command line take precedence over these credentials. Added in version 253.

## SEE ALSO
systemd(1), vconsole.conf(5), loadkeys(1), setfont(8), systemd-localed.service(8)


systemd-veritysetup-generator

title: systemd-veritysetup-generator(8)

text:
# systemd-veritysetup-generator(8)

## NAME
systemd-veritysetup-generator - Unit generator for verity protected block devices

## SYNOPSIS
/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. Added in version 233.

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

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

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

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

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

## SEE ALSO
systemd(1), systemd-veritysetup@.service(8), veritysetup(8), systemd-fstab-generator(8)


systemd-veritysetup@.service

title: systemd-veritysetup@.service(8)

summary: Disk verity protection logic

text:
# systemd-veritysetup@.service(8)

## NAME
systemd-veritysetup@.service, systemd-veritysetup - Disk verity protection logic

## SYNOPSIS
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 volume datadevice hashdevice roothash [option...]

Create a block device volume using datadevice and hashdevice as the backing devices. roothash forms the root of the tree of hashes stored on hashdevice. See Kernel dm-verity[1] documentation for details. Added in version 250.

detach volume

Detach (destroy) the block device volume. Added in version 250.

help

Print short information about command syntax. Added in version 250.

## SEE ALSO
systemd(1), systemd-veritysetup-generator(8), veritysetup(8)

## NOTES
1.

Kernel dm-verity

https://docs.kernel.org/admin-guide/device-mapper/verity.html


systemd-volatile-root.service

title: systemd-volatile-root.service(8)

summary: Make the root file system volatile

text:
# systemd-volatile-root.service(8)

## NAME
systemd-volatile-root.service, systemd-volatile-root - Make the root file system volatile

## SYNOPSIS
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-xdg-autostart-generator

title: systemd-xdg-autostart-generator(8)

text:
# systemd-xdg-autostart-generator(8)

## NAME
systemd-xdg-autostart-generator - User unit generator for XDG autostart files

## SYNOPSIS
/usr/lib/systemd/user-generators/systemd-xdg-autostart-generator

## DESCRIPTION
systemd-xdg-autostart-generator is a generator that creates .service units for XDG autostart[1] 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.

Table 1. Special XDG desktop file entries that are processed

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

systemd-xdg-autostart-generator

implements systemd.generator(7).

## SEE ALSO
systemd(1), systemd.service(5), systemd.target(5)

## NOTES
1.

XDG autostart

https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html


telinit

title: telinit(8)

summary: Change SysV runlevel

text:
# telinit(8)

## NAME
telinit - Change SysV runlevel

## SYNOPSIS
telinit [OPTIONS...] {COMMAND}

## DESCRIPTION
telinit may be used to change the SysV system runlevel. Since the concept of SysV runlevels is obsolete the runlevel requests will be transparently translated into systemd unit activation requests.

## OPTIONS
The following options are understood:

--help

Print a short help text and exit.

--no-wall

Do not send wall message before reboot/halt/power-off.

The following commands are understood:

0

Power-off the machine. This is translated into an activation request for poweroff.target and is equivalent to systemctl poweroff.

6

Reboot the machine. This is translated into an activation request for reboot.target and is equivalent to systemctl reboot.

2, 3, 4, 5

Change the SysV runlevel. This is translated into an activation request for runlevel2.target, runlevel3.target, ... and is equivalent to systemctl isolate runlevel2.target, systemctl isolate runlevel3.target, ...

1, s, S

Change into system rescue mode. This is translated into an activation request for rescue.target and is equivalent to systemctl rescue.

q, Q

Reload daemon configuration. This is equivalent to systemctl daemon-reload.

u, U

Serialize state, reexecute daemon and deserialize state again. This is equivalent to systemctl daemon-reexec.

## EXIT STATUS
On success, 0 is returned, a non-zero failure code otherwise.

## NOTES
This is a legacy command available for compatibility only. It should not be used anymore, as the concept of runlevels is obsolete.

## SEE ALSO
systemd(1), systemctl(1), wall(1)


systemd-bless-boot-generator

package: systemd-boot-efi

title: systemd-bless-boot-generator(8)

summary: Pull systemd\-bless\-boot.service into the initial boot transaction when boot counting is in effect

text:
# systemd-bless-boot-generator(8)

## NAME
systemd-bless-boot-generator - Pull systemd-bless-boot.service into the initial boot transaction when boot counting is in effect

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

title: systemd-bless-boot.service(8)

summary: Mark current boot process as successful

text:
# systemd-bless-boot.service(8)

## NAME
systemd-bless-boot.service, systemd-bless-boot - Mark current boot process as successful

## SYNOPSIS
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 Boot Loader Specification[1] 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.)

## 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", 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. This command is implied if no command argument is specified.

Added in version 240.

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

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

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

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.

## SEE ALSO
systemd(1), systemd-boot(7), systemd.special(7)

## NOTES
1.

Boot Loader Specification

https://uapi-group.org/specifications/specs/boot_loader_specification


systemd-boot-random-seed.service

title: systemd-boot-random-seed.service(8)

summary: Refresh boot loader random seed at boot

text:
# systemd-boot-random-seed.service(8)

## NAME
systemd-boot-random-seed.service - Refresh boot loader random seed at boot

## SYNOPSIS
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[1].

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

## NOTES
1.

Boot Loader Interface

https://systemd.io/BOOT_LOADER_INTERFACE


systemd-import-generator

package: systemd-container

title: systemd-import-generator(8)

text:
# systemd-import-generator(8)

## NAME
systemd-import-generator - Generator for automatically downloading disk images at boot

## SYNOPSIS
/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. Added in version 257.

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

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.

Added in version 257.

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.

Added in version 257.

Added in version 257.

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

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

## EXAMPLES
Example 1. 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.

Example 2. 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!

## SEE ALSO
systemd(1), systemd-importd.service(8), kernel-command-line(7), systemd.system-credentials(7), importctl(1)


systemd-importd.service

title: systemd-importd.service(8)

text:
# systemd-importd.service(8)

## NAME
systemd-importd.service, systemd-importd - VM and container image import and export service

## SYNOPSIS
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-machined.service

title: systemd-machined.service(8)

text:
# systemd-machined.service(8)

## NAME
systemd-machined.service, systemd-machined - Virtual machine and container registration manager

## SYNOPSIS
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[1] 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[2]. Also see the New Control Group Interfaces[3].

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[4], 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)

## NOTES
1.

gnome-system-monitor

https://help.gnome.org/users/gnome-system-monitor/

2.

Writing Virtual Machine or Container Managers

https://systemd.io/WRITING_VM_AND_CONTAINER_MANAGERS

3.

New Control Group Interfaces

https://systemd.io/CONTROL_GROUP_INTERFACE

4.

User/Group Record Lookup API via Varlink

https://systemd.io/USER_GROUP_API


systemd-mountfsd.service

title: systemd-mountfsd.service(8)

summary: Disk Image File System Mount Service

text:
# systemd-mountfsd.service(8)

## NAME
systemd-mountfsd.service, systemd-mountfsd - Disk Image File System Mount Service

## SYNOPSIS
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 Discoverable Partitions Specification[1]. 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/ (and related directories) the disk image is considered trusted.

This service provides one Varlink[2] 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)

## NOTES
1.

Discoverable Partitions Specification

https://uapi-group.org/specifications/specs/discoverable_partitions_specification/

2.

Varlink

https://varlink.org/


systemd-nsresourced.service

title: systemd-nsresourced.service(8)

text:
# systemd-nsresourced.service(8)

## NAME
systemd-nsresourced.service, systemd-nsresourced - User Namespace Resource Delegation Service

## SYNOPSIS
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 ensures that user namespaces set up this way can only write to file systems they allocate themselves or that are explicitly allowlisted via systemd-nsresourced.

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

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 service provides API calls to allowlist 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[2] service: io.systemd.NamespaceResource allows registering user namespaces, and assign mounts, cgroups and network interfaces to it.

## SEE ALSO
systemd(1), systemd-mountfsd.service(8), systemd-nspawn(1), systemd.exec(5), systemd-dissect(1), user_namespaces(7)

## NOTES
1.

User/Group Record Lookup API via Varlink

https://systemd.io/USER_GROUP_API

2.

Varlink

https://varlink.org/