view release on metacpan or  search on metacpan

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

The default policy for C<ExtensionImagePolicy> is:

    root=verity+signed+encrypted+unprotected+absent: \\
    usr=verity+signed+encrypted+unprotected+absent
',
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'MountImagePolicy',
      {
        'description' => '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
',
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'ExtensionImagePolicy',
      {
        'description' => '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
',
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'RootMStack',
      {
        'description' => '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.',
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'MountAPIVFS',
      {
        'description' => 'Takes a boolean argument. If on, a private mount namespace for the unit\'s processes is created
and the API file systems C</proc/>, C</sys/>, C</dev/> and
C</run/> (as an empty C<tmpfs>) are mounted inside of it, unless they are
already mounted. Note that this option has no effect unless used in conjunction with
C<RootDirectory>/C<RootImage> as these four mounts are
generally mounted in the host anyway, and unless the root directory is changed, the private mount namespace
will be a 1:1 copy of the host\'s, and include these four mounts. Note that the C</dev/> file
system of the host is bind mounted if this option is used without C<PrivateDevices>. To run
the service with a private, minimal version of C</dev/>, combine this option with
C<PrivateDevices>.

In order to allow propagating mounts at runtime in a safe manner, C</run/systemd/propagate/>
on the host will be used to set up new mounts, and C</run/host/incoming/> in the private namespace
will be used as an intermediate step to store them before being moved to the final mount point.',
        'type' => 'leaf',
        'value_type' => 'boolean',
        'write_as' => [
          'no',
          'yes'
        ]
      },
      'BindLogSockets',
      {
        'description' => 'Takes a boolean argument. If true, sockets from L<systemd-journald.socket(8)>
will be bind mounted into the mount namespace. This is particularly useful when a different instance
of C</run/> is employed, to make sure processes running in the namespace
can still make use of L<sd-journal(3)>.

This option is implied when C<LogNamespace> is used,
when C<MountAPIVFS=yes>, or when C<PrivateDevices=yes> is used
in conjunction with either C<RootDirectory> or C<RootImage>.',
        'type' => 'leaf',
        'value_type' => 'boolean',
        'write_as' => [
          'no',
          'yes'
        ]
      },
      'ProtectProc',
      {
        'choice' => [
          'default',
          'invisible',
          'noaccess',
          'ptraceable'
        ],
        'description' => 'Takes one of C<noaccess>, C<invisible>,
C<ptraceable> or C<default> (which it defaults to). When set, this
controls the C<hidepid=> mount option of the C<procfs> instance for
the unit that controls which directories with process metainformation
(C</proc/PID>) are visible and accessible: when set to

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

Note that the destination directory must exist or systemd must be able to create it. Thus, it
is not possible to use those options for mount points nested underneath paths specified in
C<InaccessiblePaths>, or under C</home/> and other protected
directories if C<ProtectHome=yes> is
specified. C<TemporaryFileSystem> with C<:ro> or
C<ProtectHome=tmpfs> should be used instead.',
        'type' => 'list'
      },
      'MountImages',
      {
        'cargo' => {
          'type' => 'leaf',
          'value_type' => 'uniline'
        },
        'description' => 'This setting is similar to C<RootImage> in that it mounts a file
system hierarchy from a block device node or loopback file, but the destination directory can be
specified as well as mount options. This option expects a whitespace separated list of mount
definitions. Each definition consists of a colon-separated tuple of source path and destination
definitions, optionally followed by another colon and a list of mount options.

Mount options may be defined as a single comma-separated list of options, in which case they
will be implicitly applied to the root partition on the image, or a series of colon-separated tuples
of partition name and mount options. Valid partition names and mount options are the same as for
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 source or destination contain 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 mount
paths. If the empty string is assigned, the entire list of mount paths defined prior to this is
reset.

Note that the destination directory must exist or systemd must be able to create it. Thus, it
is not possible to use those options for mount points nested underneath paths specified in
C<InaccessiblePaths>, or under C</home/> and other protected
directories if C<ProtectHome=yes> is specified.

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>.',
        'type' => 'list'
      },
      'ExtensionImages',
      {
        'cargo' => {
          'type' => 'leaf',
          'value_type' => 'uniline'
        },
        'description' => '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>.',
        'type' => 'list'
      },
      'ExtensionDirectories',
      {
        'cargo' => {
          'type' => 'leaf',
          'value_type' => 'uniline'
        },
        'description' => '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.',
        'type' => 'list'
      },
      'User',
      {
        'description' => "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
order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux
systems. For further details on the names accepted and the names warned about see L<User/Group Name
Syntax|https://systemd.io/USER_NAMES>.

When used in conjunction with C<DynamicUser> the user/group name specified is
dynamically allocated at the time the service is started, and released at the time the service is
stopped \x{2014} unless it is already allocated statically (see below). If C<DynamicUser>
is not used the specified user and group must have been created statically in the user database no
later than the moment the service is started, for example using the
L<sysusers.d(5)>
facility, which is applied at boot or package install time. If the user does not exist by then
program invocation will fail.

If the C<User> setting is used the supplementary group list is initialized
from the specified user's default group list, as defined in the system's user and group
database. Additional groups may be configured through the C<SupplementaryGroups>
setting (see below).",
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'Group',
      {
        'description' => "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
order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux
systems. For further details on the names accepted and the names warned about see L<User/Group Name
Syntax|https://systemd.io/USER_NAMES>.