view release on metacpan or  search on metacpan

lib/Config/Model/models/Systemd/Common/Exec.pl  view on Meta::CPAN

desired, because it is not possible to nest C<ReadWritePaths>, C<ReadOnlyPaths>,
C<BindPaths>, or C<BindReadOnlyPaths> inside it. For a more flexible option,
see C<TemporaryFileSystem>.

Content in paths listed in C<NoExecPaths> are not executable even if the usual
file access controls would permit this. Nest C<ExecPaths> inside of
C<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 C<ReadWritePaths>, C<ReadOnlyPaths>,
C<InaccessiblePaths>, C<ExecPaths> and
C<NoExecPaths> may be prefixed with C<->, in which case they will be
ignored when they do not exist. If prefixed with C<+> the paths are taken relative to the root
directory of the unit, as configured with C<RootDirectory>/C<RootImage>,
instead of relative to the root directory of the host (see above). When combining C<-> and
C<+> on the same path make sure to specify C<-> first, and C<+>
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 C<ReadWritePaths> and C<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 C<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
C<CapabilityBoundingSet=~CAP_SYS_ADMIN> or C<SystemCallFilter=~@mount>.

Please be extra careful when applying these options to API file systems (a list of them could be
found in C<MountAPIVPS>), since they may be required for basic system functionalities.
Moreover, C</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
',
      'ExecSearchPath' => 'Takes a colon separated list of absolute paths relative to which the executable
used by the C<Exec*=> (e.g. C<ExecStart>,
C<ExecStop>, etc.) properties can be found. C<ExecSearchPath>
overrides C<$PATH> if C<$PATH> is not supplied by the user through
C<Environment>, C<EnvironmentFile> or
C<PassEnvironment>. Assigning an empty string removes previous assignments
and setting C<ExecSearchPath> to a value multiple times will append
to the previous setting.
',
      'ExtensionDirectories' => 'This setting is similar to C<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 C</usr/> and
C</opt/> hierarchies for sysext images and C</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 C<ExtensionDirectories> may be prefixed with C<->,
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 C</usr/lib/extension-release.d/extension-release.IMAGE>
file while each confext directory must carry a C</etc/extension-release.d/extension-release.IMAGE>
file, with the appropriate metadata which matches C<RootImage>/C<RootDirectory>
or the host. See:
L<os-release(5)>.

If a service employs this option with
L<systemd.v(7)>,
and has C<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
L<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.',
      'ExtensionImagePolicy' => 'Takes an image policy string as per
L<systemd.image-policy(7)>
to use when mounting the disk images (DDI) specified in C<RootImage>,
C<MountImage>, C<ExtensionImage>, respectively. If not specified
the following policy string is the default for C<RootImagePolicy> and C<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 C<ExtensionImagePolicy> is:

    root=verity+signed+encrypted+unprotected+absent: \\
    usr=verity+signed+encrypted+unprotected+absent
',
      'ExtensionImages' => 'This setting is similar to C<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 C</usr/> and
C</opt/> hierarchies for sysext images and C</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
C<RootImageOptions> setting described above.

Each mount definition may be prefixed with C<->, 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 C<:>, it needs to be escaped as
C<\\:>. The device node or file system image file needs to follow the same rules as
specified for C<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 C</usr/lib/extension-release.d/extension-release.IMAGE>
file while each confext image must carry a C</etc/extension-release.d/extension-release.IMAGE>
file, with the appropriate metadata which matches C<RootImage>/C<RootDirectory>
or the host. See:
L<os-release(5)>.
To disable the safety check that the extension-release file name matches the image file name, the
C<x-systemd.relax-extension-release-check> mount option may be appended.

If a service employs this option with
L<systemd.v(7)>,
and has C<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
L<systemd.service(5)>
also for details.

When C<DevicePolicy> is set to C<closed> or
C<strict>, or set to C<auto> and C<DeviceAllow> is
set, then this setting adds C</dev/loop-control> with C<rw> mode,
C<block-loop> and C<block-blkext> with C<rwm> mode
to C<DeviceAllow>. See
L<systemd.resource-control(5)>
for the details about C<DevicePolicy> or C<DeviceAllow>. Also, see
C<PrivateDevices> below, as it may change the setting of
C<DevicePolicy>.',
      '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 C<root>, but C<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 C<+>.

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, C<_> and
C<->, except for the first character which must be one of a-z, A-Z and
C<_> (i.e. digits and C<-> 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

lib/Config/Model/models/Systemd/Common/Exec.pl  view on Meta::CPAN

DER-encoded signature file, or as an ASCII base64 string encoding of a DER-encoded signature prefixed
by C<base64:>. The dm-verity volume will only be opened if the signature of the root
hash is valid and signed by a public key present in the kernel keyring. If this option is not
specified, but a file with the C<.roothash.p7s> suffix is found next to the image
file, bearing otherwise the same name (except if the image has the C<.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 C</usr/> partition it may also be
Verity protected, in which case the signature for the root hash may configured via a
C<.usrhash.p7s> file adjacent to the disk image. There\'s currently no option to
configure the root hash signature for the C</usr/> via the unit file
directly.',
      'RootImage' => 'Takes a path to a block device node or regular file as argument. This call is similar
to C<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 L<UAPI.2
Discoverable Partitions
Specification|https://uapi-group.org/specifications/specs/discoverable_partitions_specification>.

When C<DevicePolicy> is set to C<closed> or
C<strict>, or set to C<auto> and C<DeviceAllow> is
set, then this setting adds C</dev/loop-control> with C<rw> mode,
C<block-loop> and C<block-blkext> with C<rwm> mode
to C<DeviceAllow>. See
L<systemd.resource-control(5)>
for the details about C<DevicePolicy> or C<DeviceAllow>. Also, see
C<PrivateDevices> below, as it may change the setting of
C<DevicePolicy>.

Units making use of C<RootImage> automatically gain an
C<After> dependency on C<systemd-udevd.service>.

The host\'s
L<os-release(5)>
file will be made available for the service (read-only) as
C</run/host/os-release>.
It will be updated automatically on soft reboot (see:
L<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
C<RootImage>. Optionally a partition name can be prefixed, followed by colon, in
case the image has multiple partitions, otherwise partition name C<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
L<mount(8)>.

Valid partition names follow the
L<Discoverable Partitions
Specification|https://uapi-group.org/specifications/specs/discoverable_partitions_specification>:
C<root>, C<usr>, C<home>, C<srv>,
C<esp>, C<xbootldr>, C<tmp>,
C<var>.',
      'RootImagePolicy' => '*ExtensionImagePolicy',
      'RootMStack' => 'Takes a path to a
L<systemd.mstack(7)>
directory encapsulating a mount stack consisting of layers and bind mounts. Similar to
C<RootDirectory> and C<RootImage> this runs the service off a
distinct root file system, in this case set up via C<overlayfs>.

Since C<.mstack/> directories may reference disk images (DDIs) similar device
policy extensions and dependencies are in effect when C<RootMStack> is used as are
if C<RootImage> is used.',
      'RootVerity' => 'Takes the path to a data integrity (dm-verity) file. This option enables data integrity checks
using dm-verity, if C<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 C<.verity> suffix is found next to the image file, bearing otherwise
the same name (except if the image has the C<.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
L<Discoverable Partitions
Specification|https://uapi-group.org/specifications/specs/discoverable_partitions_specification>.',
      'RuntimeDirectory' => '*CacheDirectory',
      'RuntimeDirectoryMode' => '*CacheDirectoryMode',
      'RuntimeDirectoryPreserve' => 'Takes a boolean argument or C<restart>. If set to C<no> (the
default), the directories specified in C<RuntimeDirectory> are always removed when the service
stops. If set to C<restart> the directories are preserved when the service is both automatically
and manually restarted. Here, the automatic restart means the operation specified in
C<Restart>, and manual restart means the one triggered by systemctl restart
foo.service. If set to C<yes>, then the directories are not removed when the service is
stopped. Note that since the runtime directory C</run/> is a mount point of
C<tmpfs>, then for system services the directories specified in
C<RuntimeDirectory> are removed when the system is rebooted.

If C<DynamicUser> is used together with
C<RuntimeDirectoryPreserve> set to values other than C<no>, the logic
is slightly altered: the C<RuntimeDirectory> directories are created below
C</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 C</run/>.',
      '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 C<->, 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 C<+>. See
L<setexeccon(3)>
for details.',
      'SecureBits' => 'Controls the secure bits set for the executed process. Takes a space-separated combination of
options from the following list: C<keep-caps>, C<keep-caps-locked>,
C<no-setuid-fixup>, C<no-setuid-fixup-locked>, C<noroot>, and
C<noroot-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 C<+>. See L<capabilities(7)> for
details.',
      'SetCredential' => 'The C<SetCredential> setting is similar to
C<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
C<LoadCredential>. In order to embed binary data into the credential data use
C-style escaping (i.e. C<\\n> to embed a newline, or C<\\x00> to embed
a C<NUL> byte).