view release on metacpan or  search on metacpan

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

It is recommended to turn this on for most services that do not need modify the clock or check
its state.',
      'ProtectControlGroups' => 'Takes a boolean argument or the special values C<private> or
C<strict>. If true, the Linux Control Groups (L<cgroups(7)>) hierarchies
accessible through C</sys/fs/cgroup/> will be made read-only to all processes of the
unit. If set to C<private>, the unit will run in a cgroup namespace with a private
writable mount of C</sys/fs/cgroup/>. If set to C<strict>, the unit
will run in a cgroup namespace with a private read-only mount of C</sys/fs/cgroup/>.
Defaults to off. If C<ProtectControlGroups> is set, C<MountAPIVFS=yes>
is implied. Note C<private> and C<strict> are downgraded to false and
true respectively unless the system is using the unified control group hierarchy and the kernel supports
cgroup namespaces.

Except for container managers no services should require write access to the control groups hierarchies;
it is hence recommended to set C<ProtectControlGroups> to true or C<strict>
for most services. For this setting the same restrictions regarding mount propagation and privileges apply
as for C<ReadOnlyPaths> and related settings, see above.',
      'ProtectHome' => 'Takes a boolean argument or the special values C<read-only> or
C<tmpfs>. If true, the directories C</home/>,
C</root>, and C</run/user> are made inaccessible and empty for
processes invoked by this unit. If set to C<read-only>, the three directories are
made read-only instead. If set to C<tmpfs>, temporary file systems are mounted on the
three directories in read-only mode. The value C<tmpfs> is useful to hide home
directories not relevant to the processes invoked by the unit, while still allowing necessary
directories to be made visible when listed in C<BindPaths> or
C<BindReadOnlyPaths>.

Setting this to C<yes> is mostly equivalent to setting the three directories in
C<InaccessiblePaths>. Similarly, C<read-only> is mostly equivalent to
C<ReadOnlyPaths>, and C<tmpfs> is mostly equivalent to
C<TemporaryFileSystem> with C<:ro>.

It is recommended to enable this setting for all long-running services (in particular
network-facing ones), to ensure they cannot get access to private user data, unless the services
actually require access to the user\'s private data. This setting is implied if
C<DynamicUser> is set. This setting cannot ensure protection in all cases. In
general it has the same limitations as C<ReadOnlyPaths>, see below.

Note that this setting provides no protection if home directories are placed at a non-standard
location, i.e. outside of the hierarchies listed above.',
      'ProtectHostname' => 'Takes a boolean argument or C<private>. If enabled, sets up a new UTS
namespace for the executed processes. If enabled, a hostname can be optionally specified following a
colon (e.g. C<yes:foo> or C<private:host.example.com>), and the
hostname is set in the new UTS namespace for the unit. If set to a true value, changing hostname or
domainname via sethostname() and setdomainname() system
calls is prevented. If set to C<private>, changing hostname or domainname is allowed
but only affects the unit\'s UTS namespace. Defaults to off.

Note that the implementation of this setting might be impossible (for example if UTS namespaces
are not available), and the unit should be written in a way that does not solely rely on this setting
for security.

Note that when this option is enabled for a service hostname changes no longer propagate from
the system into the service, it is hence not suitable for services that need to take notice of system
hostname changes dynamically.

Note that this option does not prevent changing system hostname via hostnamectl.
However, C<User> and C<Group> may be used to run as an unprivileged user
to disallow changing system hostname. See SetHostname() in
L<org.freedesktop.hostname1(5)>
for more details.',
      'ProtectKernelLogs' => 'Takes a boolean argument. If true, access to the kernel log ring buffer will be denied. It is
recommended to turn this on for most services that do not need to read from or write to the kernel log ring
buffer. Enabling this option removes C<CAP_SYSLOG> from the capability bounding set for this
unit, and installs a system call filter to block the
L<syslog(2)>
system call (not to be confused with the libc API
L<syslog(3)>
for userspace logging). The kernel exposes its log buffer to userspace via C</dev/kmsg> and
C</proc/kmsg>. If enabled, these are made inaccessible to all the processes in the unit.
',
      'ProtectKernelModules' => 'Takes a boolean argument. If true, explicit module loading will be denied. This allows
module load and unload operations to be turned off on modular kernels. It is recommended to turn this on for most
services
that do not need special file systems or extra kernel modules to work. Defaults to off. Enabling this option
removes C<CAP_SYS_MODULE> from the capability bounding set for the unit, and installs a
system call filter to block module system calls, also C</usr/lib/modules> is made
inaccessible. For this setting the same restrictions regarding mount propagation and privileges apply as for
C<ReadOnlyPaths> and related calls, see above. Note that limited automatic module loading due
to user configuration or kernel mapping tables might still happen as side effect of requested user operations,
both privileged and unprivileged. To disable module auto-load feature please see
L<sysctl.d(5)>C<kernel.modules_disabled> mechanism and
C</proc/sys/kernel/modules_disabled> documentation.',
      'ProtectKernelTunables' => 'Takes a boolean argument. If true, kernel variables accessible through
C</proc/sys/>, C</sys/>, C</proc/sysrq-trigger>,
C</proc/latency_stats>, C</proc/acpi>,
C</proc/timer_stats>, C</proc/fs> and C</proc/irq> will
be made read-only and C</proc/kallsyms> as well as C</proc/kcore> will be
inaccessible to all processes of the unit.
Usually, tunable kernel variables should be initialized only at boot-time, for example with the
L<sysctl.d(5)> mechanism. Few
services need to write to these at runtime; it is hence recommended to turn this on for most services. For this
setting the same restrictions regarding mount propagation and privileges apply as for
C<ReadOnlyPaths> and related calls, see above. Defaults to off.
Note that this option does not prevent indirect changes to kernel tunables affected by IPC calls to
other processes. However, C<InaccessiblePaths> may be used to make relevant IPC file system
objects inaccessible. If C<ProtectKernelTunables> is set,
C<MountAPIVFS=yes> is implied.',
      'ProtectProc' => '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
C<noaccess> the ability to access most of other users\' process metadata in
C</proc/> is taken away for processes of the service. When set to
C<invisible> processes owned by other users are hidden from
C</proc/>. If C<ptraceable> all processes that cannot be
ptrace()\'ed by a process are hidden to it. If C<default> no
restrictions on C</proc/> access or visibility are made. For further details see
L<The /proc
Filesystem|https://docs.kernel.org/filesystems/proc.html#mount-options>. It is generally recommended to run most system
services with this option set to
C<invisible>. This option is implemented via file system namespacing, and thus cannot
be used with services that shall be able to install mount points in the host file system
hierarchy. Note that the root user is unaffected by this option, so to be effective it has to be used
together with C<User> or C<DynamicUser=yes>, and also without the
C<CAP_SYS_PTRACE> capability, which also allows a process to bypass this feature. It
cannot be used for services that need to access metainformation about other users\' processes. This
option implies C<MountAPIVFS>.

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

This setting defaults to C<null>, unless
C<StandardInputText>/C<StandardInputData> are set, in which case it
defaults to C<data>.",
      'StandardInputData' => "Configures arbitrary textual or binary data to pass via file descriptor 0 (STDIN) to
the executed processes. These settings have no effect unless C<StandardInput> is set
to C<data> (which is the default if C<StandardInput> is not set
otherwise, but C<StandardInputText>/C<StandardInputData> is). Use
this option to embed process input data directly in the unit file.

C<StandardInputText> accepts arbitrary textual data. C-style escapes for special
characters as well as the usual C<%>-specifiers are resolved. Each time this setting is used
the specified text is appended to the per-unit data buffer, followed by a newline character (thus every use
appends a new line to the end of the buffer). Note that leading and trailing whitespace of lines configured
with this option is removed. If an empty line is specified the buffer is cleared (hence, in order to insert an
empty line, add an additional C<\\n> to the end or beginning of a line).

C<StandardInputData> accepts arbitrary binary data, encoded in
L<Base64|https://tools.ietf.org/html/rfc2045#section-6.8>. No escape sequences or specifiers are
resolved. Any whitespace in the encoded version is ignored during decoding.

Note that C<StandardInputText> and C<StandardInputData> operate on the
same data buffer, and may be mixed in order to configure both binary and textual data for the same input
stream. The textual or binary data is joined strictly in the order the settings appear in the unit
file. Assigning an empty string to either will reset the data buffer.

Please keep in mind that in order to maintain readability long unit file settings may be split into
multiple lines, by suffixing each line (except for the last) with a C<\\> character (see
L<systemd.unit(5)> for
details). This is particularly useful for large data configured with these two options. Example:

    \x{2026}
    StandardInput=data
    StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZXMgYW5kIHNvIGRv \\
    IEkKQSBmdWxsIGNvbW1pdG1lbnQncyB3aGF0IEnigLJtIHRoaW5raW5nIG9mCllvdSB3b3VsZG4n \\
    dCBnZXQgdGhpcyBmcm9tIGFueSBvdGhlciBndXkKSSBqdXN0IHdhbm5hIHRlbGwgeW91IGhvdyBJ \\
    J20gZmVlbGluZwpHb3R0YSBtYWtlIHlvdSB1bmRlcnN0YW5kCgpOZXZlciBnb25uYSBnaXZlIHlv \\
    dSB1cApOZXZlciBnb25uYSBsZXQgeW91IGRvd24KTmV2ZXIgZ29ubmEgcnVuIGFyb3VuZCBhbmQg \\
    ZGVzZXJ0IHlvdQpOZXZlciBnb25uYSBtYWtlIHlvdSBjcnkKTmV2ZXIgZ29ubmEgc2F5IGdvb2Ri \\
    eWUKTmV2ZXIgZ29ubmEgdGVsbCBhIGxpZSBhbmQgaHVydCB5b3UK
    \x{2026}
",
      'StandardInputText' => '*StandardInputData',
      'StandardOutput' => "Controls where file descriptor 1 (stdout) of the executed processes is connected
to. Takes one of C<inherit>, C<null>, C<tty>,
C<journal>, C<kmsg>, C<journal+console>,
C<kmsg+console>, C<file:path>,
C<append:path>, C<truncate:path>,
C<socket> or C<fd:name>.

C<inherit> duplicates the file descriptor of standard input for standard output.

C<null> connects standard output to C</dev/null>, i.e. everything written
to it will be lost.

C<tty> connects standard output to a tty (as configured via C<TTYPath>,
see below). If the TTY is used for output only, the executed process will not become the controlling process of
the terminal, and will not fail or wait for other processes to release the terminal. Note: if a unit
tries to print multiple lines to a TTY during bootup or shutdown, then there's a chance that those
lines will be broken up by status messages. SetShowStatus() can be used to
prevent this problem. See
L<org.freedesktop.systemd1(5)>
for details.

C<journal> connects standard output with the journal, which is accessible via
L<journalctl(1)>. Note
that everything that is written to kmsg (see below) is implicitly stored in the journal as well, the
specific option listed below is hence a superset of this one. (Also note that any external,
additional syslog daemons receive their log data from the journal, too, hence this is the option to
use when logging shall be processed with such a daemon.)

C<kmsg> connects standard output with the kernel log buffer which is accessible via
L<dmesg(1)>,
in addition to the journal. The journal daemon might be configured to send all logs to kmsg anyway, in which
case this option is no different from C<journal>.

C<journal+console> and C<kmsg+console> work in a similar way as the
two options above but copy the output to the system console as well.

The C<file:path> option may be used to connect a specific file
system object to standard output. The semantics are similar to the same option of
C<StandardInput>, see above. If path refers to a regular file
on the filesystem, it is opened (created if it does not exist yet using privileges of the user executing the
systemd process) for writing at the beginning of the file, but without truncating it.
If standard input and output are directed to the same file path, it is opened only once \x{2014} for reading as well
as writing \x{2014} and duplicated. This is particularly useful when the specified path refers to an
C<AF_UNIX> socket in the file system, as in that case only a
single stream connection is created for both input and output.

C<append:path> is similar to
C<file:path> above, but it opens the file in append mode.

C<truncate:path> is similar to
C<file:path> above, but it truncates the file when opening
it. For units with multiple command lines, e.g. C<Type=oneshot> services with
multiple C<ExecStart>, or services with C<ExecCondition>,
C<ExecStartPre> or C<ExecStartPost>, the output file is reopened
and therefore re-truncated for each command line. If the output file is truncated while another
process still has the file open, e.g. by an C<ExecReload> running concurrently with
an C<ExecStart>, and the other process continues writing to the file without
adjusting its offset, then the space between the file pointers of the two processes may be filled
with C<NUL> bytes, producing a sparse file. Thus,
C<truncate:path> is typically only useful for units where
only one process runs at a time, such as services with a single C<ExecStart> and no
C<ExecStartPost>, C<ExecReload>, C<ExecStop> or
similar.

C<socket> connects standard output to a socket acquired via socket activation. The
semantics are similar to the same option of C<StandardInput>, see above.

The C<fd:name> option connects standard output to a
specific, named file descriptor provided by a socket unit. A name may be specified as part of this
option, following a C<:> character
(e.g. C<fd:foobar>). If no name is specified, the name
C<stdout> is implied (i.e. C<fd> is equivalent to
C<fd:stdout>). At least one socket unit defining the specified name must be provided
via the C<Sockets> option, and the file descriptor name may differ from the name of
its containing socket unit. If multiple matches are found, the first one will be used. See
C<FileDescriptorName> in
L<systemd.socket(5)>
for more details about named descriptors and their ordering.