view release on metacpan or  search on metacpan

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

C<truncate>,
C<graceful>;
if not specified, files will be opened in C<rw> mode;
if C<graceful> is specified, errors during file/socket opening are ignored.
Specifying the same option several times is treated as an error.
The file or socket is opened by the service manager and the file descriptor is passed to the service.
If the path is a socket, we call connect() on it.
See L<sd_listen_fds(3)>
for more details on how to retrieve these file descriptors.

This setting is useful to allow services to access files/sockets that they cannot access themselves
(due to running in a separate mount namespace, not having privileges, ...).

This setting can be specified multiple times, in which case all the specified paths are opened and the file descriptors
passed to the service.
If the empty string is assigned, the entire list of open files defined prior to this is reset.',
      '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.',
      'RefreshOnReload' => 'Takes a boolean argument, or a list of resources defined in
L<systemd.exec(5)>.
Possible values are C<extensions> and C<credentials>, separated by space.
Prepending the list with a single tilde character (C<~>) inverts the effect.
Defaults to C<extensions>. An empty assignment resets the list to default. If enabled,
the corresponding resources (C<ExtensionImages>/C<ExtensionDirectories>
for C<extensions> and C<LoadCredential>/C<ImportCredential>/
C<SetCredential> (along with their C<Encrypted> counterparts)
for C<credentials>) will be refreshed on service reload. If C<yes>,
all resources listed above that are used by the service shall be refreshed.

Specially, if this option is set explicitly, and the respective resources are in use,
the service may be reloaded without any actual reload mechanism (C<ExecReload>
or C<Type=notify-reload>) for notifying the main process, in which case the reload
is considered complete immediately after refreshing.',
      'ReloadSignal' => 'Configures the UNIX process signal to send to the service\'s main process when asked
to reload the service\'s configuration. Defaults to C<SIGHUP>. This option has no
effect unless C<Type>=C<notify-reload> is used, see
above.',
      'RemainAfterExit' => 'Takes a boolean value that specifies whether
the service shall be considered active even when all its
processes exited. Defaults to C<no>.',
      'Restart' => 'Configures whether the service shall be restarted when the service process exits,
is killed, or a timeout is reached. The service process may be the main service process, but it may
also be one of the processes specified with C<ExecStartPre>,
C<ExecStartPost>, C<ExecStop>, C<ExecStopPost>,
or C<ExecReload>. When the death of the process is a result of systemd operation
(e.g. service stop or restart), the service will not be restarted. Timeouts include missing the watchdog
"keep-alive ping" deadline and a service start, reload, and stop operation timeouts.

Takes one of C<no>, C<on-success>, C<on-failure>,
C<on-abnormal>, C<on-watchdog>, C<on-abort>, or
C<always>. If set to C<no> (the default), the service will not be restarted.
If set to C<on-success>, it will be restarted only when the service process exits cleanly.
In this context, a clean exit means any of the following:
exit code of 0;for types other than C<Type=oneshot>, one of the signals
C<SIGHUP>, C<SIGINT>,
C<SIGTERM>, or C<SIGPIPE>;
exit statuses and signals specified in
C<SuccessExitStatus>.
If set to C<on-failure>, the service will be restarted when the process exits with
a non-zero exit code, is terminated by a signal (including on core dump, but excluding the aforementioned
four signals), when an operation (such as service reload) times out, and when the configured watchdog
timeout is triggered. If set to C<on-abnormal>, the service will be restarted when
the process is terminated by a signal (including on core dump, excluding the aforementioned four signals),
when an operation times out, or when the watchdog timeout is triggered. If set to C<on-abort>,
the service will be restarted only if the service process exits due to an uncaught signal not specified
as a clean exit status. If set to C<on-watchdog>, the service will be restarted
only if the watchdog timeout for the service expires. If set to C<always>, the service
will be restarted regardless of whether it exited cleanly or not, got terminated abnormally by
a signal, or hit a timeout. Note that C<Type=oneshot> services will never be restarted
on a clean exit status, i.e. C<always> and C<on-success> are rejected
for them.

As exceptions to the setting above, the service will not
be restarted if the exit code or signal is specified in
C<RestartPreventExitStatus> (see below) or
the service is stopped with systemctl stop
or an equivalent operation. Also, the services will always be
restarted if the exit code or signal is specified in
C<RestartForceExitStatus> (see below).

Note that service restart is subject to unit start rate
limiting configured with C<StartLimitIntervalSec>
and C<StartLimitBurst>, see
L<systemd.unit(5)>
for details.

Setting this to C<on-failure> is the
recommended choice for long-running services, in order to
increase reliability by attempting automatic recovery from
errors. For services that shall be able to terminate on their
own choice (and avoid immediate restarting),
C<on-abnormal> is an alternative choice.',
      'RestartForceExitStatus' => 'Takes a list of exit status definitions that, when returned by the main service
process, will force automatic service restarts, regardless of the restart setting configured with
C<Restart>. The argument format is similar to C<RestartPreventExitStatus>.

Note that for C<Type=oneshot> services, a success exit status will prevent
them from auto-restarting, no matter whether the corresponding exit statuses are listed in this
option or not.',
      'RestartMaxDelaySec' => 'Configures the longest time to sleep before restarting a service
as the interval goes up with C<RestartSteps>. Takes a value
in the same format as C<RestartSec>, or C<infinity>
to disable the setting. Defaults to C<infinity>.

This setting is effective only if C<RestartSteps> is also set and
C<RestartSec> is not zero.',
      'RestartMode' => 'Takes a string value that specifies how a service should restart:

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

L<systemd-system.conf(5)>).

If a service of C<Type=notify>/C<Type=notify-reload> sends
C<EXTEND_TIMEOUT_USEC=\x{2026}>, this may cause the stop time to be extended beyond
C<TimeoutStopSec>. The first receipt of this message must occur before
C<TimeoutStopSec> is exceeded, and once the stop time has extended beyond
C<TimeoutStopSec>, the service manager will allow the service to continue to stop,
provided the service repeats C<EXTEND_TIMEOUT_USEC=\x{2026}> within the interval specified,
or terminates itself (see
L<sd_notify(3)>).
",
      '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 \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.",
      'USBFunctionDescriptors' => 'Configure the location of a file containing
L<USB
FunctionFS|https://docs.kernel.org/usb/functionfs.html> descriptors, for implementation of USB
gadget functions. This is used only in conjunction with a
socket unit with C<ListenUSBFunction>
configured. The contents of this file are written to the
C<ep0> file after it is
opened.',
      'USBFunctionStrings' => 'Configure the location of a file containing
USB FunctionFS strings.  Behavior is similar to
C<USBFunctionDescriptors>
above.',
      'WatchdogSec' => 'Configures the watchdog timeout for a service.
The watchdog is activated when the start-up is completed. The
service must call
L<sd_notify(3)>
regularly with C<WATCHDOG=1> (i.e. the
"keep-alive ping"). If the time between two such calls is
larger than the configured time, then the service is placed in
a failed state and it will be terminated with
C<SIGABRT> (or the signal specified by
C<WatchdogSignal>). By setting
C<Restart> to C<on-failure>,
C<on-watchdog>, C<on-abnormal> or
C<always>, the service will be automatically
restarted. The time configured here will be passed to the
executed service process in the
C<WATCHDOG_USEC> environment variable. This
allows daemons to automatically enable the keep-alive pinging
logic if watchdog support is enabled for the service. If this
option is used, C<NotifyAccess> (see below)
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>.
Defaults to 0, which disables this feature. The service can
check whether the service manager expects watchdog keep-alive
notifications. See
L<sd_watchdog_enabled(3)>
for details.
L<sd_event_set_watchdog(3)>
may be used to enable automatic watchdog notification support.
'
    },
    'element' => [
      'Type',
      {
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'ExitType',
      '*Type',
      'RemainAfterExit',
      {
        'type' => 'leaf',
        'upstream_default' => 'no',
        'value_type' => 'boolean',
        'write_as' => [
          'no',
          'yes'
        ]
      },
      'GuessMainPID',
      {
        'type' => 'leaf',
        'upstream_default' => 'yes',
        'value_type' => 'boolean',
        'write_as' => [
          'no',
          'yes'
        ]
      },
      'PIDFile',
      {
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'BusName',
      '*PIDFile',
      'ExecStart',
      {
        'cargo' => {
          'type' => 'leaf',
          'value_type' => 'uniline'
        },
        'type' => 'list'
      },
      'ExecStartPre',
      '*ExecStart',
      'ExecStartPost',
      '*ExecStart',
      'ExecCondition',
      '*ExecStart',
      'ExecReload',
      '*ExecStart',
      'ExecReloadPost',
      '*ExecStart',