view release on metacpan or  search on metacpan

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

which configure resource control settings for the processes of the
service.

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'
    ],
    'element' => [
      'Type',
      {
        'description' => "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 \x{2014} 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) \x{2014} 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.",
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'ExitType',
      {
        'description' => '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.',
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'RemainAfterExit',
      {
        'description' => 'Takes a boolean value that specifies whether
the service shall be considered active even when all its
processes exited. Defaults to C<no>.',
        'type' => 'leaf',
        'upstream_default' => 'no',
        'value_type' => 'boolean',
        'write_as' => [
          'no',
          'yes'
        ]
      },
      'GuessMainPID',
      {
        'description' => '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>.',
        'type' => 'leaf',
        'upstream_default' => 'yes',
        'value_type' => 'boolean',
        'write_as' => [
          'no',
          'yes'
        ]
      },
      'PIDFile',
      {
        'description' => '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.',
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'BusName',
      {

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

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.',
        'type' => 'list'
      },
      'ExecCondition',
      {
        'cargo' => {
          'type' => 'leaf',
          'value_type' => 'uniline'
        },
        'description' => '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.',
        'type' => 'list'
      },
      'ExecReload',
      {
        'cargo' => {
          'type' => 'leaf',
          'value_type' => 'uniline'
        },
        'description' => '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>.',
        'type' => 'list'
      },
      'ExecReloadPost',
      {
        'cargo' => {
          'type' => 'leaf',
          'value_type' => 'uniline'
        },
        'description' => 'Commands to execute after a successful reload operation. Syntax for this setting
is exactly the same as C<ExecReload>.',
        'type' => 'list'
      },
      'ExecStop',
      {
        'cargo' => {
          'type' => 'leaf',
          'value_type' => 'uniline'
        },
        'description' => '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