Config-Model-Systemd

 view release on metacpan or  search on metacpan

lib/Config/Model/models/Systemd/Section/Service.pod  view on Meta::CPAN

Similar to C<identity>, this does not provide UID/GID isolation, but it does provide
process capability isolation. If this mode is enabled, all unit processes are run without privileges
in the host user namespace (regardless of whether the unit's own user/group is
C<root> or not). Specifically this means that the process will have zero process
capabilities on the host's user namespace, but full capabilities within the service's user
namespace. Settings such as C<CapabilityBoundingSet> will affect only the latter,
and there's no way to acquire additional capabilities in the host's user namespace.

If the parameter is C<managed> a transient, dynamically allocated range of
65536 UIDs/GIDs is allocated for the unit, and a UID/GID mapping is assigned to the unit's process
so the UID/GID 0 from inside the unit maps to the first UID/GID of the allocated mapping. Note that
in this mode the UID/GID the service process will run as is different depending if looking from the
host side (where it will be a high, dynamically assigned UID) or from inside the unit (where it will
be 0). Also note that this mode will enable file system UID mapping for the file systems this service
accesses, mapping the "foreign" UID range on disk to the selected dynamic UID range at
runtime.

When this setting is set up by a per-user instance of the service manager, the mapping of the
C<root> user and group to itself is omitted (unless the user manager is root).
Additionally, in the per-user instance manager case, the
user namespace will be set up before most other namespaces. This means that combining
C<PrivateUsers>=C<true> with other namespaces will enable use of features not
normally supported by the per-user instances of the service manager.

This setting is particularly useful in conjunction with
C<RootDirectory>/C<RootImage>, as the need to synchronize the user and group
databases in the root directory and on the host is reduced, as the only users and groups who need to be matched
are C<root>, C<nobody> and the unit's own user and group. I< Optional. Type enum. choice: 'full', 'identity', 'managed', 'no', 'self', 'yes'.  > 

=over 4

=item upstream_default value :

no

=back



=head2 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. I< Optional. Type enum. choice: 'no', 'private', 'yes'.  > 

=over 4

=item upstream_default value :

no

=back



=head2 ProtectClock

Takes a boolean argument. If set, writes to the hardware clock or system clock will
be denied. Defaults to off. Enabling this option removes C<CAP_SYS_TIME> and
C<CAP_WAKE_ALARM> from the capability bounding set for this unit, installs a system
call filter to block calls that can set the clock, and C<DeviceAllow=char-rtc r> is
implied. Note that the system calls are blocked altogether, the filter does not take into account
that some of the calls can be used to read the clock state with some parameter combinations.
Effectively, C</dev/rtc0>, C</dev/rtc1>, etc. are made read-only
to the service. See
L<systemd.resource-control(5)>
for the details about C<DeviceAllow>.

It is recommended to turn this on for most services that do not need modify the clock or check
its state. I< Optional. Type boolean.  > 

=over 4

=item upstream_default value :

no

=back



=head2 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. I< Optional. Type boolean.  > 

=over 4

=item upstream_default value :

lib/Config/Model/models/Systemd/Section/Service.pod  view on Meta::CPAN

C<tty-fail> is similar to C<tty>, but if the terminal already has a
controlling process start-up of the executed process fails.

The C<data> option may be used to configure arbitrary textual or binary data to pass via
standard input to the executed process. The data to pass is configured via
C<StandardInputText>/C<StandardInputData> (see below). Note that the actual
file descriptor type passed (memory file, regular file, UNIX pipe, …) might depend on the kernel and available
privileges. In any case, the file descriptor is read-only, and when read returns the specified data followed by
EOF.

The C<file:path> option may be used to connect a specific file
system object to standard input. An absolute path following the C<:> character is expected,
which may refer to a regular file, a FIFO or special file. If an C<AF_UNIX> socket in the
file system is specified, a stream socket is connected to it. The latter is useful for connecting standard
input of processes to arbitrary system services.

The C<socket> option is valid in socket-activated services only, and requires the relevant
socket unit file (see
L<systemd.socket(5)> for details)
to have C<Accept=yes> set, or to specify a single socket only. If this option is set, standard
input will be connected to the socket the service was activated from, which is primarily useful for
compatibility with daemons designed for use with the traditional L<inetd(8)> socket activation
daemon (C<$LISTEN_FDS> (and related) environment variables are not passed when
C<socket> value is configured).

The C<fd:name> option connects standard input to a specific,
named file descriptor provided by a socket unit. The 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<stdin> is implied (i.e. C<fd> is equivalent to C<fd:stdin>).
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 file descriptors and their ordering.

This setting defaults to C<null>, unless
C<StandardInputText>/C<StandardInputData> are set, in which case it
defaults to C<data>. I< Optional. Type enum. choice: 'data', 'null', 'socket', 'tty', 'tty-fail', 'tty-force'.  > 

=head2 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 — for reading as well
as writing — 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.

lib/Config/Model/models/Systemd/Section/Service.pod  view on Meta::CPAN

is not suitable). Developers can find it useful to use this to
generate a coredump to troubleshoot why a service did not
terminate upon receiving the initial C<SIGTERM>
signal. This can be achieved by configuring C<LimitCORE>
and setting C<FinalKillSignal> to either
C<SIGQUIT> or C<SIGABRT>.
Defaults to C<SIGKILL>.
I< Optional. Type uniline.  > 

=head2 WatchdogSignal

Specifies which signal to use to terminate the
service when the watchdog timeout expires (enabled through
C<WatchdogSec>). Defaults to C<SIGABRT>.
I< Optional. Type uniline.  > 

=head2 Type

Configures the mechanism via which the service notifies the manager that the service start-up
has finished. One of C<simple>, C<exec>, C<forking>,
C<oneshot>, C<dbus>, C<notify>,
C<notify-reload>, or C<idle>:

It is recommended to use C<Type>=C<exec> for long-running
services, as it ensures that process setup errors (e.g. errors such as a missing service
executable, or missing user) are properly tracked. However, as this service type will not propagate
the failures in the service's own startup code (as opposed to failures in the preparatory steps the
service manager executes before execve()) and does not allow ordering of other
units against completion of initialization of the service code itself (which for example is useful
if clients need to connect to the service through some form of IPC, and the IPC channel is only
established by the service itself — in contrast to doing this ahead of time through socket or bus
activation or similar), it might not be sufficient for many cases. If so, C<notify>,
C<notify-reload>, or C<dbus> (the latter only in case the service
provides a D-Bus interface) are the preferred options as they allow service program code to
precisely schedule when to consider the service started up successfully and when to proceed with
follow-up units. The C<notify>/C<notify-reload> service types require
explicit support in the service codebase (as sd_notify() or an equivalent API
needs to be invoked by the service at the appropriate time) — if it is not supported, then
C<forking> is an alternative: it supports the traditional heavy-weight UNIX service
start-up protocol. Note that using any type other than C<simple> possibly delays the
boot process, as the service manager needs to wait for at least some service initialization to
complete. (Also note it is generally not recommended to use C<idle> or
C<oneshot> for long-running services.)

Note that various service settings (e.g. C<User>, C<Group>
through libc NSS) might result in "hidden" blocking IPC calls to other services when
used. Sometimes it might be advisable to use the C<simple> service type to ensure
that the service manager's transaction logic is not affected by such potentially slow operations
and hidden dependencies, as this is the only service type where the service manager will not wait
for such service execution setup operations to complete before proceeding. I< Optional. Type uniline.  > 

=head2 ExitType

Specifies when the manager should consider the service to be finished. One of C<main> or
C<cgroup>:

It is generally recommended to use C<ExitType>=C<main> when a service has
a known forking model and a main process can reliably be determined. C<ExitType>=C<cgroup> is meant for applications
whose forking model is not known ahead of time and which
might not have a specific main process. It is well suited for transient or automatically generated services,
such as graphical applications inside of a desktop environment. I< Optional. Type uniline.  > 

=head2 RemainAfterExit

Takes a boolean value that specifies whether
the service shall be considered active even when all its
processes exited. Defaults to C<no>. I< Optional. Type boolean.  > 

=over 4

=item upstream_default value :

no

=back



=head2 GuessMainPID

Takes a boolean value that specifies whether
systemd should try to guess the main PID of a service if it
cannot be determined reliably. This option is ignored unless
C<Type=forking> is set and
C<PIDFile> is unset because for the other types
or with an explicitly configured PID file, the main PID is
always known. The guessing algorithm might come to incorrect
conclusions if a daemon consists of more than one process. If
the main PID cannot be determined, failure detection and
automatic restarting of a service will not work reliably.
Defaults to C<yes>. I< Optional. Type boolean.  > 

=over 4

=item upstream_default value :

yes

=back



=head2 PIDFile

Takes a path referring to the PID file of the service. Usage of this option is
recommended for services where C<Type> is set to C<forking>. The path
specified typically points to a file below C</run/>. If a relative path is
specified for system service, then it is hence prefixed with C</run/>, and prefixed
with C<$XDG_RUNTIME_DIR> if specified in a user service. The service manager will
read the PID of the main process of the service from this file after start-up of the service. The
service manager will not write to the file configured here, although it will remove the file after
the service has shut down if it still exists. The PID file does not need to be owned by a privileged
user, but if it is owned by an unprivileged user additional safety restrictions are enforced: the
file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and
the PID file must refer to a process already belonging to the service.

Note that PID files should be avoided in modern projects. Use C<Type=notify>,
C<Type=notify-reload> or C<Type=simple> where possible, which does not
require use of PID files to determine the main process of a service and avoids needless
forking. I< Optional. Type uniline.  > 

lib/Config/Model/models/Systemd/Section/Service.pod  view on Meta::CPAN

C<Type> (i.e. the process has been started for C<Type=simple> or
C<Type=idle>, the last C<ExecStart> process exited successfully for
C<Type=oneshot>, the initial process exited successfully for
C<Type=forking>, C<READY=1> is sent for
C<Type=notify>/C<Type=notify-reload>, or the
C<BusName> has been taken for C<Type=dbus>).

Note that C<ExecStartPre> may not be
used to start long-running processes. All processes forked
off by processes invoked via C<ExecStartPre> will
be killed before the next service process is run.

Note that if any of the commands specified in C<ExecStartPre>,
C<ExecStart>, or C<ExecStartPost> fail (and are not prefixed with
C<->, see above) or time out before the service is fully up, execution continues with commands
specified in C<ExecStopPost>, the commands in C<ExecStop> are skipped.

Note that the execution of C<ExecStartPost> is taken into account for the purpose of
C<Before>/C<After> ordering constraints. I< Optional. Type list of uniline.  > 

=head2 ExecCondition

Optional commands that are executed before the commands in
C<ExecStartPre>. Syntax is the same as for C<ExecStart>. Multiple
command lines are allowed, regardless of the service type (i.e. C<Type>), and the
commands are executed one after the other, serially.

The behavior is like an C<ExecStartPre> and condition check hybrid: when an
C<ExecCondition> command exits with exit code 1 through 254 (inclusive), the remaining
commands are skipped and the unit is not marked as failed. However, if an
C<ExecCondition> command exits with 255 or abnormally (e.g. timeout, killed by a
signal, etc.), the unit will be considered failed (and remaining commands will be skipped). Exit code of 0 or
those matching C<SuccessExitStatus> will continue execution to the next commands.

The same recommendations about not running long-running processes in C<ExecStartPre>
also applies to C<ExecCondition>. C<ExecCondition> will also run the commands
in C<ExecStopPost>, as part of stopping the service, in the case of any non-zero or abnormal
exits, like the ones described above. I< Optional. Type list of uniline.  > 

=head2 ExecReload

Commands to execute to trigger a configuration reload in the service. This setting
may take multiple command lines, following the same scheme as described for
C<ExecStart> above. Use of this setting is optional. Specifier and environment
variable substitution is supported here following the same scheme as for
C<ExecStart>.

One additional, special environment variable is set: if known, C<$MAINPID> is
set to the main process of the daemon, and may be used for command lines like the following:

    ExecReload=kill -HUP $MAINPID

Note however that reloading a daemon by enqueuing a signal without completion notification
(as is the case with the example line above) is usually not a good choice, because this is an
asynchronous operation and hence not suitable when ordering reloads of multiple services against
each other. It is thus strongly recommended to either use C<Type=notify-reload>,
or to set C<ExecReload> to a command that not only triggers a configuration reload
of the daemon, but also synchronously waits for it to complete. For example, L<dbus-broker(1)>
uses the following:

    ExecReload=busctl call org.freedesktop.DBus \
    /org/freedesktop/DBus org.freedesktop.DBus \
    ReloadConfig


This setting can be combined with C<Type=notify-reload>, in which case
the service main process is signaled after all specified command lines finish execution. Specially,
if C<RELOADING=1> notification is received before C<ExecReload>
completes, the signaling is skipped and the service manager immediately starts listening for
C<READY=1>. I< Optional. Type list of uniline.  > 

=head2 ExecReloadPost

Commands to execute after a successful reload operation. Syntax for this setting
is exactly the same as C<ExecReload>. I< Optional. Type list of uniline.  > 

=head2 ExecStop

Commands to execute to stop the service started via
C<ExecStart>. This argument takes multiple command lines, following the same scheme
as described for C<ExecStart> above. Use of this setting is optional. After the
commands configured in this option are run, it is implied that the service is stopped, and any
processes remaining for it are terminated according to the C<KillMode> setting (see
L<systemd.kill(5)>).
If this option is not specified, the process is terminated by sending the signal specified in
C<KillSignal> or C<RestartKillSignal> when service stop is
requested. Specifier and environment variable substitution is supported (including
C<$MAINPID>, see above).

Note that it is usually not sufficient to specify a command for this setting that only asks the
service to terminate (for example, by sending some form of termination signal to it), but does not
wait for it to do so. Since the remaining processes of the services are killed according to
C<KillMode> and C<KillSignal> or
C<RestartKillSignal> as described above immediately after the command exited, this
may not result in a clean stop. The specified command should hence be a synchronous operation, not an
asynchronous one.

Note that the commands specified in C<ExecStop> are only executed when the service
started successfully first. They are not invoked if the service was never started at all, or in case its
start-up failed, for example because any of the commands specified in C<ExecStart>,
C<ExecStartPre> or C<ExecStartPost> failed (and were not prefixed with
C<->, see above) or timed out. Use C<ExecStopPost> to invoke commands when a
service failed to start up correctly and is shut down again. Also note that the stop operation is always
performed if the service started successfully, even if the processes in the service terminated on their
own or were killed. The stop commands must be prepared to deal with that case. C<$MAINPID>
will be unset if systemd knows that the main process exited by the time the stop commands are called.

Service restart requests are implemented as stop operations followed by start operations. This
means that C<ExecStop> and C<ExecStopPost> are executed during a
service restart operation.

It is recommended to use this setting for commands that communicate with the service requesting
clean termination. For post-mortem clean-up steps use C<ExecStopPost> instead.
I< Optional. Type list of uniline.  > 

=head2 ExecStopPost

Additional commands that are executed after the service is stopped. This includes cases where
the commands configured in C<ExecStop> were used, where the service does not have any
C<ExecStop> defined, or where the service exited unexpectedly. This argument takes multiple
command lines, following the same scheme as described for C<ExecStart>. Use of these settings
is optional. Specifier and environment variable substitution is supported. Note that – unlike