File Coverage

blib/lib/Config/Model/models/Systemd/Section/Service.pl
Criterion Covered Total %
statement 18 18 100.0
branch n/a
condition n/a
subroutine 6 6 100.0
pod n/a
total 24 24 100.0


line stmt bran cond sub pod time code
1             #
2             # This file is part of Config-Model-Systemd
3             #
4             # This software is Copyright (c) 2008-2022 by Dominique Dumont.
5             #
6             # This is free software, licensed under:
7             #
8             # The GNU Lesser General Public License, Version 2.1, February 1999
9             #
10 4     4   21187 use strict;
  4     1   9  
  4     1   95  
  1         2749  
  1         1  
  1         19  
  1         3209  
  1         1  
  1         24  
11 4     4   18 use warnings;
  4     1   7  
  4     1   3236  
  1         4  
  1         1  
  1         726  
  1         5  
  1         3  
  1         903  
12              
13             return [
14             {
15             'accept' => [
16             '.*',
17             {
18             'type' => 'leaf',
19             'value_type' => 'uniline',
20             'warn' => 'Unexpected systemd parameter. Please contact cme author to update systemd model.'
21             }
22             ],
23             'class_description' => 'A unit configuration file whose name ends in
24             C<.service> encodes information about a process
25             controlled and supervised by systemd.
26              
27             This man page lists the configuration options specific to
28             this unit type. See
29             L<systemd.unit(5)>
30             for the common options of all unit configuration files. The common
31             configuration items are configured in the generic
32             [Unit] and [Install]
33             sections. The service specific configuration options are
34             configured in the [Service] section.
35              
36             Additional options are listed in
37             L<systemd.exec(5)>,
38             which define the execution environment the commands are executed
39             in, and in
40             L<systemd.kill(5)>,
41             which define the way the processes of the service are terminated,
42             and in
43             L<systemd.resource-control(5)>,
44             which configure resource control settings for the processes of the
45             service.
46              
47             If SysV init compat is enabled, systemd automatically creates service units that wrap SysV init
48             scripts (the service name is the same as the name of the script, with a C<.service>
49             suffix added); see
50             L<systemd-sysv-generator(8)>.
51              
52              
53             The L<systemd-run(1)>
54             command allows creating C<.service> and C<.scope> units dynamically
55             and transiently from the command line.
56             This configuration class was generated from systemd documentation.
57             by L<parse-man.pl|https://github.com/dod38fr/config-model-systemd/contrib/parse-man.pl>
58             ',
59             'copyright' => [
60             '2010-2016 Lennart Poettering and others',
61             '2016 Dominique Dumont'
62             ],
63             'element' => [
64             'Type',
65             {
66             'description' => "Configures the process start-up type for this service unit. One of C<simple>,
67             C<exec>, C<forking>, C<oneshot>, C<dbus>,
68             C<notify> or C<idle>:
69              
70             It is generally recommended to use C<Type>C<simple> for long-running
71             services whenever possible, as it is the simplest and fastest option. However, as this service type won't
72             propagate service start-up failures and doesn't allow ordering of other units against completion of
73             initialization of the service (which for example is useful if clients need to connect to the service through
74             some form of IPC, and the IPC channel is only established by the service itself \x{2014} in contrast to doing this
75             ahead of time through socket or bus activation or similar), it might not be sufficient for many cases. If so,
76             C<notify> or C<dbus> (the latter only in case the service provides a D-Bus
77             interface) are the preferred options as they allow service program code to precisely schedule when to
78             consider the service started up successfully and when to proceed with follow-up units. The
79             C<notify> service type requires explicit support in the service codebase (as
80             sd_notify() or an equivalent API needs to be invoked by the service at the appropriate
81             time) \x{2014} if it's not supported, then C<forking> is an alternative: it supports the traditional
82             UNIX service start-up protocol. Finally, C<exec> might be an option for cases where it is
83             enough to ensure the service binary is invoked, and where the service binary itself executes no or little
84             initialization on its own (and its initialization is unlikely to fail). Note that using any type other than
85             C<simple> possibly delays the boot process, as the service manager needs to wait for service
86             initialization to complete. It is hence recommended not to needlessly use any types other than
87             C<simple>. (Also note it is generally not recommended to use C<idle> or
88             C<oneshot> for long-running services.)",
89             'type' => 'leaf',
90             'value_type' => 'uniline'
91             },
92             'ExitType',
93             {
94             'description' => 'Specifies when the manager should consider the service to be finished. One of C<main> or
95             C<cgroup>:
96              
97             It is generally recommended to use C<ExitType>C<main> when a service has
98             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
99             might not have a specific main process. It is well suited for transient or automatically generated services,
100             such as graphical applications inside of a desktop environment.',
101             'type' => 'leaf',
102             'value_type' => 'uniline'
103             },
104             'RemainAfterExit',
105             {
106             'description' => 'Takes a boolean value that specifies whether
107             the service shall be considered active even when all its
108             processes exited. Defaults to C<no>.',
109             'type' => 'leaf',
110             'value_type' => 'boolean',
111             'write_as' => [
112             'no',
113             'yes'
114             ]
115             },
116             'GuessMainPID',
117             {
118             'description' => 'Takes a boolean value that specifies whether
119             systemd should try to guess the main PID of a service if it
120             cannot be determined reliably. This option is ignored unless
121             C<Type=forking> is set and
122             C<PIDFile> is unset because for the other types
123             or with an explicitly configured PID file, the main PID is
124             always known. The guessing algorithm might come to incorrect
125             conclusions if a daemon consists of more than one process. If
126             the main PID cannot be determined, failure detection and
127             automatic restarting of a service will not work reliably.
128             Defaults to C<yes>.',
129             'type' => 'leaf',
130             'value_type' => 'boolean',
131             'write_as' => [
132             'no',
133             'yes'
134             ]
135             },
136             'PIDFile',
137             {
138             'description' => 'Takes a path referring to the PID file of the service. Usage of this option is recommended for
139             services where C<Type> is set to C<forking>. The path specified typically points
140             to a file below C</run/>. If a relative path is specified it is hence prefixed with
141             C</run/>. The service manager will read the PID of the main process of the service from this
142             file after start-up of the service. The service manager will not write to the file configured here, although it
143             will remove the file after the service has shut down if it still exists. The PID file does not need to be owned
144             by a privileged user, but if it is owned by an unprivileged user additional safety restrictions are enforced:
145             the file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and the
146             PID file must refer to a process already belonging to the service.
147              
148             Note that PID files should be avoided in modern projects. Use C<Type=notify> or
149             C<Type=simple> where possible, which does not require use of PID files to determine the
150             main process of a service and avoids needless forking.',
151             'type' => 'leaf',
152             'value_type' => 'uniline'
153             },
154             'BusName',
155             {
156             'description' => 'Takes a D-Bus destination name that this service shall use. This option is mandatory
157             for services where C<Type> is set to C<dbus>. It is recommended to
158             always set this property if known to make it easy to map the service name to the D-Bus destination.
159             In particular, systemctl service-log-level/service-log-target verbs make use of
160             this.',
161             'type' => 'leaf',
162             'value_type' => 'uniline'
163             },
164             'ExecStart',
165             {
166             'cargo' => {
167             'type' => 'leaf',
168             'value_type' => 'uniline'
169             },
170             'description' => 'Commands with their arguments that are
171             executed when this service is started. The value is split into
172             zero or more command lines according to the rules described
173             below (see section "Command Lines" below).
174              
175             Unless C<Type> is C<oneshot>, exactly one command must be given. When
176             C<Type=oneshot> is used, zero or more commands may be specified. Commands may be specified by
177             providing multiple command lines in the same directive, or alternatively, this directive may be specified more
178             than once with the same effect. If the empty string is assigned to this option, the list of commands to start
179             is reset, prior assignments of this option will have no effect. If no C<ExecStart> is
180             specified, then the service must have C<RemainAfterExit=yes> and at least one
181             C<ExecStop> line set. (Services lacking both C<ExecStart> and
182             C<ExecStop> are not valid.)
183              
184             For each of the specified commands, the first argument must be either an absolute path to an executable
185             or a simple file name without any slashes. Optionally, this filename may be prefixed with a number of special
186             characters:
187              
188             C<@>, C<->, C<:>, and one of
189             C<+>/C<!>/C<!!> may be used together and they can appear in any
190             order. However, only one of C<+>, C<!>, C<!!> may be used at a
191             time. Note that these prefixes are also supported for the other command line settings,
192             i.e. C<ExecStartPre>, C<ExecStartPost>, C<ExecReload>,
193             C<ExecStop> and C<ExecStopPost>.
194              
195             If more than one command is specified, the commands are
196             invoked sequentially in the order they appear in the unit
197             file. If one of the commands fails (and is not prefixed with
198             C<->), other lines are not executed, and the
199             unit is considered failed.
200              
201             Unless C<Type=forking> is set, the
202             process started via this command line will be considered the
203             main process of the daemon.',
204             'type' => 'list'
205             },
206             'ExecStartPre',
207             {
208             'cargo' => {
209             'type' => 'leaf',
210             'value_type' => 'uniline'
211             },
212             'description' => 'Additional commands that are executed before
213             or after the command in C<ExecStart>,
214             respectively. Syntax is the same as for
215             C<ExecStart>, except that multiple command
216             lines are allowed and the commands are executed one after the
217             other, serially.
218              
219             If any of those commands (not prefixed with
220             C<->) fail, the rest are not executed and the
221             unit is considered failed.
222              
223             C<ExecStart> commands are only run after
224             all C<ExecStartPre> commands that were not prefixed
225             with a C<-> exit successfully.
226              
227             C<ExecStartPost> commands are only run after the commands specified in
228             C<ExecStart> have been invoked successfully, as determined by C<Type>
229             (i.e. the process has been started for C<Type=simple> or C<Type=idle>, the last
230             C<ExecStart> process exited successfully for C<Type=oneshot>, the initial
231             process exited successfully for C<Type=forking>, C<READY=1> is sent for
232             C<Type=notify>, or the C<BusName> has been taken for
233             C<Type=dbus>).
234              
235             Note that C<ExecStartPre> may not be
236             used to start long-running processes. All processes forked
237             off by processes invoked via C<ExecStartPre> will
238             be killed before the next service process is run.
239              
240             Note that if any of the commands specified in C<ExecStartPre>,
241             C<ExecStart>, or C<ExecStartPost> fail (and are not prefixed with
242             C<->, see above) or time out before the service is fully up, execution continues with commands
243             specified in C<ExecStopPost>, the commands in C<ExecStop> are skipped.
244              
245             Note that the execution of C<ExecStartPost> is taken into account for the purpose of
246             C<Before>/C<After> ordering constraints.',
247             'type' => 'list'
248             },
249             'ExecStartPost',
250             {
251             'cargo' => {
252             'type' => 'leaf',
253             'value_type' => 'uniline'
254             },
255             'description' => 'Additional commands that are executed before
256             or after the command in C<ExecStart>,
257             respectively. Syntax is the same as for
258             C<ExecStart>, except that multiple command
259             lines are allowed and the commands are executed one after the
260             other, serially.
261              
262             If any of those commands (not prefixed with
263             C<->) fail, the rest are not executed and the
264             unit is considered failed.
265              
266             C<ExecStart> commands are only run after
267             all C<ExecStartPre> commands that were not prefixed
268             with a C<-> exit successfully.
269              
270             C<ExecStartPost> commands are only run after the commands specified in
271             C<ExecStart> have been invoked successfully, as determined by C<Type>
272             (i.e. the process has been started for C<Type=simple> or C<Type=idle>, the last
273             C<ExecStart> process exited successfully for C<Type=oneshot>, the initial
274             process exited successfully for C<Type=forking>, C<READY=1> is sent for
275             C<Type=notify>, or the C<BusName> has been taken for
276             C<Type=dbus>).
277              
278             Note that C<ExecStartPre> may not be
279             used to start long-running processes. All processes forked
280             off by processes invoked via C<ExecStartPre> will
281             be killed before the next service process is run.
282              
283             Note that if any of the commands specified in C<ExecStartPre>,
284             C<ExecStart>, or C<ExecStartPost> fail (and are not prefixed with
285             C<->, see above) or time out before the service is fully up, execution continues with commands
286             specified in C<ExecStopPost>, the commands in C<ExecStop> are skipped.
287              
288             Note that the execution of C<ExecStartPost> is taken into account for the purpose of
289             C<Before>/C<After> ordering constraints.',
290             'type' => 'list'
291             },
292             'ExecCondition',
293             {
294             'cargo' => {
295             'type' => 'leaf',
296             'value_type' => 'uniline'
297             },
298             'description' => 'Optional commands that are executed before the command(s) in C<ExecStartPre>.
299             Syntax is the same as for C<ExecStart>, except that multiple command lines are allowed and the
300             commands are executed one after the other, serially.
301              
302             The behavior is like an C<ExecStartPre> and condition check hybrid: when an
303             C<ExecCondition> command exits with exit code 1 through 254 (inclusive), the remaining
304             commands are skipped and the unit is not marked as failed. However, if an
305             C<ExecCondition> command exits with 255 or abnormally (e.g. timeout, killed by a
306             signal, etc.), the unit will be considered failed (and remaining commands will be skipped). Exit code of 0 or
307             those matching C<SuccessExitStatus> will continue execution to the next command(s).
308              
309             The same recommendations about not running long-running processes in C<ExecStartPre>
310             also applies to C<ExecCondition>. C<ExecCondition> will also run the commands
311             in C<ExecStopPost>, as part of stopping the service, in the case of any non-zero or abnormal
312             exits, like the ones described above.',
313             'type' => 'list'
314             },
315             'ExecReload',
316             {
317             'cargo' => {
318             'type' => 'leaf',
319             'value_type' => 'uniline'
320             },
321             'description' => 'Commands to execute to trigger a configuration
322             reload in the service. This argument takes multiple command
323             lines, following the same scheme as described for
324             C<ExecStart> above. Use of this setting is
325             optional. Specifier and environment variable substitution is
326             supported here following the same scheme as for
327             C<ExecStart>.
328              
329             One additional, special environment variable is set: if
330             known, C<$MAINPID> is set to the main process
331             of the daemon, and may be used for command lines like the
332             following:
333              
334             Note however that reloading a daemon by sending a signal
335             (as with the example line above) is usually not a good choice,
336             because this is an asynchronous operation and hence not
337             suitable to order reloads of multiple services against each
338             other. It is strongly recommended to set
339             C<ExecReload> to a command that not only
340             triggers a configuration reload of the daemon, but also
341             synchronously waits for it to complete. For example,
342             L<dbus-broker(1)>
343             uses the following:',
344             'type' => 'list'
345             },
346             'ExecStop',
347             {
348             'cargo' => {
349             'type' => 'leaf',
350             'value_type' => 'uniline'
351             },
352             'description' => 'Commands to execute to stop the service started via
353             C<ExecStart>. This argument takes multiple command lines, following the same scheme
354             as described for C<ExecStart> above. Use of this setting is optional. After the
355             commands configured in this option are run, it is implied that the service is stopped, and any
356             processes remaining for it are terminated according to the C<KillMode> setting (see
357             L<systemd.kill(5)>).
358             If this option is not specified, the process is terminated by sending the signal specified in
359             C<KillSignal> or C<RestartKillSignal> when service stop is
360             requested. Specifier and environment variable substitution is supported (including
361             C<$MAINPID>, see above).
362              
363             Note that it is usually not sufficient to specify a command for this setting that only asks the
364             service to terminate (for example, by sending some form of termination signal to it), but does not
365             wait for it to do so. Since the remaining processes of the services are killed according to
366             C<KillMode> and C<KillSignal> or
367             C<RestartKillSignal> as described above immediately after the command exited, this
368             may not result in a clean stop. The specified command should hence be a synchronous operation, not an
369             asynchronous one.
370              
371             Note that the commands specified in C<ExecStop> are only executed when the service
372             started successfully first. They are not invoked if the service was never started at all, or in case its
373             start-up failed, for example because any of the commands specified in C<ExecStart>,
374             C<ExecStartPre> or C<ExecStartPost> failed (and weren\'t prefixed with
375             C<->, see above) or timed out. Use C<ExecStopPost> to invoke commands when a
376             service failed to start up correctly and is shut down again. Also note that the stop operation is always
377             performed if the service started successfully, even if the processes in the service terminated on their
378             own or were killed. The stop commands must be prepared to deal with that case. C<$MAINPID>
379             will be unset if systemd knows that the main process exited by the time the stop commands are called.
380              
381             Service restart requests are implemented as stop operations followed by start operations. This
382             means that C<ExecStop> and C<ExecStopPost> are executed during a
383             service restart operation.
384              
385             It is recommended to use this setting for commands that communicate with the service requesting
386             clean termination. For post-mortem clean-up steps use C<ExecStopPost> instead.
387             ',
388             'type' => 'list'
389             },
390             'ExecStopPost',
391             {
392             'cargo' => {
393             'type' => 'leaf',
394             'value_type' => 'uniline'
395             },
396             'description' => "Additional commands that are executed after the service is stopped. This includes cases where
397             the commands configured in C<ExecStop> were used, where the service does not have any
398             C<ExecStop> defined, or where the service exited unexpectedly. This argument takes multiple
399             command lines, following the same scheme as described for C<ExecStart>. Use of these settings
400             is optional. Specifier and environment variable substitution is supported. Note that \x{2013} unlike
401             C<ExecStop> \x{2013} commands specified with this setting are invoked when a service failed to start
402             up correctly and is shut down again.
403              
404             It is recommended to use this setting for clean-up operations that shall be executed even when the
405             service failed to start up correctly. Commands configured with this setting need to be able to operate even if
406             the service failed starting up half-way and left incompletely initialized data around. As the service's
407             processes have been terminated already when the commands specified with this setting are executed they should
408             not attempt to communicate with them.
409              
410             Note that all commands that are configured with this setting are invoked with the result code of the
411             service, as well as the main process' exit code and status, set in the C<\$SERVICE_RESULT>,
412             C<\$EXIT_CODE> and C<\$EXIT_STATUS> environment variables, see
413             L<systemd.exec(5)> for
414             details.
415              
416             Note that the execution of C<ExecStopPost> is taken into account for the purpose of
417             C<Before>/C<After> ordering constraints.",
418             'type' => 'list'
419             },
420             'RestartSec',
421             {
422             'description' => 'Configures the time to sleep before restarting
423             a service (as configured with C<Restart>).
424             Takes a unit-less value in seconds, or a time span value such
425             as "5min 20s". Defaults to 100ms.',
426             'type' => 'leaf',
427             'value_type' => 'uniline'
428             },
429             'TimeoutStartSec',
430             {
431             'description' => "Configures the time to wait for start-up. If a daemon service does not signal start-up
432             completion within the configured time, the service will be considered failed and will be shut down again. The
433             precise action depends on the C<TimeoutStartFailureMode> option. Takes a unit-less value in
434             seconds, or a time span value such as \"5min 20s\". Pass C<infinity> to disable the timeout logic.
435             Defaults to C<DefaultTimeoutStartSec> from the manager configuration file, except when
436             C<Type=oneshot> is used, in which case the timeout is disabled by default (see
437             L<systemd-system.conf(5)>).
438              
439             If a service of C<Type=notify> sends C<EXTEND_TIMEOUT_USEC=\x{2026}>, this may cause
440             the start time to be extended beyond C<TimeoutStartSec>. The first receipt of this message
441             must occur before C<TimeoutStartSec> is exceeded, and once the start time has extended beyond
442             C<TimeoutStartSec>, the service manager will allow the service to continue to start, provided
443             the service repeats C<EXTEND_TIMEOUT_USEC=\x{2026}> within the interval specified until the service
444             startup status is finished by C<READY=1>. (see
445             L<sd_notify(3)>).
446             ",
447             'type' => 'leaf',
448             'value_type' => 'uniline'
449             },
450             'TimeoutStopSec',
451             {
452             'description' => "This option serves two purposes. First, it configures the time to wait for each
453             C<ExecStop> command. If any of them times out, subsequent C<ExecStop> commands
454             are skipped and the service will be terminated by C<SIGTERM>. If no C<ExecStop>
455             commands are specified, the service gets the C<SIGTERM> immediately. This default behavior
456             can be changed by the C<TimeoutStopFailureMode> option. Second, it configures the time
457             to wait for the service itself to stop. If it doesn't terminate in the specified time, it will be forcibly terminated
458             by C<SIGKILL> (see C<KillMode> in
459             L<systemd.kill(5)>).
460             Takes a unit-less value in seconds, or a time span value such
461             as \"5min 20s\". Pass C<infinity> to disable the
462             timeout logic. Defaults to
463             C<DefaultTimeoutStopSec> from the manager
464             configuration file (see
465             L<systemd-system.conf(5)>).
466              
467             If a service of C<Type=notify> sends C<EXTEND_TIMEOUT_USEC=\x{2026}>, this may cause
468             the stop time to be extended beyond C<TimeoutStopSec>. The first receipt of this message
469             must occur before C<TimeoutStopSec> is exceeded, and once the stop time has extended beyond
470             C<TimeoutStopSec>, the service manager will allow the service to continue to stop, provided
471             the service repeats C<EXTEND_TIMEOUT_USEC=\x{2026}> within the interval specified, or terminates itself
472             (see L<sd_notify(3)>).
473             ",
474             'type' => 'leaf',
475             'value_type' => 'uniline'
476             },
477             'TimeoutAbortSec',
478             {
479             'description' => "This option configures the time to wait for the service to terminate when it was aborted due to a
480             watchdog timeout (see C<WatchdogSec>). If the service has a short C<TimeoutStopSec>
481             this option can be used to give the system more time to write a core dump of the service. Upon expiration the service
482             will be forcibly terminated by C<SIGKILL> (see C<KillMode> in
483             L<systemd.kill(5)>). The core file will
484             be truncated in this case. Use C<TimeoutAbortSec> to set a sensible timeout for the core dumping per
485             service that is large enough to write all expected data while also being short enough to handle the service failure
486             in due time.
487              
488             Takes a unit-less value in seconds, or a time span value such as \"5min 20s\". Pass an empty value to skip
489             the dedicated watchdog abort timeout handling and fall back C<TimeoutStopSec>. Pass
490             C<infinity> to disable the timeout logic. Defaults to C<DefaultTimeoutAbortSec> from
491             the manager configuration file (see
492             L<systemd-system.conf(5)>).
493              
494             If a service of C<Type=notify> handles C<SIGABRT> itself (instead of relying
495             on the kernel to write a core dump) it can send C<EXTEND_TIMEOUT_USEC=\x{2026}> to
496             extended the abort time beyond C<TimeoutAbortSec>. The first receipt of this message
497             must occur before C<TimeoutAbortSec> is exceeded, and once the abort time has extended beyond
498             C<TimeoutAbortSec>, the service manager will allow the service to continue to abort, provided
499             the service repeats C<EXTEND_TIMEOUT_USEC=\x{2026}> within the interval specified, or terminates itself
500             (see L<sd_notify(3)>).
501             ",
502             'type' => 'leaf',
503             'value_type' => 'uniline'
504             },
505             'TimeoutSec',
506             {
507             'description' => 'A shorthand for configuring both
508             C<TimeoutStartSec> and
509             C<TimeoutStopSec> to the specified value.
510             ',
511             'type' => 'leaf',
512             'value_type' => 'uniline'
513             },
514             'TimeoutStartFailureMode',
515             {
516             'choice' => [
517             'terminate',
518             'abort',
519             'kill'
520             ],
521             'description' => 'These options configure the action that is taken in case a daemon service does not signal
522             start-up within its configured C<TimeoutStartSec>, respectively if it does not stop within
523             C<TimeoutStopSec>. Takes one of C<terminate>, C<abort> and
524             C<kill>. Both options default to C<terminate>.
525              
526             If C<terminate> is set the service will be gracefully terminated by sending the signal
527             specified in C<KillSignal> (defaults to C<SIGTERM>, see
528             L<systemd.kill(5)>). If the
529             service does not terminate the C<FinalKillSignal> is sent after
530             C<TimeoutStopSec>. If C<abort> is set, C<WatchdogSignal> is sent
531             instead and C<TimeoutAbortSec> applies before sending C<FinalKillSignal>.
532             This setting may be used to analyze services that fail to start-up or shut-down intermittently.
533             By using C<kill> the service is immediately terminated by sending
534             C<FinalKillSignal> without any further timeout. This setting can be used to expedite the
535             shutdown of failing services.
536             ',
537             'type' => 'leaf',
538             'value_type' => 'enum'
539             },
540             'TimeoutStopFailureMode',
541             {
542             'choice' => [
543             'terminate',
544             'abort',
545             'kill'
546             ],
547             'description' => 'These options configure the action that is taken in case a daemon service does not signal
548             start-up within its configured C<TimeoutStartSec>, respectively if it does not stop within
549             C<TimeoutStopSec>. Takes one of C<terminate>, C<abort> and
550             C<kill>. Both options default to C<terminate>.
551              
552             If C<terminate> is set the service will be gracefully terminated by sending the signal
553             specified in C<KillSignal> (defaults to C<SIGTERM>, see
554             L<systemd.kill(5)>). If the
555             service does not terminate the C<FinalKillSignal> is sent after
556             C<TimeoutStopSec>. If C<abort> is set, C<WatchdogSignal> is sent
557             instead and C<TimeoutAbortSec> applies before sending C<FinalKillSignal>.
558             This setting may be used to analyze services that fail to start-up or shut-down intermittently.
559             By using C<kill> the service is immediately terminated by sending
560             C<FinalKillSignal> without any further timeout. This setting can be used to expedite the
561             shutdown of failing services.
562             ',
563             'type' => 'leaf',
564             'value_type' => 'enum'
565             },
566             'RuntimeMaxSec',
567             {
568             'description' => "Configures a maximum time for the service to run. If this is used and the service has been
569             active for longer than the specified time it is terminated and put into a failure state. Note that this setting
570             does not have any effect on C<Type=oneshot> services, as they terminate immediately after
571             activation completed. Pass C<infinity> (the default) to configure no runtime
572             limit.
573              
574             If a service of C<Type=notify> sends C<EXTEND_TIMEOUT_USEC=\x{2026}>, this may cause
575             the runtime to be extended beyond C<RuntimeMaxSec>. The first receipt of this message
576             must occur before C<RuntimeMaxSec> is exceeded, and once the runtime has extended beyond
577             C<RuntimeMaxSec>, the service manager will allow the service to continue to run, provided
578             the service repeats C<EXTEND_TIMEOUT_USEC=\x{2026}> within the interval specified until the service
579             shutdown is achieved by C<STOPPING=1> (or termination). (see
580             L<sd_notify(3)>).
581             ",
582             'type' => 'leaf',
583             'value_type' => 'uniline'
584             },
585             'RuntimeRandomizedExtraSec',
586             {
587             'description' => 'This option modifies C<RuntimeMaxSec> by increasing the maximum runtime by an
588             evenly distributed duration between 0 and the specified value (in seconds). If C<RuntimeMaxSec> is
589             unspecified, then this feature will be disabled.
590             ',
591             'type' => 'leaf',
592             'value_type' => 'uniline'
593             },
594             'WatchdogSec',
595             {
596             'description' => 'Configures the watchdog timeout for a service.
597             The watchdog is activated when the start-up is completed. The
598             service must call
599             L<sd_notify(3)>
600             regularly with C<WATCHDOG=1> (i.e. the
601             "keep-alive ping"). If the time between two such calls is
602             larger than the configured time, then the service is placed in
603             a failed state and it will be terminated with
604             C<SIGABRT> (or the signal specified by
605             C<WatchdogSignal>). By setting
606             C<Restart> to C<on-failure>,
607             C<on-watchdog>, C<on-abnormal> or
608             C<always>, the service will be automatically
609             restarted. The time configured here will be passed to the
610             executed service process in the
611             C<WATCHDOG_USEC> environment variable. This
612             allows daemons to automatically enable the keep-alive pinging
613             logic if watchdog support is enabled for the service. If this
614             option is used, C<NotifyAccess> (see below)
615             should be set to open access to the notification socket
616             provided by systemd. If C<NotifyAccess> is
617             not set, it will be implicitly set to C<main>.
618             Defaults to 0, which disables this feature. The service can
619             check whether the service manager expects watchdog keep-alive
620             notifications. See
621             L<sd_watchdog_enabled(3)>
622             for details.
623             L<sd_event_set_watchdog(3)>
624             may be used to enable automatic watchdog notification support.
625             ',
626             'type' => 'leaf',
627             'value_type' => 'uniline'
628             },
629             'Restart',
630             {
631             'choice' => [
632             'no',
633             'on-success',
634             'on-failure',
635             'on-abnormal',
636             'on-watchdog',
637             'on-abort',
638             'always'
639             ],
640             'description' => 'Configures whether the service shall be
641             restarted when the service process exits, is killed, or a
642             timeout is reached. The service process may be the main
643             service process, but it may also be one of the processes
644             specified with C<ExecStartPre>,
645             C<ExecStartPost>,
646             C<ExecStop>,
647             C<ExecStopPost>, or
648             C<ExecReload>. When the death of the process
649             is a result of systemd operation (e.g. service stop or
650             restart), the service will not be restarted. Timeouts include
651             missing the watchdog "keep-alive ping" deadline and a service
652             start, reload, and stop operation timeouts.
653              
654             Takes one of
655             C<no>,
656             C<on-success>,
657             C<on-failure>,
658             C<on-abnormal>,
659             C<on-watchdog>,
660             C<on-abort>, or
661             C<always>.
662             If set to C<no> (the default), the service will
663             not be restarted. If set to C<on-success>, it
664             will be restarted only when the service process exits cleanly.
665             In this context, a clean exit means any of the following:
666             exit code of 0;for types other than
667             C<Type=oneshot>, one of the signals
668             C<SIGHUP>,
669             C<SIGINT>,
670             C<SIGTERM>, or
671             C<SIGPIPE>;exit statuses and signals specified in
672             C<SuccessExitStatus>.
673             If set to
674             C<on-failure>, the service will be restarted
675             when the process exits with a non-zero exit code, is
676             terminated by a signal (including on core dump, but excluding
677             the aforementioned four signals), when an operation (such as
678             service reload) times out, and when the configured watchdog
679             timeout is triggered. If set to C<on-abnormal>,
680             the service will be restarted when the process is terminated
681             by a signal (including on core dump, excluding the
682             aforementioned four signals), when an operation times out, or
683             when the watchdog timeout is triggered. If set to
684             C<on-abort>, the service will be restarted only
685             if the service process exits due to an uncaught signal not
686             specified as a clean exit status. If set to
687             C<on-watchdog>, the service will be restarted
688             only if the watchdog timeout for the service expires. If set
689             to C<always>, the service will be restarted
690             regardless of whether it exited cleanly or not, got terminated
691             abnormally by a signal, or hit a timeout.
692              
693             As exceptions to the setting above, the service will not
694             be restarted if the exit code or signal is specified in
695             C<RestartPreventExitStatus> (see below) or
696             the service is stopped with systemctl stop
697             or an equivalent operation. Also, the services will always be
698             restarted if the exit code or signal is specified in
699             C<RestartForceExitStatus> (see below).
700              
701             Note that service restart is subject to unit start rate
702             limiting configured with C<StartLimitIntervalSec>
703             and C<StartLimitBurst>, see
704             L<systemd.unit(5)>
705             for details. A restarted service enters the failed state only
706             after the start limits are reached.
707              
708             Setting this to C<on-failure> is the
709             recommended choice for long-running services, in order to
710             increase reliability by attempting automatic recovery from
711             errors. For services that shall be able to terminate on their
712             own choice (and avoid immediate restarting),
713             C<on-abnormal> is an alternative choice.',
714             'type' => 'leaf',
715             'value_type' => 'enum'
716             },
717             'SuccessExitStatus',
718             {
719             'description' => 'Takes a list of exit status definitions that, when returned by the main service
720             process, will be considered successful termination, in addition to the normal successful exit status
721             0 and, except for C<Type=oneshot>, the signals C<SIGHUP>, C<SIGINT>,
722             C<SIGTERM>, and C<SIGPIPE>. Exit status definitions can be
723             numeric termination statuses, termination status names, or termination signal names, separated by
724             spaces. See the Process Exit Codes section in
725             L<systemd.exec(5)> for
726             a list of termination status names (for this setting only the part without the
727             C<EXIT_> or C<EX_> prefix should be used). See L<signal(7)> for
728             a list of signal names.
729              
730             Note that this setting does not change the mapping between numeric exit statuses and their
731             names, i.e. regardless how this setting is used 0 will still be mapped to C<SUCCESS>
732             (and thus typically shown as C<0/SUCCESS> in tool outputs) and 1 to
733             C<FAILURE> (and thus typically shown as C<1/FAILURE>), and so on. It
734             only controls what happens as effect of these exit statuses, and how it propagates to the state of
735             the service as a whole.
736              
737             This option may appear more than once, in which case the list of successful exit statuses is
738             merged. If the empty string is assigned to this option, the list is reset, all prior assignments of
739             this option will have no effect.
740              
741             Note: systemd-analyze exit-status may be used to list exit statuses and
742             translate between numerical status values and names.',
743             'type' => 'leaf',
744             'value_type' => 'uniline'
745             },
746             'RestartPreventExitStatus',
747             {
748             'description' => "Takes a list of exit status definitions that, when returned by the main service
749             process, will prevent automatic service restarts, regardless of the restart setting configured with
750             C<Restart>. Exit status definitions can either be numeric exit codes or termination
751             signal names, and are separated by spaces. Defaults to the empty list, so that, by default, no exit
752             status is excluded from the configured restart logic. For example:
753              
754             RestartPreventExitStatus=1 6 SIGABRT
755              
756             ensures that exit codes 1 and 6 and the termination signal C<SIGABRT> will not
757             result in automatic service restarting. This option may appear more than once, in which case the list
758             of restart-preventing statuses is merged. If the empty string is assigned to this option, the list is
759             reset and all prior assignments of this option will have no effect.
760              
761             Note that this setting has no effect on processes configured via
762             C<ExecStartPre>, C<ExecStartPost>, C<ExecStop>,
763             C<ExecStopPost> or C<ExecReload>, but only on the main service
764             process, i.e. either the one invoked by C<ExecStart> or (depending on
765             C<Type>, C<PIDFile>, \x{2026}) the otherwise configured main
766             process.",
767             'type' => 'leaf',
768             'value_type' => 'uniline'
769             },
770             'RestartForceExitStatus',
771             {
772             'description' => 'Takes a list of exit status definitions that,
773             when returned by the main service process, will force automatic
774             service restarts, regardless of the restart setting configured
775             with C<Restart>. The argument format is
776             similar to
777             C<RestartPreventExitStatus>.',
778             'type' => 'leaf',
779             'value_type' => 'uniline'
780             },
781             'RootDirectoryStartOnly',
782             {
783             'description' => 'Takes a boolean argument. If true, the root
784             directory, as configured with the
785             C<RootDirectory> option (see
786             L<systemd.exec(5)>
787             for more information), is only applied to the process started
788             with C<ExecStart>, and not to the various
789             other C<ExecStartPre>,
790             C<ExecStartPost>,
791             C<ExecReload>, C<ExecStop>,
792             and C<ExecStopPost> commands. If false, the
793             setting is applied to all configured commands the same way.
794             Defaults to false.',
795             'type' => 'leaf',
796             'value_type' => 'boolean',
797             'write_as' => [
798             'no',
799             'yes'
800             ]
801             },
802             'NonBlocking',
803             {
804             'description' => 'Set the C<O_NONBLOCK> flag for all file descriptors passed via socket-based
805             activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr), excluding those passed
806             in via the file descriptor storage logic (see C<FileDescriptorStoreMax> for details), will
807             have the C<O_NONBLOCK> flag set and hence are in non-blocking mode. This option is only
808             useful in conjunction with a socket unit, as described in
809             L<systemd.socket(5)> and has no
810             effect on file descriptors which were previously saved in the file-descriptor store for example. Defaults to
811             false.',
812             'type' => 'leaf',
813             'value_type' => 'uniline'
814             },
815             'NotifyAccess',
816             {
817             'choice' => [
818             'none',
819             'main',
820             'exec',
821             'all'
822             ],
823             'description' => 'Controls access to the service status notification socket, as accessible via the
824             L<sd_notify(3)> call. Takes one
825             of C<none> (the default), C<main>, C<exec> or
826             C<all>. If C<none>, no daemon status updates are accepted from the service
827             processes, all status update messages are ignored. If C<main>, only service updates sent from the
828             main process of the service are accepted. If C<exec>, only service updates sent from any of the
829             main or control processes originating from one of the C<Exec*=> commands are accepted. If
830             C<all>, all services updates from all members of the service\'s control group are accepted. This
831             option should be set to open access to the notification socket when using C<Type=notify> or
832             C<WatchdogSec> (see above). If those options are used but C<NotifyAccess> is
833             not configured, it will be implicitly set to C<main>.
834              
835             Note that sd_notify() notifications may be attributed to units correctly only if
836             either the sending process is still around at the time PID 1 processes the message, or if the sending process
837             is explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally
838             forked off the process, i.e. on all processes that match C<main> or
839             C<exec>. Conversely, if an auxiliary process of the unit sends an
840             sd_notify() message and immediately exits, the service manager might not be able to
841             properly attribute the message to the unit, and thus will ignore it, even if
842             C<NotifyAccess>C<all> is set for it.
843              
844             Hence, to eliminate all race conditions involving lookup of the client\'s unit and attribution of notifications
845             to units correctly, sd_notify_barrier() may be used. This call acts as a synchronization point
846             and ensures all notifications sent before this call have been picked up by the service manager when it returns
847             successfully. Use of sd_notify_barrier() is needed for clients which are not invoked by the
848             service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the
849             unit.',
850             'type' => 'leaf',
851             'value_type' => 'enum'
852             },
853             'Sockets',
854             {
855             'description' => 'Specifies the name of the socket units this
856             service shall inherit socket file descriptors from when the
857             service is started. Normally, it should not be necessary to use
858             this setting, as all socket file descriptors whose unit shares
859             the same name as the service (subject to the different unit
860             name suffix of course) are passed to the spawned
861             process.
862              
863             Note that the same socket file descriptors may be passed
864             to multiple processes simultaneously. Also note that a
865             different service may be activated on incoming socket traffic
866             than the one which is ultimately configured to inherit the
867             socket file descriptors. Or, in other words: the
868             C<Service> setting of
869             C<.socket> units does not have to match the
870             inverse of the C<Sockets> setting of the
871             C<.service> it refers to.
872              
873             This option may appear more than once, in which case the list of socket units is merged. Note
874             that once set, clearing the list of sockets again (for example, by assigning the empty string to this
875             option) is not supported.',
876             'type' => 'leaf',
877             'value_type' => 'uniline'
878             },
879             'FileDescriptorStoreMax',
880             {
881             'description' => 'Configure how many file descriptors may be stored in the service manager for the
882             service using
883             L<sd_pid_notify_with_fds(3)>\'s
884             C<FDSTORE=1> messages. This is useful for implementing services that can restart
885             after an explicit request or a crash without losing state. Any open sockets and other file
886             descriptors which should not be closed during the restart may be stored this way. Application state
887             can either be serialized to a file in C</run/>, or better, stored in a
888             L<memfd_create(2)>
889             memory file descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service
890             manager. All file descriptors passed to the service manager from a specific service are passed back
891             to the service\'s main process on the next service restart (see
892             L<sd_listen_fds(3)> for
893             details about the precise protocol used and the order in which the file descriptors are passed). Any
894             file descriptors passed to the service manager are automatically closed when
895             C<POLLHUP> or C<POLLERR> is seen on them, or when the service is
896             fully stopped and no job is queued or being executed for it. If this option is used,
897             C<NotifyAccess> (see above) should be set to open access to the notification socket
898             provided by systemd. If C<NotifyAccess> is not set, it will be implicitly set to
899             C<main>.',
900             'type' => 'leaf',
901             'value_type' => 'uniline'
902             },
903             'USBFunctionDescriptors',
904             {
905             'description' => 'Configure the location of a file containing
906             L<USB
907             FunctionFS|https://www.kernel.org/doc/Documentation/usb/functionfs.txt> descriptors, for implementation of USB
908             gadget functions. This is used only in conjunction with a
909             socket unit with C<ListenUSBFunction>
910             configured. The contents of this file are written to the
911             C<ep0> file after it is
912             opened.',
913             'type' => 'leaf',
914             'value_type' => 'uniline'
915             },
916             'USBFunctionStrings',
917             {
918             'description' => 'Configure the location of a file containing
919             USB FunctionFS strings. Behavior is similar to
920             C<USBFunctionDescriptors>
921             above.',
922             'type' => 'leaf',
923             'value_type' => 'uniline'
924             },
925             'OOMPolicy',
926             {
927             'description' => 'Configure the out-of-memory (OOM) kernel killer policy. Note that the userspace OOM
928             killer
929             L<systemd-oomd.service(8)>
930             is a more flexible solution that aims to prevent out-of-memory situations for the userspace, not just
931             the kernel.
932              
933             On Linux, when memory becomes scarce to the point that the kernel has trouble allocating memory
934             for itself, it might decide to kill a running process in order to free up memory and reduce memory
935             pressure. This setting takes one of C<continue>, C<stop> or
936             C<kill>. If set to C<continue> and a process of the service is
937             killed by the kernel\'s OOM killer this is logged but the service continues running. If set to
938             C<stop> the event is logged but the service is terminated cleanly by the service
939             manager. If set to C<kill> and one of the service\'s processes is killed by the OOM
940             killer the kernel is instructed to kill all remaining processes of the service too, by setting the
941             C<memory.oom.group> attribute to C<1>; also see L<kernel documentation|https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html>.
942              
943             Defaults to the setting C<DefaultOOMPolicy> in
944             L<systemd-system.conf(5)>
945             is set to, except for services where C<Delegate> is turned on, where it defaults to
946             C<continue>.
947              
948             Use the C<OOMScoreAdjust> setting to configure whether processes of the unit
949             shall be considered preferred or less preferred candidates for process termination by the Linux OOM
950             killer logic. See
951             L<systemd.exec(5)> for
952             details.
953              
954             This setting also applies to systemd-oomd, similar to the kernel OOM kills
955             this setting determines the state of the service after systemd-oomd kills a cgroup
956             associated with the service.',
957             'type' => 'leaf',
958             'value_type' => 'uniline'
959             },
960             'FailureAction',
961             {
962             'status' => 'deprecated',
963             'type' => 'leaf',
964             'value_type' => 'uniline',
965             'warn' => 'FailureAction is now part of Unit.'
966             },
967             'SuccessAction',
968             {
969             'status' => 'deprecated',
970             'type' => 'leaf',
971             'value_type' => 'uniline',
972             'warn' => 'SuccessAction is now part of Unit.'
973             },
974             'StartLimitBurst',
975             {
976             'status' => 'deprecated',
977             'type' => 'leaf',
978             'value_type' => 'uniline',
979             'warn' => 'StartLimitBurst is now part of Unit.'
980             },
981             'StartLimitInterval',
982             {
983             'status' => 'deprecated',
984             'type' => 'leaf',
985             'value_type' => 'uniline',
986             'warn' => 'service/StartLimitInterval is now Unit/StartLimitIntervalSec.'
987             },
988             'RebootArgument',
989             {
990             'status' => 'deprecated',
991             'type' => 'leaf',
992             'value_type' => 'uniline',
993             'warn' => 'RebootArgument is now part of Unit.'
994             }
995             ],
996             'generated_by' => 'parse-man.pl from systemd doc',
997             'include' => [
998             'Systemd::Common::ResourceControl',
999             'Systemd::Common::Exec',
1000             'Systemd::Common::Kill'
1001             ],
1002             'license' => 'LGPLv2.1+',
1003             'name' => 'Systemd::Section::Service'
1004             }
1005             ]
1006             ;
1007