view release on metacpan or  search on metacpan

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

The L<systemd-run(1)>
command allows creating C<.service> and C<.scope> units dynamically
and transiently from the command line.
This configuration class was generated from systemd documentation.
by L<parse-man.pl|https://github.com/dod38fr/config-model-systemd/contrib/parse-man.pl>
',
    'copyright' => [
      '2010-2016 Lennart Poettering and others',
      '2016 Dominique Dumont'
    ],
    'description' => {
      'BusName' => 'Takes a D-Bus destination name that this service shall use. This option is mandatory
for services where C<Type> is set to C<dbus>. It is recommended to
always set this property if known to make it easy to map the service name to the D-Bus destination.
In particular, systemctl service-log-level/service-log-target verbs make use of
this.',
      '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.

Note that an C<ExecCondition> skip is not equivalent to a
unit-level C<Condition\x{2026}=> or C<Assert\x{2026}=> check failing. Because
C<ExecCondition> runs as part of the activation transition, a skip causes the unit to
transition from C<active> to C<inactive>, and consequently
C<SuccessAction> (see
L<systemd.unit(5)>) will be
honored. By contrast, C<Condition\x{2026}=> directives in the C<[Unit]> section
prevent activation entirely and therefore do not trigger C<SuccessAction>.

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.",
      '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>.',
      'ExecReloadPost' => 'Commands to execute after a successful reload operation. Syntax for this setting
is exactly the same as C<ExecReload>.',
      'ExecStart' => 'Commands that are executed when this service is started.

Unless C<Type> is C<oneshot>, exactly one command must be
given. When C<Type=oneshot> is used, this setting may be used multiple times to
define multiple commands to execute. If the empty string is assigned to this option, the list of
commands to start is reset, prior assignments of this option will have no effect. If no
C<ExecStart> is specified, then the service must have
C<RemainAfterExit=yes> and at least one C<ExecStop> line
set. (Services lacking both C<ExecStart> and C<ExecStop> are not
valid.)

If more than one command is configured, the commands are invoked sequentially in the order they
appear in the unit file. If one of the commands fails (and is not prefixed with
C<->), other lines are not executed, and the unit is considered failed.

Unless C<Type=forking> is set, the process started via this command line will
be considered the main process of the daemon.',
      'ExecStartPost' => 'Additional commands that are executed before or after the command in
C<ExecStart>, respectively. 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.

If any of those commands (not prefixed with
C<->) fail, the rest are not executed and the
unit is considered failed.

C<ExecStart> commands are only run after
all C<ExecStartPre> commands that were not prefixed
with a C<-> exit successfully.

C<ExecStartPost> commands are only run after the commands specified in
C<ExecStart> have been invoked successfully, as determined by
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

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

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.
',
      '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 \x{2013} unlike
C<ExecStop> \x{2013} commands specified with this setting are invoked when a service failed to start
up correctly and is shut down again.

It is recommended to use this setting for clean-up operations that shall be executed even when
the service failed to start up correctly. Commands configured with this setting need to be able to
operate even if the service failed starting up half-way and left incompletely initialized data
around. As the service's processes have likely exited already when the commands specified with this
setting are executed they should not attempt to communicate with them.

Note that all commands that are configured with this setting are invoked with the result code of the
service, as well as the main process' exit code and status, set in the C<\$SERVICE_RESULT>,
C<\$EXIT_CODE> and C<\$EXIT_STATUS> environment variables, see
L<systemd.exec(5)> for
details.

Note that the execution of C<ExecStopPost> is taken into account for the purpose of
C<Before>/C<After> ordering constraints.",
      '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.',
      'FileDescriptorStoreMax' => 'Configure how many file descriptors may be stored in the service manager for the
service using
L<sd_pid_notify_with_fds(3)>\'s
C<FDSTORE=1> messages. This is useful for implementing services that can restart
after an explicit request or a crash without losing state. Any open sockets and other file
descriptors which should not be closed during the restart may be stored this way. Application state
can either be serialized to a file in C<RuntimeDirectory>, or stored in a
L<memfd_create(2)>
memory file descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service
manager. All file descriptors passed to the service manager from a specific service are passed back
to the service\'s main process on the next service restart (see
L<sd_listen_fds(3)> for
details about the precise protocol used and the order in which the file descriptors are passed). Any
file descriptors passed to the service manager are automatically closed when
C<POLLHUP> or C<POLLERR> is seen on them, or when the service is
fully stopped and no job is queued or being executed for it (the latter can be tweaked with
C<FileDescriptorStorePreserve>, see below). If this option is used,
C<NotifyAccess> (see above) should be set to open access to the notification socket
provided by systemd. If C<NotifyAccess> is not set, it will be implicitly set to
C<main>.

The fdstore command of
L<systemd-analyze(1)>
may be used to list the current contents of a service\'s file descriptor store.

Note that the service manager will only pass file descriptors contained in the file descriptor
store to the service\'s own processes, never to other clients via IPC or similar. However, it does
allow unprivileged clients to query the list of currently open file descriptors of a
service. Sensitive data may hence be safely placed inside the referenced files, but should not be
attached to the metadata (e.g. included in filenames) of the stored file
descriptors.

If this option is set to a non-zero value the C<$FDSTORE> environment variable
will be set for processes invoked for this service. See
L<systemd.exec(5)> for
details.

For further information on the file descriptor store see the L<File Descriptor
Store|https://systemd.io/FILE_DESCRIPTOR_STORE> overview.',
      'FileDescriptorStorePreserve' => "Takes one of C<no>, C<yes>,
C<restart>, C<on-success> and controls when to release the
service's file descriptor store (i.e. when to close the contained file descriptors, if any). If set
to C<no> the file descriptor store is automatically released when the service is
stopped; if C<restart> (the default) it is kept around as long as the unit is
neither inactive nor failed, or a job is queued for the service, or the service is expected to be
restarted. If C<yes> the file descriptor store is kept around and garbage
collection of the unit is disabled. The latter is useful to keep entries in the file descriptor
store pinned until the unit is removed, the service manager exits, or the file descriptors get
C<EPOLLHUP> or C<EPOLLERR>. If C<on-success>
the behaviour is identical to C<yes>, except that the file descriptor store is
discarded if the unit enters the permanent C<failed> state (i.e. once all automated
restart attempts driven by C<Restart> have been exhausted). The store is preserved
across the transitionary failed states that precede each individual auto-restart attempt.

When set to C<yes> or C<on-success>, and the service is
itself running under another service manager (e.g. a service of C<user\@.service>,
or a payload inside
L<systemd-nspawn(1)>),
file descriptors pushed into the store are also forwarded one level up via the enveloping manager's
C<\$NOTIFY_SOCKET>, tagged with the originating unit id, so that they are preserved