Config-Model-Systemd

 view release on metacpan or  search on metacpan

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

of IPC objects and temporary files created by the executed processes is bound to the runtime of the
service, and hence the lifetime of the dynamic user/group. Since C</tmp/> and
C</var/tmp/> are usually the only world-writable directories on a system, unless
C<PrivateTmp> is manually set to C<true>, C<disconnected>
would be implied. This ensures that a unit making use of dynamic user/group allocation cannot
leave files around after unit termination. Furthermore
C<NoNewPrivileges> and C<RestrictSUIDSGID> are implicitly enabled
(and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID
files or directories. Moreover, C<ProtectSystem=strict> and
C<ProtectHome=read-only> are implied, thus prohibiting the service to write to
arbitrary file system locations. In order to allow the service to write to certain directories, they
have to be allow-listed using C<ReadWritePaths>, but care must be taken so that
UID/GID recycling does not create security issues involving files created by the service. Use
C<RuntimeDirectory> (see below) in order to assign a writable runtime directory to a
service, owned by the dynamic user/group and removed automatically when the unit is terminated. Use
C<StateDirectory>, C<CacheDirectory> and
C<LogsDirectory> in order to assign a set of writable directories for specific
purposes to the service in a way that they are protected from vulnerabilities due to UID reuse (see
below). If this option is enabled, care should be taken that the unit's processes do not get access
to directories outside of these explicitly configured and managed ones. Specifically, do not use
C<BindPaths> and be careful with C<AF_UNIX> file descriptor
passing for directory file descriptors, as this would permit processes to create files or directories
owned by the dynamic user/group that are not subject to the lifecycle and access guarantees of the
service. Note that this option is currently incompatible with D-Bus policies, thus a service using
this option may currently not allocate a D-Bus service name (note that this does not affect calling
into other D-Bus services). Defaults to off.",
      'Environment' => "Sets environment variables for executed processes. Each line is unquoted using the
rules described in \"Quoting\" section in
L<systemd.syntax(7)>
and becomes a list of variable assignments. If you need to assign a value containing spaces or the
equals sign to a variable, put quotes around the whole assignment. Variable expansion is not
performed inside the strings and the C<\$> character has no special meaning. Specifier
expansion is performed, see the \"Specifiers\" section in
L<systemd.unit(5)>.

This option may be specified more than once, in which case all listed variables will be set. If
the same variable is listed twice, the later setting will override the earlier setting. If the empty
string is assigned to this option, the list of environment variables is reset, all prior assignments
have no effect.

The names of the variables can contain ASCII letters, digits, and the underscore character.
Variable names cannot be empty or start with a digit. In variable values, most characters are
allowed, but non-printable characters are currently rejected.

Example:

    Environment=\"VAR1=word1 word2\" VAR2=word3 \"VAR3=\$word 5 6\"

gives three variables C<VAR1>,
C<VAR2>, C<VAR3>
with the values C<word1 word2>,
C<word3>, C<\$word 5 6>.

See L<environ(7)> for
details about environment variables.

Note that environment variables are not suitable for passing secrets (such as passwords, key
material, \x{2026})  to service processes. Environment variables set for a unit are exposed to unprivileged
clients via D-Bus IPC, and generally not understood as being data that requires protection. Moreover,
environment variables are propagated down the process tree, including across security boundaries
(such as setuid/setgid executables), and hence might leak to processes that should not have access to
the secret data. Use C<LoadCredential>, C<LoadCredentialEncrypted>
or C<SetCredentialEncrypted> (see below) to pass data to unit processes
securely.",
      'EnvironmentFile' => 'Similar to C<Environment>, but reads the environment variables from
a text file. The text file should contain newline-separated variable assignments. Empty lines, lines
without an C<=> separator, or lines starting with C<;> or
C<#> will be ignored, which may be used for commenting. The file must be encoded with
UTF-8. Valid characters are
L<unicode scalar values|https://www.unicode.org/glossary/#unicode_scalar_value>
other than
L<unicode noncharacters|https://www.unicode.org/glossary/#noncharacter>,
C<U+0000> C<NUL>, and C<U+FEFF>L<unicode byte order mark|https://www.unicode.org/glossary/#byte_order_mark>.
Control codes other than C<NUL> are allowed.

In the file, an unquoted value after the C<=> is parsed with the same backslash-escape
rules as L<POSIX shell unquoted
text|https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01>, but unlike in a shell,
interior whitespace is preserved and quotes after the
first non-whitespace character are preserved. Leading and trailing whitespace (space, tab, carriage return) is
discarded, but interior whitespace within the line is preserved verbatim. A line ending with a backslash will be
continued to the following one, with the newline itself discarded. A backslash
C<\\> followed by any character other than newline will preserve the following character, so that
C<\\\\> will become the value C<\\>.

In the file, a C<\'>-quoted value after the C<=> can span
multiple lines and contain any character verbatim other than single quote, like L<POSIX
shell single-quoted text|https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02>. No
backslash-escape sequences are recognized. Leading and trailing
whitespace outside of the single quotes is discarded.

In the file, a C<">-quoted value after the C<=> can span
multiple lines, and the same escape sequences are recognized as in L<POSIX
shell double-quoted text|https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03>.
Backslash (C<\\>) followed by any of
C<"\\`$> will preserve that character. A backslash followed by newline is a line
continuation, and the newline itself is discarded. A backslash followed by any other character is
ignored; both the backslash and the following character are preserved verbatim. Leading and trailing
whitespace outside of the double quotes is discarded.

The argument passed should be an absolute filename or wildcard expression. If the file does not
exist, cannot be read, or contains invalid content, the service will fail to start. To make the file
optional, prefix the path with C<->, which causes all errors related to the file to be
silently ignored. This option may be specified more than once in which case all specified files are read.
If the empty string is assigned to this option, the list of files to read is reset, all prior assignments
have no effect.

Note that shell variables such as C<$HOME> are not expanded in this path.
Use C<%>-specifiers instead; for example, C<%h> expands to the
user\'s home directory.

The files listed with this directive will be read shortly before the process is executed (more
specifically, after all processes from a previous unit state terminated. This means you can generate these
files in one unit state, and read it with this option in the next. The files are read from the file
system of the service manager, before any file system changes like bind mounts take place).

Settings from these files override settings made with C<Environment>. If the same
variable is set twice from these files, the files will be read in the order they are specified and the later
setting will override the earlier setting.',
      'ExecPaths' => 'Sets up a new file system namespace for executed processes. These options may be used
to limit access a process has to the file system. Each setting takes a space-separated list of paths

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

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>.',
      'NUMAMask' => 'Controls the NUMA node list which will be applied alongside with selected NUMA policy.
Takes a list of NUMA nodes and has the same syntax as a list of CPUs for C<CPUAffinity>
option or special "all" value which will include all available NUMA nodes in the mask. Note that the list
of NUMA nodes is not required for C<default> and C<local>
policies and for C<preferred> policy we expect a single NUMA node.',
      'NUMAPolicy' => 'Controls the NUMA memory policy of the executed processes. Takes a policy type, one of:
C<default>, C<preferred>, C<bind>, C<interleave> and
C<local>. A list of NUMA nodes that should be associated with the policy must be specified
in C<NUMAMask>. For more details on each policy please see,
L<set_mempolicy(2)>. For overall
overview of NUMA support in Linux see,
L<numa(7)>.
',
      'NetworkNamespacePath' => 'Takes an absolute file system path referring to a Linux network namespace
pseudo-file (i.e. a file like C</proc/$PID/ns/net> or a bind mount or symlink to
one). When set the invoked processes are added to the network namespace referenced by that path. The
path has to point to a valid namespace file at the moment the processes are forked off. If this
option is used C<PrivateNetwork> has no effect. If this option is used together with
C<JoinsNamespaceOf> then it only has an effect if this unit is started before any of
the listed units that have C<PrivateNetwork> or
C<NetworkNamespacePath> configured, as otherwise the network namespace of those
units is reused.

When this option is enabled, C<PrivateMounts> is implied unless it is
explicitly disabled, and C</sys> will be remounted to associate it with the new
network namespace.

When this option is used on a socket unit any sockets bound on behalf of this unit will be
bound within the specified network namespace.',
      'Nice' => 'Sets the default nice level (scheduling priority) for executed processes. Takes an
integer between -20 (highest priority) and 19 (lowest priority). In case of resource contention,
smaller values mean more resources will be made available to the unit\'s processes, larger values mean
less resources will be made available. See
L<setpriority(2)> for
details.',
      'NoExecPaths' => '*ExecPaths',
      'NoNewPrivileges' => 'Takes a boolean argument. If true, ensures that the service process and all its
children can never gain new privileges through execve() (e.g. via setuid or
setgid bits, or filesystem capabilities). This is the simplest and most effective way to ensure that
a process and its children can never elevate privileges again. Defaults to false. In case the service
will be run in a new mount namespace anyway and SELinux is disabled, all file systems are mounted with
C<MS_NOSUID> flag. Also see L<No New Privileges Flag|https://docs.kernel.org/userspace-api/no_new_privs.html>.

Note that this setting only has an effect on the unit\'s processes themselves (or any processes
directly or indirectly forked off them). It has no effect on processes potentially invoked on request
of them through tools such as L<at(1)>,
L<crontab(1)>,
L<systemd-run(1)>, or
arbitrary IPC services.',
      'OOMScoreAdjust' => 'Sets the adjustment value for the Linux kernel\'s Out-Of-Memory (OOM) killer score for
executed processes. Takes an integer between -1000 (to disable OOM killing of processes of this unit)
and 1000 (to make killing of processes of this unit under memory pressure very likely). See L<The /proc
Filesystem|https://docs.kernel.org/filesystems/proc.html> for
details. If not specified, defaults to the OOM score adjustment level of the service manager itself,
which is normally at 0.

Use the C<OOMPolicy> setting of service units to configure how the service
manager shall react to the kernel OOM killer or systemd-oomd terminating a process of the service. See
L<systemd.service(5)>
for details.',
      'PAMName' => 'Sets the PAM service name to set up a session as. If set, the executed process will be
registered as a PAM session under the specified service name. This is only useful in conjunction with the
C<User> setting, and is otherwise ignored. If not set, no PAM session will be opened for the
executed processes. See L<pam(8)> for
details.

Note that for each unit making use of this option a PAM session handler process will be maintained as
part of the unit and stays around as long as the unit is active, to ensure that appropriate actions can be
taken when the unit and hence the PAM session terminates. This process is named C<(sd-pam)> and
is an immediate child process of the unit\'s main process.

Note that when this option is used for a unit it is very likely (depending on PAM configuration) that the
main unit process will be migrated to its own session scope unit when it is activated. This process will hence
be associated with two units: the unit it was originally started from (and for which
C<PAMName> was configured), and the session scope unit. Any child processes of that process
will however be associated with the session scope unit only. This has implications when used in combination
with C<NotifyAccess>=C<all>, as these child processes will not be able to affect
changes in the original unit through notification messages. These messages will be considered belonging to the
session scope unit and not the original unit. It is hence not recommended to use C<PAMName> in
combination with C<NotifyAccess>=C<all>.

If a PAM module interactively requests input (a password or suchlike) it will be attempted to
be read from a service credential (as configured via C<SetCredential>,
C<ImportCredential> and related calls) under the name
C<pam.authtok.pamservice>, where
pamservice is replaced by the PAM service name as configured with
C<PAMName>. (Note that the credential remains accessible for the runtime of the
service!) If no matching credential is set, the user is prompted for it interactively via the L<Password
Agent|https://systemd.io/PASSWORD_AGENTS> logic.',
      'PassEnvironment' => 'Pass environment variables set for the system service manager to executed processes. Takes a
space-separated list of variable names. This option may be specified more than once, in which case all listed
variables will be passed. If the empty string is assigned to this option, the list of environment variables to
pass is reset, all prior assignments have no effect. Variables specified that are not set for the system
manager will not be passed and will be silently ignored. Note that this option is only relevant for the system
service manager, as system services by default do not automatically inherit any environment variables set for
the service manager itself. However, in case of the user service manager all environment variables are passed
to the executed processes anyway, hence this option is without effect for the user service manager.

Variables set for invoked processes due to this setting are subject to being overridden by those

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

Commands prefixed with C<+> are not subject to filtering. The
execve(), exit(), exit_group(),
getrlimit(), rt_sigreturn(),
sigreturn() system calls and the system calls for querying time and sleeping are
implicitly allow-listed and do not need to be listed explicitly.

The default action when a system call is denied is to terminate the processes with a
C<SIGSYS> signal. This can changed using C<SystemCallErrorNumber>,
see below. In addition, deny-listed system calls and system call groups may optionally be suffixed
with a colon (C<:>) and an argument in the same format as
C<SystemCallErrorNumber>, to take this action when the matching system call is made.
This takes precedence over the action specified in C<SystemCallErrorNumber>.

This feature makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp
filtering') and is useful for enforcing a minimal sandboxing environment.

Note that on systems supporting multiple ABIs (such as x86/x86-64) it is recommended to turn
off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this
option. Specifically, it is recommended to combine this option with
C<SystemCallArchitectures=native> or similar.

Note that strict system call filters may impact execution and error handling code paths of the
service invocation. Specifically, access to the execve() system call is required
for the execution of the service binary \x{2014} if it is blocked service invocation will necessarily fail.
Also, if execution of the service binary fails for some reason (for example: missing service
executable), the error handling logic might require access to an additional set of system calls in
order to process and log this failure correctly. It might be necessary to temporarily disable system
call filters in order to allow debugging of such failures.

If you specify both types of this option (i.e. allow-listing and deny-listing), the first
encountered will take precedence and will dictate the default action (termination or approval of a
system call). Then the next occurrences of this option will add or delete the listed system calls
from the set of the filtered system calls, depending of its type and the default action. (For
example, if you have started with an allow list rule for read() and
write(), and right after it add a deny list rule for write(),
then write() will be removed from the set.)

As the number of possible system calls is large, predefined groups of system calls are
provided. A group starts with C<\@> character, followed by name of the set.
Currently predefined system call setsSetDescription\@aioAsynchronous I/O (L<io_setup(2)>, L<io_submit(2)>, and related
calls)\@basic-ioSystem calls for basic I/O: reading, writing, seeking, file descriptor duplication and closing
(L<read(2)>, L<write(2)>, and related calls)\@chownChanging file ownership (L<chown(2)>, L<fchownat(2)>, and related
calls)\@clockSystem calls for changing the system clock (L<adjtimex(2)>, L<settimeofday(2)>, and related
calls)\@cpu-emulationSystem calls for CPU emulation functionality (L<vm86(2)> and related calls)\@debugDebugging,
performance monitoring and tracing functionality (L<ptrace(2)>, L<perf_event_open(2)> and related
calls)\@file-systemFile system operations: opening, creating files and directories for read and write, renaming and
removing them, reading file properties, or creating hard and symbolic links\@io-eventEvent loop system calls
(L<poll(2)>, L<select(2)>, L<epoll(7)>, L<eventfd(2)> and related calls)\@ipcPipes, SysV IPC, POSIX Message Queues and
other IPC (L<mq_overview(7)>, L<svipc(7)>)\@keyringKernel keyring access (L<keyctl(2)> and related calls)\@memlockLocking
of memory in RAM (L<mlock(2)>, L<mlockall(2)> and related calls)\@moduleLoading and unloading of kernel modules
(L<init_module(2)>, L<delete_module(2)> and related calls)\@mountMounting and unmounting of file systems (L<mount(2)>,
L<chroot(2)>, and related calls)\@network-ioSocket I/O (including local AF_UNIX): L<socket(7)>,
L<unix(7)>\@obsoleteUnusual, obsolete or unimplemented (L<create_module(2)>, L<gtty(2)>, \x{2026})\@pkeySystem calls that deal
with memory protection keys (L<pkeys(7)>)\@privilegedAll system calls which need super-user capabilities
(L<capabilities(7)>)\@processProcess control, execution, namespacing operations (L<clone(2)>, L<kill(2)>,
L<namespaces(7)>, \x{2026})\@raw-ioRaw I/O port access (L<ioperm(2)>, L<iopl(2)>, pciconfig_read(), \x{2026})\@rebootSystem calls for
rebooting and reboot preparation (L<reboot(2)>, kexec(), \x{2026})\@resourcesSystem calls for changing resource limits, memory
and scheduling parameters (L<setrlimit(2)>, L<setpriority(2)>, \x{2026})\@sandboxSystem calls for sandboxing programs
(L<seccomp(2)>, Landlock system calls, \x{2026})\@setuidSystem calls for changing user ID and group ID credentials,
(L<setuid(2)>, L<setgid(2)>, L<setresuid(2)>, \x{2026})\@signalSystem calls for manipulating and handling process signals
(L<signal(2)>, L<sigprocmask(2)>, \x{2026})\@swapSystem calls for enabling/disabling swap devices (L<swapon(2)>,
L<swapoff(2)>)\@syncSynchronizing files and memory to disk (L<fsync(2)>, L<msync(2)>, and related calls)\@system-serviceA
reasonable set of system calls used by common system services, excluding any special purpose calls. This is the
recommended starting point for allow-listing system calls for system services, as it contains what is typically needed
by system services, but excludes overly specific interfaces. For example, the following APIs are excluded: C<\@clock>,
C<\@mount>, C<\@swap>, C<\@reboot>.\@timerSystem calls for scheduling operations by time (L<alarm(2)>, L<timer_create(2)>,
\x{2026})\@knownAll system calls defined by the kernel. This list is defined statically in systemd based on a kernel version
that was available when this systemd version was released. It will become progressively more out-of-date as the kernel
is updated.
Note, that as new system calls are added to the kernel, additional system calls might be added to the groups
above. Contents of the sets may also change between systemd versions. In addition, the list of system calls
depends on the kernel version and architecture for which systemd was compiled. Use
systemd-analyze\x{a0}syscall-filter to list the actual list of system calls in each
filter.

Generally, allow-listing system calls (rather than deny-listing) is the safer mode of
operation. It is recommended to enforce system call allow lists for all long-running system
services. Specifically, the following lines are a relatively safe basic choice for the majority of
system services:

    [Service]
    SystemCallFilter=\@system-service
    SystemCallErrorNumber=EPERM

Note that various kernel system calls are defined redundantly: there are multiple system calls
for executing the same operation. For example, the pidfd_send_signal() system
call may be used to execute operations similar to what can be done with the older
kill() system call, hence blocking the latter without the former only provides
weak protection. Since new system calls are added regularly to the kernel as development progresses,
keeping system call deny lists comprehensive requires constant work. It is thus recommended to use
allow-listing instead, which offers the benefit that new system calls are by default implicitly
blocked until the allow list is updated.

Also note that a number of system calls are required to be accessible for the dynamic linker to
work. The dynamic linker is required for running most regular programs (specifically: all dynamic ELF
binaries, which is how most distributions build packaged programs). This means that blocking these
system calls (which include open(), openat() or
mmap()) will make most programs typically shipped with generic distributions
unusable.

It is recommended to combine the file system namespacing related options with
C<SystemCallFilter=~\@mount>, in order to prohibit the unit's processes to undo the
mappings. Specifically these are the options C<PrivateTmp>,
C<PrivateDevices>, C<ProtectSystem>, C<ProtectHome>,
C<ProtectKernelTunables>, C<ProtectControlGroups>,
C<ProtectKernelLogs>, C<ProtectClock>, C<ReadOnlyPaths>,
C<InaccessiblePaths> and C<ReadWritePaths>.",
      'SystemCallLog' => 'Takes a space-separated list of system call names. If this setting is used, all
system calls executed by the unit processes for the listed ones will be logged. If the first
character of the list is C<~>, the effect is inverted: all system calls except the
listed system calls will be logged. This feature makes use of the Secure Computing Mode 2 interfaces
of the kernel (\'seccomp filtering\') and is useful for auditing or setting up a minimal sandboxing
environment. This option may be specified more than once, in which case the filter masks are merged.
If the empty string is assigned, the filter is reset, all prior assignments will have no effect.
This does not affect commands prefixed with C<+>.',
      'TTYColumns' => 'Configure the size of the TTY specified with C<TTYPath>. If unset or
set to the empty string, it is attempted to retrieve the dimensions of the terminal screen via ANSI
sequences, and if that fails the kernel defaults (typically 80x24) are used.',
      'TTYPath' => 'Sets the terminal device node to use if standard input, output, or error are connected to a TTY
(see above). Defaults to C</dev/console>.',