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