Debian Codegraph @

upstream/opensuse-tumbleweed/man5/systemd.service.5

raw
1 '\" t
2 .TH "SYSTEMD\&.SERVICE" "5" "" "systemd 260.1" "systemd.service"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd.service \- Service unit configuration
24 .SH "SYNOPSIS"
25 .PP
26 \fIservice\fR\&.service
27 .SH "DESCRIPTION"
28 .PP
29 A unit configuration file whose name ends in
30 "\&.service"
31 encodes information about a process controlled and supervised by systemd\&.
32 .PP
33 This man page lists the configuration options specific to this unit type\&. See
34 \fBsystemd.unit\fR(5)
35 for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. The service specific configuration options are configured in the [Service] section\&.
36 .PP
37 Additional options are listed in
38 \fBsystemd.exec\fR(5), which define the execution environment the commands are executed in, and in
39 \fBsystemd.kill\fR(5), which define the way the processes of the service are terminated, and in
40 \fBsystemd.resource-control\fR(5), which configure resource control settings for the processes of the service\&.
41 .PP
42 The
43 \fBsystemd-run\fR(1)
44 command allows creating
45 \&.service
46 and
47 \&.scope
48 units dynamically and transiently from the command line\&.
49 .SH "SERVICE TEMPLATES"
50 .PP
51 It is possible for
52 \fBsystemd\fR
53 services to take a single argument via the
54 "\fIservice\fR@\fIargument\fR\&.service"
55 syntax\&. Such services are called "instantiated" services, while the unit definition without the
56 \fIargument\fR
57 parameter is called a "template"\&. An example could be a
58 dhcpcd@\&.service
59 service template which takes a network interface as a parameter to form an instantiated service\&. Within the service file, this parameter or "instance name" can be accessed with %\-specifiers\&. See
60 \fBsystemd.unit\fR(5)
61 for details\&.
62 .SH "AUTOMATIC DEPENDENCIES"
63 .SS "Implicit Dependencies"
64 .PP
65 The following dependencies are implicitly added:
66 .sp
67 .RS 4
68 .ie n \{\
69 \h'-04'\(bu\h'+03'\c
70 .\}
71 .el \{\
72 .sp -1
73 .IP \(bu 2.3
74 .\}
75 Services with
76 \fIType=dbus\fR
77 set automatically acquire dependencies of type
78 \fIRequires=\fR
79 and
80 \fIAfter=\fR
81 on
82 dbus\&.socket\&.
83 .RE
84 .sp
85 .RS 4
86 .ie n \{\
87 \h'-04'\(bu\h'+03'\c
88 .\}
89 .el \{\
90 .sp -1
91 .IP \(bu 2.3
92 .\}
93 Socket activated services are automatically ordered after their activating
94 \&.socket
95 units via an automatic
96 \fIAfter=\fR
97 dependency\&. Services also pull in all
98 \&.socket
99 units listed in
100 \fISockets=\fR
101 via automatic
102 \fIWants=\fR
103 and
104 \fIAfter=\fR
105 dependencies\&.
106 .RE
107 .PP
108 Additional implicit dependencies may be added as result of execution and resource control parameters as documented in
109 \fBsystemd.exec\fR(5)
110 and
111 \fBsystemd.resource-control\fR(5)\&.
112 .SS "Default Dependencies"
113 .PP
114 The following dependencies are added unless
115 \fIDefaultDependencies=no\fR
116 is set:
117 .sp
118 .RS 4
119 .ie n \{\
120 \h'-04'\(bu\h'+03'\c
121 .\}
122 .el \{\
123 .sp -1
124 .IP \(bu 2.3
125 .\}
126 Service units will have dependencies of type
127 \fIRequires=\fR
128 and
129 \fIAfter=\fR
130 on
131 sysinit\&.target, a dependency of type
132 \fIAfter=\fR
133 on
134 basic\&.target
135 as well as dependencies of type
136 \fIConflicts=\fR
137 and
138 \fIBefore=\fR
139 on
140 shutdown\&.target\&. These ensure that normal service units pull in basic system initialization, and are terminated cleanly prior to system shutdown\&. Only services involved with early boot or late system shutdown should disable this option\&.
141 .RE
142 .sp
143 .RS 4
144 .ie n \{\
145 \h'-04'\(bu\h'+03'\c
146 .\}
147 .el \{\
148 .sp -1
149 .IP \(bu 2.3
150 .\}
151 Instanced service units (i\&.e\&. service units with an
152 "@"
153 in their name) are assigned by default a per\-template slice unit (see
154 \fBsystemd.slice\fR(5)), named after the template unit, containing all instances of the specific template\&. This slice is normally stopped at shutdown, together with all template instances\&. If that is not desired, set
155 \fIDefaultDependencies=no\fR
156 in the template unit, and either define your own per\-template slice unit file that also sets
157 \fIDefaultDependencies=no\fR, or set
158 \fISlice=system\&.slice\fR
159 (or another suitable slice) in the template unit\&. Also see
160 \fBsystemd.resource-control\fR(5)\&.
161 .RE
162 .SH "OPTIONS"
163 .PP
164 Service unit files may include [Unit] and [Install] sections, which are described in
165 \fBsystemd.unit\fR(5)\&.
166 .PP
167 Service unit files must include a [Service] section, which carries information about the service and the process it supervises\&. A number of options that may be used in this section are shared with other unit types\&. These options are documented in
168 \fBsystemd.exec\fR(5),
169 \fBsystemd.kill\fR(5)
170 and
171 \fBsystemd.resource-control\fR(5)\&. The options specific to the [Service] section of service units are the following:
172 .PP
173 \fIType=\fR
174 .RS 4
175 Configures the mechanism via which the service notifies the manager that the service start\-up has finished\&. One of
176 \fBsimple\fR,
177 \fBexec\fR,
178 \fBforking\fR,
179 \fBoneshot\fR,
180 \fBdbus\fR,
181 \fBnotify\fR,
182 \fBnotify\-reload\fR, or
183 \fBidle\fR:
184 .sp
185 .RS 4
186 .ie n \{\
187 \h'-04'\(bu\h'+03'\c
188 .\}
189 .el \{\
190 .sp -1
191 .IP \(bu 2.3
192 .\}
193 If set to
194 \fBsimple\fR
195 (the default if
196 \fIExecStart=\fR
197 is specified but neither
198 \fIType=\fR
199 nor
200 \fIBusName=\fR
201 are, and credentials are not used), the service manager will consider the unit started immediately after the main service process has been forked off (i\&.e\&. immediately after
202 \fBfork()\fR, and before various process attributes have been configured and in particular before the new process has called
203 \fBexecve()\fR
204 to invoke the actual service binary)\&. Typically,
205 \fIType=\fR\fBexec\fR
206 is the better choice, see below\&.
207 .sp
208 It is expected that the process configured with
209 \fIExecStart=\fR
210 is the main process of the service\&. In this mode, if the process offers functionality to other processes on the system, its communication channels should be installed before the service is started up (e\&.g\&. sockets set up by systemd, via socket activation), as the service manager will immediately proceed starting follow\-up units, right after creating the main service process, and before executing the service\*(Aqs binary\&. Note that this means
211 \fBsystemctl start\fR
212 command lines for
213 \fBsimple\fR
214 services will report success even if the service\*(Aqs binary cannot be invoked successfully (for example because the selected
215 \fIUser=\fR
216 does not exist, or the service binary is missing)\&.
217 .RE
218 .sp
219 .RS 4
220 .ie n \{\
221 \h'-04'\(bu\h'+03'\c
222 .\}
223 .el \{\
224 .sp -1
225 .IP \(bu 2.3
226 .\}
227 The
228 \fBexec\fR
229 type is similar to
230 \fBsimple\fR, but the service manager will consider the unit started immediately after the main service binary has been executed\&. The service manager will delay starting of follow\-up units until that point\&. (Or in other words:
231 \fBsimple\fR
232 proceeds with further jobs right after
233 \fBfork()\fR
234 returns, while
235 \fBexec\fR
236 will not proceed before both
237 \fBfork()\fR
238 and
239 \fBexecve()\fR
240 in the service process succeeded\&.) Note that this means
241 \fBsystemctl start\fR
242 command lines for
243 \fBexec\fR
244 services will report failure when the service\*(Aqs binary cannot be invoked successfully (for example because the selected
245 \fIUser=\fR
246 does not exist, or the service binary is missing)\&. This type is implied if credentials are used (refer to
247 \fILoadCredential=\fR
248 in
249 \fBsystemd.exec\fR(5)
250 for details)\&.
251 .RE
252 .sp
253 .RS 4
254 .ie n \{\
255 \h'-04'\(bu\h'+03'\c
256 .\}
257 .el \{\
258 .sp -1
259 .IP \(bu 2.3
260 .\}
261 If set to
262 \fBforking\fR, the manager will consider the unit started immediately after the binary that forked off by the manager exits\&.
263 \fIThe use of this type is discouraged, use \fR\fI\fBnotify\fR\fR\fI, \fR\fI\fBnotify\-reload\fR\fR\fI, or \fR\fI\fBdbus\fR\fR\fI instead\&.\fR
264 .sp
265 It is expected that the process configured with
266 \fIExecStart=\fR
267 will call
268 \fBfork()\fR
269 as part of its start\-up\&. The parent process is expected to exit when start\-up is complete and all communication channels are set up\&. The child continues to run as the main service process, and the service manager will consider the unit started when the parent process exits\&. This is the behavior of traditional UNIX services\&. If this setting is used, it is recommended to also use the
270 \fIPIDFile=\fR
271 option, so that systemd can reliably identify the main process of the service\&. The manager will proceed with starting follow\-up units after the parent process exits\&.
272 .RE
273 .sp
274 .RS 4
275 .ie n \{\
276 \h'-04'\(bu\h'+03'\c
277 .\}
278 .el \{\
279 .sp -1
280 .IP \(bu 2.3
281 .\}
282 Behavior of
283 \fBoneshot\fR
284 is similar to
285 \fBexec\fR; however, the service manager will consider the unit up after the main process exits\&. It will then start follow\-up units\&.
286 \fIRemainAfterExit=\fR
287 is particularly useful for this type of service\&.
288 \fIType=\fR\fBoneshot\fR
289 is the implied default if neither
290 \fIType=\fR
291 nor
292 \fIExecStart=\fR
293 are specified\&. Note that if this option is used without
294 \fIRemainAfterExit=\fR
295 the service will never enter
296 "active"
297 unit state, but will directly transition from
298 "activating"
299 to
300 "deactivating"
301 or
302 "dead", since no process is configured that shall run continuously\&. In particular this means that after a service of this type ran (and which has
303 \fIRemainAfterExit=\fR
304 not set) it will not show up as started afterwards, but as dead\&.
305 .RE
306 .sp
307 .RS 4
308 .ie n \{\
309 \h'-04'\(bu\h'+03'\c
310 .\}
311 .el \{\
312 .sp -1
313 .IP \(bu 2.3
314 .\}
315 Behavior of
316 \fBdbus\fR
317 is similar to
318 \fBsimple\fR; however, units of this type must have the
319 \fIBusName=\fR
320 specified and the service manager will consider the unit up when the specified bus name has been acquired\&. This type is the default if
321 \fIBusName=\fR
322 is specified\&.
323 .sp
324 Service units with this option configured implicitly gain dependencies on the
325 dbus\&.socket
326 unit\&. A service unit of this type is considered to be in the activating state until the specified bus name is acquired\&. It is considered activated while the bus name is taken\&. Once the bus name is released the service is considered being no longer functional which has the effect that the service manager attempts to terminate any remaining processes belonging to the service\&. Services that drop their bus name as part of their shutdown logic thus should be prepared to receive a
327 \fBSIGTERM\fR
328 (or whichever signal is configured in
329 \fIKillSignal=\fR) as result\&.
330 .RE
331 .sp
332 .RS 4
333 .ie n \{\
334 \h'-04'\(bu\h'+03'\c
335 .\}
336 .el \{\
337 .sp -1
338 .IP \(bu 2.3
339 .\}
340 Behavior of
341 \fBnotify\fR
342 is similar to
343 \fBexec\fR; however, it is expected that the service sends a
344 "READY=1"
345 notification message via
346 \fBsd_notify\fR(3)
347 or an equivalent call when it has finished starting up\&. systemd will proceed with starting follow\-up units after this notification message has been sent\&. If this option is used,
348 \fINotifyAccess=\fR
349 (see below) should be set to open access to the notification socket provided by systemd\&. If
350 \fINotifyAccess=\fR
351 is missing or set to
352 \fBnone\fR, it will be forcibly set to
353 \fBmain\fR\&.
354 .sp
355 If the service supports reloading, and uses a signal to start the reload, using
356 \fBnotify\-reload\fR
357 instead is recommended\&.
358 .RE
359 .sp
360 .RS 4
361 .ie n \{\
362 \h'-04'\(bu\h'+03'\c
363 .\}
364 .el \{\
365 .sp -1
366 .IP \(bu 2.3
367 .\}
368 Behavior of
369 \fBnotify\-reload\fR
370 is similar to
371 \fBnotify\fR, with one difference: the
372 \fBSIGHUP\fR
373 UNIX process signal is sent to the service\*(Aqs main process when the service is asked to reload and the manager will wait for a notification about the reload being finished\&.
374 .sp
375 When initiating the reload process the service is expected to reply with a notification message via
376 \fBsd_notify\fR(3)
377 that contains the
378 "RELOADING=1"
379 field in combination with
380 "MONOTONIC_USEC="
381 set to the current monotonic time (i\&.e\&.
382 \fBCLOCK_MONOTONIC\fR
383 in
384 \fBclock_gettime\fR(2)) in μs, formatted as decimal string\&. Once reloading is complete another notification message must be sent, containing
385 "READY=1"\&. Using this service type and implementing this reload protocol is an efficient alternative to providing an
386 \fIExecReload=\fR
387 command for reloading of the service\*(Aqs configuration\&.
388 .sp
389 The signal to send can be tweaked via
390 \fIReloadSignal=\fR, see below\&.
391 .RE
392 .sp
393 .RS 4
394 .ie n \{\
395 \h'-04'\(bu\h'+03'\c
396 .\}
397 .el \{\
398 .sp -1
399 .IP \(bu 2.3
400 .\}
401 Behavior of
402 \fBidle\fR
403 is very similar to
404 \fBsimple\fR; however, actual execution of the service program is delayed until all active jobs are dispatched\&. This may be used to avoid interleaving of output of shell services with the status output on the console\&. Note that this type is useful only to improve console output, it is not useful as a general unit ordering tool, and the effect of this service type is subject to a 5s timeout, after which the service program is invoked anyway\&.
405 .RE
406 .sp
407 It is recommended to use
408 \fIType=\fR\fBexec\fR
409 for long\-running services, as it ensures that process setup errors (e\&.g\&. errors such as a missing service executable, or missing user) are properly tracked\&. However, as this service type will not propagate the failures in the service\*(Aqs own startup code (as opposed to failures in the preparatory steps the service manager executes before
410 \fBexecve()\fR) and does not allow ordering of other units against completion of initialization of the service code itself (which for example is useful if clients need to connect to the service through some form of IPC, and the IPC channel is only established by the service itself \(em in contrast to doing this ahead of time through socket or bus activation or similar), it might not be sufficient for many cases\&. If so,
411 \fBnotify\fR,
412 \fBnotify\-reload\fR, or
413 \fBdbus\fR
414 (the latter only in case the service provides a D\-Bus interface) are the preferred options as they allow service program code to precisely schedule when to consider the service started up successfully and when to proceed with follow\-up units\&. The
415 \fBnotify\fR/\fBnotify\-reload\fR
416 service types require explicit support in the service codebase (as
417 \fBsd_notify()\fR
418 or an equivalent API needs to be invoked by the service at the appropriate time) \(em if it is not supported, then
419 \fBforking\fR
420 is an alternative: it supports the traditional heavy\-weight UNIX service start\-up protocol\&. Note that using any type other than
421 \fBsimple\fR
422 possibly delays the boot process, as the service manager needs to wait for at least some service initialization to complete\&. (Also note it is generally not recommended to use
423 \fBidle\fR
424 or
425 \fBoneshot\fR
426 for long\-running services\&.)
427 .sp
428 Note that various service settings (e\&.g\&.
429 \fIUser=\fR,
430 \fIGroup=\fR
431 through libc NSS) might result in "hidden" blocking IPC calls to other services when used\&. Sometimes it might be advisable to use the
432 \fBsimple\fR
433 service type to ensure that the service manager\*(Aqs transaction logic is not affected by such potentially slow operations and hidden dependencies, as this is the only service type where the service manager will not wait for such service execution setup operations to complete before proceeding\&.
434 .RE
435 .PP
436 \fIExitType=\fR
437 .RS 4
438 Specifies when the manager should consider the service to be finished\&. One of
439 \fBmain\fR
440 or
441 \fBcgroup\fR:
442 .sp
443 .RS 4
444 .ie n \{\
445 \h'-04'\(bu\h'+03'\c
446 .\}
447 .el \{\
448 .sp -1
449 .IP \(bu 2.3
450 .\}
451 If set to
452 \fBmain\fR
453 (the default), the service manager will consider the unit stopped when the main process, which is determined according to the
454 \fIType=\fR, exits\&. Consequently, it cannot be used with
455 \fIType=\fR\fBoneshot\fR\&.
456 .RE
457 .sp
458 .RS 4
459 .ie n \{\
460 \h'-04'\(bu\h'+03'\c
461 .\}
462 .el \{\
463 .sp -1
464 .IP \(bu 2.3
465 .\}
466 If set to
467 \fBcgroup\fR, the service will be considered running as long as at least one process in the cgroup has not exited\&.
468 .RE
469 .sp
470 It is generally recommended to use
471 \fIExitType=\fR\fBmain\fR
472 when a service has a known forking model and a main process can reliably be determined\&.
473 \fIExitType=\fR
474 \fBcgroup\fR
475 is meant for applications whose forking model is not known ahead of time and which might not have a specific main process\&. It is well suited for transient or automatically generated services, such as graphical applications inside of a desktop environment\&.
476 .sp
477 Added in version 250\&.
478 .RE
479 .PP
480 \fIRemainAfterExit=\fR
481 .RS 4
482 Takes a boolean value that specifies whether the service shall be considered active even when all its processes exited\&. Defaults to
483 \fBno\fR\&.
484 .RE
485 .PP
486 \fIGuessMainPID=\fR
487 .RS 4
488 Takes a boolean value that specifies whether systemd should try to guess the main PID of a service if it cannot be determined reliably\&. This option is ignored unless
489 \fBType=forking\fR
490 is set and
491 \fBPIDFile=\fR
492 is unset because for the other types or with an explicitly configured PID file, the main PID is always known\&. The guessing algorithm might come to incorrect conclusions if a daemon consists of more than one process\&. If the main PID cannot be determined, failure detection and automatic restarting of a service will not work reliably\&. Defaults to
493 \fByes\fR\&.
494 .RE
495 .PP
496 \fIPIDFile=\fR
497 .RS 4
498 Takes a path referring to the PID file of the service\&. Usage of this option is recommended for services where
499 \fIType=\fR
500 is set to
501 \fBforking\fR\&. The path specified typically points to a file below
502 /run/\&. If a relative path is specified for system service, then it is hence prefixed with
503 /run/, and prefixed with
504 $XDG_RUNTIME_DIR
505 if specified in a user service\&. The service manager will read the PID of the main process of the service from this file after start\-up of the service\&. The service manager will not write to the file configured here, although it will remove the file after the service has shut down if it still exists\&. The PID file does not need to be owned by a privileged user, but if it is owned by an unprivileged user additional safety restrictions are enforced: the file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and the PID file must refer to a process already belonging to the service\&.
506 .sp
507 Note that PID files should be avoided in modern projects\&. Use
508 \fBType=notify\fR,
509 \fBType=notify\-reload\fR
510 or
511 \fBType=simple\fR
512 where possible, which does not require use of PID files to determine the main process of a service and avoids needless forking\&.
513 .RE
514 .PP
515 \fIBusName=\fR
516 .RS 4
517 Takes a D\-Bus destination name that this service shall use\&. This option is mandatory for services where
518 \fIType=\fR
519 is set to
520 \fBdbus\fR\&. It is recommended to always set this property if known to make it easy to map the service name to the D\-Bus destination\&. In particular,
521 \fBsystemctl service\-log\-level/service\-log\-target\fR
522 verbs make use of this\&.
523 .RE
524 .PP
525 \fIExecStart=\fR
526 .RS 4
527 Commands that are executed when this service is started\&.
528 .sp
529 Unless
530 \fIType=\fR
531 is
532 \fBoneshot\fR, exactly one command must be given\&. When
533 \fIType=oneshot\fR
534 is used, this setting may be used multiple times to define multiple commands to execute\&. If the empty string is assigned to this option, the list of commands to start is reset, prior assignments of this option will have no effect\&. If no
535 \fIExecStart=\fR
536 is specified, then the service must have
537 \fIRemainAfterExit=yes\fR
538 and at least one
539 \fIExecStop=\fR
540 line set\&. (Services lacking both
541 \fIExecStart=\fR
542 and
543 \fIExecStop=\fR
544 are not valid\&.)
545 .sp
546 If more than one command is configured, the commands are invoked sequentially in the order they appear in the unit file\&. If one of the commands fails (and is not prefixed with
547 "\-"), other lines are not executed, and the unit is considered failed\&.
548 .sp
549 Unless
550 \fIType=forking\fR
551 is set, the process started via this command line will be considered the main process of the daemon\&.
552 .RE
553 .PP
554 \fIExecStartPre=\fR, \fIExecStartPost=\fR
555 .RS 4
556 Additional commands that are executed before or after the command in
557 \fIExecStart=\fR, respectively\&. Syntax is the same as for
558 \fIExecStart=\fR\&. Multiple command lines are allowed, regardless of the service type (i\&.e\&.
559 \fIType=\fR), and the commands are executed one after the other, serially\&.
560 .sp
561 If any of those commands (not prefixed with
562 "\-") fail, the rest are not executed and the unit is considered failed\&.
563 .sp
564 \fIExecStart=\fR
565 commands are only run after all
566 \fIExecStartPre=\fR
567 commands that were not prefixed with a
568 "\-"
569 exit successfully\&.
570 .sp
571 \fIExecStartPost=\fR
572 commands are only run after the commands specified in
573 \fIExecStart=\fR
574 have been invoked successfully, as determined by
575 \fIType=\fR
576 (i\&.e\&. the process has been started for
577 \fIType=simple\fR
578 or
579 \fIType=idle\fR, the last
580 \fIExecStart=\fR
581 process exited successfully for
582 \fIType=oneshot\fR, the initial process exited successfully for
583 \fIType=forking\fR,
584 "READY=1"
585 is sent for
586 \fIType=notify\fR/\fIType=notify\-reload\fR, or the
587 \fIBusName=\fR
588 has been taken for
589 \fIType=dbus\fR)\&.
590 .sp
591 Note that
592 \fIExecStartPre=\fR
593 may not be used to start long\-running processes\&. All processes forked off by processes invoked via
594 \fIExecStartPre=\fR
595 will be killed before the next service process is run\&.
596 .sp
597 Note that if any of the commands specified in
598 \fIExecStartPre=\fR,
599 \fIExecStart=\fR, or
600 \fIExecStartPost=\fR
601 fail (and are not prefixed with
602 "\-", see above) or time out before the service is fully up, execution continues with commands specified in
603 \fIExecStopPost=\fR, the commands in
604 \fIExecStop=\fR
605 are skipped\&.
606 .sp
607 Note that the execution of
608 \fIExecStartPost=\fR
609 is taken into account for the purpose of
610 \fIBefore=\fR/\fIAfter=\fR
611 ordering constraints\&.
612 .RE
613 .PP
614 \fIExecCondition=\fR
615 .RS 4
616 Optional commands that are executed before the commands in
617 \fIExecStartPre=\fR\&. Syntax is the same as for
618 \fIExecStart=\fR\&. Multiple command lines are allowed, regardless of the service type (i\&.e\&.
619 \fIType=\fR), and the commands are executed one after the other, serially\&.
620 .sp
621 The behavior is like an
622 \fIExecStartPre=\fR
623 and condition check hybrid: when an
624 \fIExecCondition=\fR
625 command exits with exit code 1 through 254 (inclusive), the remaining commands are skipped and the unit is
626 \fInot\fR
627 marked as failed\&. However, if an
628 \fIExecCondition=\fR
629 command exits with 255 or abnormally (e\&.g\&. timeout, killed by a signal, etc\&.), the unit will be considered failed (and remaining commands will be skipped)\&. Exit code of 0 or those matching
630 \fISuccessExitStatus=\fR
631 will continue execution to the next commands\&.
632 .sp
633 The same recommendations about not running long\-running processes in
634 \fIExecStartPre=\fR
635 also applies to
636 \fIExecCondition=\fR\&.
637 \fIExecCondition=\fR
638 will also run the commands in
639 \fIExecStopPost=\fR, as part of stopping the service, in the case of any non\-zero or abnormal exits, like the ones described above\&.
640 .sp
641 Added in version 243\&.
642 .RE
643 .PP
644 \fIExecReload=\fR
645 .RS 4
646 Commands to execute to trigger a configuration reload in the service\&. This setting may take multiple command lines, following the same scheme as described for
647 \fIExecStart=\fR
648 above\&. Use of this setting is optional\&. Specifier and environment variable substitution is supported here following the same scheme as for
649 \fIExecStart=\fR\&.
650 .sp
651 One additional, special environment variable is set: if known,
652 \fI$MAINPID\fR
653 is set to the main process of the daemon, and may be used for command lines like the following:
654 .sp
655 .if n \{\
656 .RS 4
657 .\}
658 .nf
659 ExecReload=kill \-HUP $MAINPID
660 .fi
661 .if n \{\
662 .RE
663 .\}
664 .sp
665 Note however that reloading a daemon by enqueuing a signal without completion notification (as is the case with the example line above) is usually not a good choice, because this is an asynchronous operation and hence not suitable when ordering reloads of multiple services against each other\&. It is thus strongly recommended to either use
666 \fIType=notify\-reload\fR, or to set
667 \fIExecReload=\fR
668 to a command that not only triggers a configuration reload of the daemon, but also synchronously waits for it to complete\&. For example,
669 \fBdbus-broker\fR(1)
670 uses the following:
671 .sp
672 .if n \{\
673 .RS 4
674 .\}
675 .nf
676 ExecReload=busctl call org\&.freedesktop\&.DBus \e
677 /org/freedesktop/DBus org\&.freedesktop\&.DBus \e
678 ReloadConfig
679 .fi
680 .if n \{\
681 .RE
682 .\}
683 .sp
684 This setting can be combined with
685 \fIType=notify\-reload\fR, in which case the service main process is signaled after all specified command lines finish execution\&. Specially, if
686 "RELOADING=1"
687 notification is received before
688 \fIExecReload=\fR
689 completes, the signaling is skipped and the service manager immediately starts listening for
690 "READY=1"\&.
691 .RE
692 .PP
693 \fIExecReloadPost=\fR
694 .RS 4
695 Commands to execute after a successful reload operation\&. Syntax for this setting is exactly the same as
696 \fIExecReload=\fR\&.
697 .sp
698 Added in version 259\&.
699 .RE
700 .PP
701 \fIExecStop=\fR
702 .RS 4
703 Commands to execute to stop the service started via
704 \fIExecStart=\fR\&. This argument takes multiple command lines, following the same scheme as described for
705 \fIExecStart=\fR
706 above\&. Use of this setting is optional\&. After the commands configured in this option are run, it is implied that the service is stopped, and any processes remaining for it are terminated according to the
707 \fIKillMode=\fR
708 setting (see
709 \fBsystemd.kill\fR(5))\&. If this option is not specified, the process is terminated by sending the signal specified in
710 \fIKillSignal=\fR
711 or
712 \fIRestartKillSignal=\fR
713 when service stop is requested\&. Specifier and environment variable substitution is supported (including
714 \fI$MAINPID\fR, see above)\&.
715 .sp
716 Note that it is usually not sufficient to specify a command for this setting that only asks the service to terminate (for example, by sending some form of termination signal to it), but does not wait for it to do so\&. Since the remaining processes of the services are killed according to
717 \fIKillMode=\fR
718 and
719 \fIKillSignal=\fR
720 or
721 \fIRestartKillSignal=\fR
722 as described above immediately after the command exited, this may not result in a clean stop\&. The specified command should hence be a synchronous operation, not an asynchronous one\&.
723 .sp
724 Note that the commands specified in
725 \fIExecStop=\fR
726 are only executed when the service started successfully first\&. They are not invoked if the service was never started at all, or in case its start\-up failed, for example because any of the commands specified in
727 \fIExecStart=\fR,
728 \fIExecStartPre=\fR
729 or
730 \fIExecStartPost=\fR
731 failed (and were not prefixed with
732 "\-", see above) or timed out\&. Use
733 \fIExecStopPost=\fR
734 to invoke commands when a service failed to start up correctly and is shut down again\&. Also note that the stop operation is always performed if the service started successfully, even if the processes in the service terminated on their own or were killed\&. The stop commands must be prepared to deal with that case\&.
735 \fI$MAINPID\fR
736 will be unset if systemd knows that the main process exited by the time the stop commands are called\&.
737 .sp
738 Service restart requests are implemented as stop operations followed by start operations\&. This means that
739 \fIExecStop=\fR
740 and
741 \fIExecStopPost=\fR
742 are executed during a service restart operation\&.
743 .sp
744 It is recommended to use this setting for commands that communicate with the service requesting clean termination\&. For post\-mortem clean\-up steps use
745 \fIExecStopPost=\fR
746 instead\&.
747 .RE
748 .PP
749 \fIExecStopPost=\fR
750 .RS 4
751 Additional commands that are executed after the service is stopped\&. This includes cases where the commands configured in
752 \fIExecStop=\fR
753 were used, where the service does not have any
754 \fIExecStop=\fR
755 defined, or where the service exited unexpectedly\&. This argument takes multiple command lines, following the same scheme as described for
756 \fIExecStart=\fR\&. Use of these settings is optional\&. Specifier and environment variable substitution is supported\&. Note that \(en unlike
757 \fIExecStop=\fR
758 \(en commands specified with this setting are invoked when a service failed to start up correctly and is shut down again\&.
759 .sp
760 It is recommended to use this setting for clean\-up operations that shall be executed even when the service failed to start up correctly\&. Commands configured with this setting need to be able to operate even if the service failed starting up half\-way and left incompletely initialized data around\&. As the service\*(Aqs processes have likely exited already when the commands specified with this setting are executed they should not attempt to communicate with them\&.
761 .sp
762 Note that all commands that are configured with this setting are invoked with the result code of the service, as well as the main process\*(Aq exit code and status, set in the
763 \fI$SERVICE_RESULT\fR,
764 \fI$EXIT_CODE\fR
765 and
766 \fI$EXIT_STATUS\fR
767 environment variables, see
768 \fBsystemd.exec\fR(5)
769 for details\&.
770 .sp
771 Note that the execution of
772 \fIExecStopPost=\fR
773 is taken into account for the purpose of
774 \fIBefore=\fR/\fIAfter=\fR
775 ordering constraints\&.
776 .RE
777 .PP
778 \fIRestartSec=\fR
779 .RS 4
780 Configures the time to sleep before restarting a service (as configured with
781 \fIRestart=\fR)\&. Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Defaults to 100ms\&.
782 .RE
783 .PP
784 \fIRestartSteps=\fR
785 .RS 4
786 Configures the number of exponential steps to take to increase the interval of auto\-restarts from
787 \fIRestartSec=\fR
788 to
789 \fIRestartMaxDelaySec=\fR\&. Takes a positive integer or 0 to disable it\&. Defaults to 0\&.
790 \fIHint:\fR
791 values between 3 and 5 are good choices when exponential backoff is desired\&.
792 .sp
793 Example:
794 .sp
795 .if n \{\
796 .RS 4
797 .\}
798 .nf
799 RestartSec=10s
800 RestartSteps=4
801 RestartMaxDelaySec=160s
802 .fi
803 .if n \{\
804 .RE
805 .\}
806 .sp
807 This will produce the following restart intervals: 10s, 20s, 40s, 80s, 160s, 160s, 160s, etc\&. Notice the geometric interpolation and the resulting constant ratio between intervals; here it is 2\&. The formula for the
808 \fIratio\fR
809 is
810 (\fIRestartMaxDelaySec\fR / \fIRestartSec\fR)^(1 / \fIRestartSteps\fR)\&. A (repeating) delay equal to
811 \fIRestartMaxDelaySec=\fR
812 is always reached after
813 \fIRestartSteps\fR + 1
814 steps\&.
815 .sp
816 This setting is effective only if
817 \fIRestartMaxDelaySec=\fR
818 is also set and
819 \fIRestartSec=\fR
820 is not zero\&.
821 .sp
822 Added in version 254\&.
823 .RE
824 .PP
825 \fIRestartMaxDelaySec=\fR
826 .RS 4
827 Configures the longest time to sleep before restarting a service as the interval goes up with
828 \fIRestartSteps=\fR\&. Takes a value in the same format as
829 \fIRestartSec=\fR, or
830 "infinity"
831 to disable the setting\&. Defaults to
832 "infinity"\&.
833 .sp
834 This setting is effective only if
835 \fIRestartSteps=\fR
836 is also set and
837 \fIRestartSec=\fR
838 is not zero\&.
839 .sp
840 Added in version 254\&.
841 .RE
842 .PP
843 \fITimeoutStartSec=\fR
844 .RS 4
845 Configures the time to wait for start\-up\&. If a daemon service does not signal start\-up completion within the configured time, the service will be considered failed and will be shut down again\&. The precise action depends on the
846 \fITimeoutStartFailureMode=\fR
847 option\&. Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass
848 "infinity"
849 to disable the timeout logic\&. Defaults to
850 \fIDefaultTimeoutStartSec=\fR
851 set in the manager, except when
852 \fIType=oneshot\fR
853 is used, in which case the timeout is disabled by default (see
854 \fBsystemd-system.conf\fR(5))\&.
855 .sp
856 If a service of
857 \fIType=notify\fR/\fIType=notify\-reload\fR
858 sends
859 "EXTEND_TIMEOUT_USEC=\&...", this may cause the start time to be extended beyond
860 \fITimeoutStartSec=\fR\&. The first receipt of this message must occur before
861 \fITimeoutStartSec=\fR
862 is exceeded, and once the start time has extended beyond
863 \fITimeoutStartSec=\fR, the service manager will allow the service to continue to start, provided the service repeats
864 "EXTEND_TIMEOUT_USEC=\&..."
865 within the interval specified until the service startup status is finished by
866 "READY=1"\&. (see
867 \fBsd_notify\fR(3))\&.
868 .sp
869 Note that the start timeout is also applied to service reloads, regardless of whether implemented through
870 \fIExecReload=\fR
871 or via the reload logic enabled via
872 \fIType=notify\-reload\fR\&. If the reload does not complete within the configured time, the reload will be considered failed and the service will continue running with the old configuration\&. This will not affect the running service, but will be logged and will cause e\&.g\&.
873 \fBsystemctl reload\fR
874 to fail\&.
875 .sp
876 Added in version 188\&.
877 .RE
878 .PP
879 \fITimeoutStopSec=\fR
880 .RS 4
881 This option serves two purposes\&. First, it configures the time to wait for each
882 \fIExecStop=\fR
883 command\&. If any of them times out, subsequent
884 \fIExecStop=\fR
885 commands are skipped and the service will be terminated by
886 \fBSIGTERM\fR\&. If no
887 \fIExecStop=\fR
888 commands are specified, the service gets the
889 \fBSIGTERM\fR
890 immediately\&. This default behavior can be changed by the
891 \fITimeoutStopFailureMode=\fR
892 option\&. Second, it configures the time to wait for the service itself to stop\&. If it does not terminate in the specified time, it will be forcibly terminated by
893 \fBSIGKILL\fR
894 (see
895 \fIKillMode=\fR
896 in
897 \fBsystemd.kill\fR(5))\&. Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass
898 "infinity"
899 to disable the timeout logic\&. Defaults to
900 \fIDefaultTimeoutStopSec=\fR
901 from the manager configuration file (see
902 \fBsystemd-system.conf\fR(5))\&.
903 .sp
904 If a service of
905 \fIType=notify\fR/\fIType=notify\-reload\fR
906 sends
907 "EXTEND_TIMEOUT_USEC=\&...", this may cause the stop time to be extended beyond
908 \fITimeoutStopSec=\fR\&. The first receipt of this message must occur before
909 \fITimeoutStopSec=\fR
910 is exceeded, and once the stop time has extended beyond
911 \fITimeoutStopSec=\fR, the service manager will allow the service to continue to stop, provided the service repeats
912 "EXTEND_TIMEOUT_USEC=\&..."
913 within the interval specified, or terminates itself (see
914 \fBsd_notify\fR(3))\&.
915 .sp
916 Added in version 188\&.
917 .RE
918 .PP
919 \fITimeoutAbortSec=\fR
920 .RS 4
921 This option configures the time to wait for the service to terminate when it was aborted due to a watchdog timeout (see
922 \fIWatchdogSec=\fR)\&. If the service has a short
923 \fITimeoutStopSec=\fR
924 this option can be used to give the system more time to write a core dump of the service\&. Upon expiration the service will be forcibly terminated by
925 \fBSIGKILL\fR
926 (see
927 \fIKillMode=\fR
928 in
929 \fBsystemd.kill\fR(5))\&. The core file will be truncated in this case\&. Use
930 \fITimeoutAbortSec=\fR
931 to set a sensible timeout for the core dumping per service that is large enough to write all expected data while also being short enough to handle the service failure in due time\&.
932 .sp
933 Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass an empty value to skip the dedicated watchdog abort timeout handling and fall back
934 \fITimeoutStopSec=\fR\&. Pass
935 "infinity"
936 to disable the timeout logic\&. Defaults to
937 \fIDefaultTimeoutAbortSec=\fR
938 from the manager configuration file (see
939 \fBsystemd-system.conf\fR(5))\&.
940 .sp
941 If a service of
942 \fIType=notify\fR/\fIType=notify\-reload\fR
943 handles
944 \fBSIGABRT\fR
945 itself (instead of relying on the kernel to write a core dump) it can send
946 "EXTEND_TIMEOUT_USEC=\&..."
947 to extended the abort time beyond
948 \fITimeoutAbortSec=\fR\&. The first receipt of this message must occur before
949 \fITimeoutAbortSec=\fR
950 is exceeded, and once the abort time has extended beyond
951 \fITimeoutAbortSec=\fR, the service manager will allow the service to continue to abort, provided the service repeats
952 "EXTEND_TIMEOUT_USEC=\&..."
953 within the interval specified, or terminates itself (see
954 \fBsd_notify\fR(3))\&.
955 .sp
956 Added in version 243\&.
957 .RE
958 .PP
959 \fITimeoutSec=\fR
960 .RS 4
961 A shorthand for configuring both
962 \fITimeoutStartSec=\fR
963 and
964 \fITimeoutStopSec=\fR
965 to the specified value\&.
966 .RE
967 .PP
968 \fITimeoutStartFailureMode=\fR, \fITimeoutStopFailureMode=\fR
969 .RS 4
970 These options configure the action that is taken in case a daemon service does not signal start\-up within its configured
971 \fITimeoutStartSec=\fR, respectively if it does not stop within
972 \fITimeoutStopSec=\fR\&. Takes one of
973 \fBterminate\fR,
974 \fBabort\fR
975 and
976 \fBkill\fR\&. Both options default to
977 \fBterminate\fR\&.
978 .sp
979 If
980 \fBterminate\fR
981 is set the service will be gracefully terminated by sending the signal specified in
982 \fIKillSignal=\fR
983 (defaults to
984 \fBSIGTERM\fR, see
985 \fBsystemd.kill\fR(5))\&. If the service does not terminate the
986 \fIFinalKillSignal=\fR
987 is sent after
988 \fITimeoutStopSec=\fR\&. If
989 \fBabort\fR
990 is set,
991 \fIWatchdogSignal=\fR
992 is sent instead and
993 \fITimeoutAbortSec=\fR
994 applies before sending
995 \fIFinalKillSignal=\fR\&. This setting may be used to analyze services that fail to start\-up or shut\-down intermittently\&. By using
996 \fBkill\fR
997 the service is immediately terminated by sending
998 \fIFinalKillSignal=\fR
999 without any further timeout\&. This setting can be used to expedite the shutdown of failing services\&.
1000 .sp
1001 Added in version 246\&.
1002 .RE
1003 .PP
1004 \fIRuntimeMaxSec=\fR
1005 .RS 4
1006 Configures a maximum time for the service to run\&. If this is used and the service has been active for longer than the specified time it is terminated and put into a failure state\&. Note that this setting does not have any effect on
1007 \fIType=oneshot\fR
1008 services, as they terminate immediately after activation completed (use
1009 \fITimeoutStartSec=\fR
1010 to limit their activation)\&. Pass
1011 "infinity"
1012 (the default) to configure no runtime limit\&.
1013 .sp
1014 If a service of
1015 \fIType=notify\fR/\fIType=notify\-reload\fR
1016 sends
1017 "EXTEND_TIMEOUT_USEC=\&...", this may cause the runtime to be extended beyond
1018 \fIRuntimeMaxSec=\fR\&. The first receipt of this message must occur before
1019 \fIRuntimeMaxSec=\fR
1020 is exceeded, and once the runtime has extended beyond
1021 \fIRuntimeMaxSec=\fR, the service manager will allow the service to continue to run, provided the service repeats
1022 "EXTEND_TIMEOUT_USEC=\&..."
1023 within the interval specified until the service shutdown is achieved by
1024 "STOPPING=1"
1025 (or termination)\&. (see
1026 \fBsd_notify\fR(3))\&.
1027 .sp
1028 Added in version 229\&.
1029 .RE
1030 .PP
1031 \fIRuntimeRandomizedExtraSec=\fR
1032 .RS 4
1033 This option modifies
1034 \fIRuntimeMaxSec=\fR
1035 by increasing the maximum runtime by an evenly distributed duration between 0 and the specified value (in seconds)\&. If
1036 \fIRuntimeMaxSec=\fR
1037 is unspecified, then this feature will be disabled\&.
1038 .sp
1039 Added in version 250\&.
1040 .RE
1041 .PP
1042 \fIWatchdogSec=\fR
1043 .RS 4
1044 Configures the watchdog timeout for a service\&. The watchdog is activated when the start\-up is completed\&. The service must call
1045 \fBsd_notify\fR(3)
1046 regularly with
1047 "WATCHDOG=1"
1048 (i\&.e\&. the "keep\-alive ping")\&. If the time between two such calls is larger than the configured time, then the service is placed in a failed state and it will be terminated with
1049 \fBSIGABRT\fR
1050 (or the signal specified by
1051 \fIWatchdogSignal=\fR)\&. By setting
1052 \fIRestart=\fR
1053 to
1054 \fBon\-failure\fR,
1055 \fBon\-watchdog\fR,
1056 \fBon\-abnormal\fR
1057 or
1058 \fBalways\fR, the service will be automatically restarted\&. The time configured here will be passed to the executed service process in the
1059 \fIWATCHDOG_USEC=\fR
1060 environment variable\&. This allows daemons to automatically enable the keep\-alive pinging logic if watchdog support is enabled for the service\&. If this option is used,
1061 \fINotifyAccess=\fR
1062 (see below) should be set to open access to the notification socket provided by systemd\&. If
1063 \fINotifyAccess=\fR
1064 is not set, it will be implicitly set to
1065 \fBmain\fR\&. Defaults to 0, which disables this feature\&. The service can check whether the service manager expects watchdog keep\-alive notifications\&. See
1066 \fBsd_watchdog_enabled\fR(3)
1067 for details\&.
1068 \fBsd_event_set_watchdog\fR(3)
1069 may be used to enable automatic watchdog notification support\&.
1070 .RE
1071 .PP
1072 \fIRestart=\fR
1073 .RS 4
1074 Configures whether the service shall be restarted when the service process exits, is killed, or a timeout is reached\&. The service process may be the main service process, but it may also be one of the processes specified with
1075 \fIExecStartPre=\fR,
1076 \fIExecStartPost=\fR,
1077 \fIExecStop=\fR,
1078 \fIExecStopPost=\fR, or
1079 \fIExecReload=\fR\&. When the death of the process is a result of systemd operation (e\&.g\&. service stop or restart), the service will not be restarted\&. Timeouts include missing the watchdog "keep\-alive ping" deadline and a service start, reload, and stop operation timeouts\&.
1080 .sp
1081 Takes one of
1082 \fBno\fR,
1083 \fBon\-success\fR,
1084 \fBon\-failure\fR,
1085 \fBon\-abnormal\fR,
1086 \fBon\-watchdog\fR,
1087 \fBon\-abort\fR, or
1088 \fBalways\fR\&. If set to
1089 \fBno\fR
1090 (the default), the service will not be restarted\&. If set to
1091 \fBon\-success\fR, it will be restarted only when the service process exits cleanly\&. In this context, a clean exit means any of the following:
1092 .sp
1093 .RS 4
1094 .ie n \{\
1095 \h'-04'\(bu\h'+03'\c
1096 .\}
1097 .el \{\
1098 .sp -1
1099 .IP \(bu 2.3
1100 .\}
1101 exit code of 0;
1102 .RE
1103 .sp
1104 .RS 4
1105 .ie n \{\
1106 \h'-04'\(bu\h'+03'\c
1107 .\}
1108 .el \{\
1109 .sp -1
1110 .IP \(bu 2.3
1111 .\}
1112 for types other than
1113 \fIType=oneshot\fR, one of the signals
1114 \fBSIGHUP\fR,
1115 \fBSIGINT\fR,
1116 \fBSIGTERM\fR, or
1117 \fBSIGPIPE\fR;
1118 .RE
1119 .sp
1120 .RS 4
1121 .ie n \{\
1122 \h'-04'\(bu\h'+03'\c
1123 .\}
1124 .el \{\
1125 .sp -1
1126 .IP \(bu 2.3
1127 .\}
1128 exit statuses and signals specified in
1129 \fISuccessExitStatus=\fR\&.
1130 .RE
1131 .sp
1132 If set to
1133 \fBon\-failure\fR, the service will be restarted when the process exits with a non\-zero exit code, is terminated by a signal (including on core dump, but excluding the aforementioned four signals), when an operation (such as service reload) times out, and when the configured watchdog timeout is triggered\&. If set to
1134 \fBon\-abnormal\fR, the service will be restarted when the process is terminated by a signal (including on core dump, excluding the aforementioned four signals), when an operation times out, or when the watchdog timeout is triggered\&. If set to
1135 \fBon\-abort\fR, the service will be restarted only if the service process exits due to an uncaught signal not specified as a clean exit status\&. If set to
1136 \fBon\-watchdog\fR, the service will be restarted only if the watchdog timeout for the service expires\&. If set to
1137 \fBalways\fR, the service will be restarted regardless of whether it exited cleanly or not, got terminated abnormally by a signal, or hit a timeout\&. Note that
1138 \fIType=oneshot\fR
1139 services will never be restarted on a clean exit status, i\&.e\&.
1140 \fBalways\fR
1141 and
1142 \fBon\-success\fR
1143 are rejected for them\&.
1144 .sp
1145 .it 1 an-trap
1146 .nr an-no-space-flag 1
1147 .nr an-break-flag 1
1148 .br
1149 .B Table\ \&1.\ \&Exit causes and the effect of the \fIRestart=\fR settings
1150 .TS
1151 allbox tab(:);
1152 lB lB lB lB lB lB lB lB.
1153 T{
1154 Restart settings/Exit causes
1155 T}:T{
1156 \fBno\fR
1157 T}:T{
1158 \fBalways\fR
1159 T}:T{
1160 \fBon\-success\fR
1161 T}:T{
1162 \fBon\-failure\fR
1163 T}:T{
1164 \fBon\-abnormal\fR
1165 T}:T{
1166 \fBon\-abort\fR
1167 T}:T{
1168 \fBon\-watchdog\fR
1169 T}
1170 .T&
1171 l l l l l l l l
1172 l l l l l l l l
1173 l l l l l l l l
1174 l l l l l l l l
1175 l l l l l l l l
1176 l l l l l l l l.
1177 T{
1178 Clean exit code or signal
1179 T}:T{
1180 \ \&
1181 T}:T{
1182 X
1183 T}:T{
1184 X
1185 T}:T{
1186 \ \&
1187 T}:T{
1188 \ \&
1189 T}:T{
1190 \ \&
1191 T}:T{
1192 \ \&
1193 T}
1194 T{
1195 Unclean exit code
1196 T}:T{
1197 \ \&
1198 T}:T{
1199 X
1200 T}:T{
1201 \ \&
1202 T}:T{
1203 X
1204 T}:T{
1205 \ \&
1206 T}:T{
1207 \ \&
1208 T}:T{
1209 \ \&
1210 T}
1211 T{
1212 Unclean signal
1213 T}:T{
1214 \ \&
1215 T}:T{
1216 X
1217 T}:T{
1218 \ \&
1219 T}:T{
1220 X
1221 T}:T{
1222 X
1223 T}:T{
1224 X
1225 T}:T{
1226 \ \&
1227 T}
1228 T{
1229 Timeout
1230 T}:T{
1231 \ \&
1232 T}:T{
1233 X
1234 T}:T{
1235 \ \&
1236 T}:T{
1237 X
1238 T}:T{
1239 X
1240 T}:T{
1241 \ \&
1242 T}:T{
1243 \ \&
1244 T}
1245 T{
1246 Watchdog
1247 T}:T{
1248 \ \&
1249 T}:T{
1250 X
1251 T}:T{
1252 \ \&
1253 T}:T{
1254 X
1255 T}:T{
1256 X
1257 T}:T{
1258 \ \&
1259 T}:T{
1260 X
1261 T}
1262 T{
1263 Termination due to OOM
1264 T}:T{
1265 \ \&
1266 T}:T{
1267 X
1268 T}:T{
1269 \ \&
1270 T}:T{
1271 X
1272 T}:T{
1273 X
1274 T}:T{
1275 \ \&
1276 T}:T{
1277 \ \&
1278 T}
1279 .TE
1280 .sp 1
1281 As exceptions to the setting above, the service will not be restarted if the exit code or signal is specified in
1282 \fIRestartPreventExitStatus=\fR
1283 (see below) or the service is stopped with
1284 \fBsystemctl stop\fR
1285 or an equivalent operation\&. Also, the services will always be restarted if the exit code or signal is specified in
1286 \fIRestartForceExitStatus=\fR
1287 (see below)\&.
1288 .sp
1289 Note that service restart is subject to unit start rate limiting configured with
1290 \fIStartLimitIntervalSec=\fR
1291 and
1292 \fIStartLimitBurst=\fR, see
1293 \fBsystemd.unit\fR(5)
1294 for details\&.
1295 .sp
1296 Setting this to
1297 \fBon\-failure\fR
1298 is the recommended choice for long\-running services, in order to increase reliability by attempting automatic recovery from errors\&. For services that shall be able to terminate on their own choice (and avoid immediate restarting),
1299 \fBon\-abnormal\fR
1300 is an alternative choice\&.
1301 .RE
1302 .PP
1303 \fIRestartMode=\fR
1304 .RS 4
1305 Takes a string value that specifies how a service should restart:
1306 .sp
1307 .RS 4
1308 .ie n \{\
1309 \h'-04'\(bu\h'+03'\c
1310 .\}
1311 .el \{\
1312 .sp -1
1313 .IP \(bu 2.3
1314 .\}
1315 If set to
1316 \fBnormal\fR
1317 (the default), the service restarts by going through a failed/inactive state\&.
1318 .sp
1319 Added in version 254\&.
1320 .RE
1321 .sp
1322 .RS 4
1323 .ie n \{\
1324 \h'-04'\(bu\h'+03'\c
1325 .\}
1326 .el \{\
1327 .sp -1
1328 .IP \(bu 2.3
1329 .\}
1330 If set to
1331 \fBdirect\fR, the service transitions to the activating state directly during auto\-restart, skipping failed/inactive state\&.
1332 \fIExecStopPost=\fR
1333 is still invoked\&.
1334 \fIOnSuccess=\fR
1335 and
1336 \fIOnFailure=\fR
1337 are skipped\&.
1338 .sp
1339 This option is useful in cases where a dependency can fail temporarily but we do not want these temporary failures to make the dependent units fail\&. Dependent units are not notified of these temporary failures\&.
1340 .sp
1341 Added in version 254\&.
1342 .RE
1343 .sp
1344 .RS 4
1345 .ie n \{\
1346 \h'-04'\(bu\h'+03'\c
1347 .\}
1348 .el \{\
1349 .sp -1
1350 .IP \(bu 2.3
1351 .\}
1352 If set to
1353 \fBdebug\fR, the service manager will log messages that are related to this unit at debug level while automated restarts are attempted, until either the service hits the rate limit or it succeeds, and the
1354 \fI$DEBUG_INVOCATION=1\fR
1355 environment variable will be set for the unit\&. This is useful to be able to get additional information when a service fails to start, without needing to proactively or permanently enable debug level logging in systemd, which is very verbose\&. This is otherwise equivalent to
1356 \fBnormal\fR
1357 mode\&.
1358 .sp
1359 Added in version 257\&.
1360 .RE
1361 .sp
1362 Added in version 254\&.
1363 .RE
1364 .PP
1365 \fISuccessExitStatus=\fR
1366 .RS 4
1367 Takes a list of exit status definitions that, when returned by the main service process, will be considered successful termination, in addition to the normal successful exit status 0 and, except for
1368 \fIType=oneshot\fR, the signals
1369 \fBSIGHUP\fR,
1370 \fBSIGINT\fR,
1371 \fBSIGTERM\fR, and
1372 \fBSIGPIPE\fR\&. Exit status definitions can be numeric termination statuses, termination status names, or termination signal names, separated by spaces\&. See the Process Exit Codes section in
1373 \fBsystemd.exec\fR(5)
1374 for a list of termination status names (for this setting only the part without the
1375 "EXIT_"
1376 or
1377 "EX_"
1378 prefix should be used)\&. See
1379 \fBsignal\fR(7)
1380 for a list of signal names\&.
1381 .sp
1382 Note that this setting does not change the mapping between numeric exit statuses and their names, i\&.e\&. regardless how this setting is used 0 will still be mapped to
1383 "SUCCESS"
1384 (and thus typically shown as
1385 "0/SUCCESS"
1386 in tool outputs) and 1 to
1387 "FAILURE"
1388 (and thus typically shown as
1389 "1/FAILURE"), and so on\&. It only controls what happens as effect of these exit statuses, and how it propagates to the state of the service as a whole\&.
1390 .sp
1391 This option may appear more than once, in which case the list of successful exit statuses is merged\&. If the empty string is assigned to this option, the list is reset, all prior assignments of this option will have no effect\&.
1392 .PP
1393 \fBExample\ \&1.\ \&A service with the \fISuccessExitStatus=\fR setting\fR
1394 .sp
1395 .if n \{\
1396 .RS 4
1397 .\}
1398 .nf
1399 SuccessExitStatus=TEMPFAIL 250 SIGKILL
1400 .fi
1401 .if n \{\
1402 .RE
1403 .\}
1404 .sp
1405 Exit status 75 (\fBTEMPFAIL\fR), 250, and the termination signal
1406 \fBSIGKILL\fR
1407 are considered clean service terminations\&.
1408
1409 Note:
1410 \fBsystemd\-analyze exit\-status\fR
1411 may be used to list exit statuses and translate between numerical status values and names\&.
1412 .sp
1413 Added in version 189\&.
1414 .RE
1415 .PP
1416 \fIRestartPreventExitStatus=\fR
1417 .RS 4
1418 Takes a list of exit status definitions that, when returned by the main service process, will prevent automatic service restarts, regardless of the restart setting configured with
1419 \fIRestart=\fR\&. Exit status definitions can be numeric termination statuses, termination status names, or termination signal names, separated by spaces\&. Defaults to the empty list, so that, by default, no exit status is excluded from the configured restart logic\&.
1420 .PP \fBExample\ \&2.\ \&A service with the \fIRestartPreventExitStatus=\fR setting\fR .sp .if n \{\ .RS 4 .\} .nf RestartPreventExitStatus=TEMPFAIL 250 SIGKILL .fi .if n \{\ .RE .\} .sp Exit status 75 (\fBTEMPFAIL\fR), 250, and the termination signal \fBSIGKILL\fR will not result in automatic service restarting\&.
1421 This option may appear more than once, in which case the list of restart\-preventing statuses is merged\&. If the empty string is assigned to this option, the list is reset and all prior assignments of this option will have no effect\&.
1422 .sp
1423 Note that this setting has no effect on processes configured via
1424 \fIExecStartPre=\fR,
1425 \fIExecStartPost=\fR,
1426 \fIExecStop=\fR,
1427 \fIExecStopPost=\fR
1428 or
1429 \fIExecReload=\fR, but only on the main service process, i\&.e\&. either the one invoked by
1430 \fIExecStart=\fR
1431 or (depending on
1432 \fIType=\fR,
1433 \fIPIDFile=\fR, \&...) the otherwise configured main process\&.
1434 .sp
1435 Added in version 189\&.
1436 .RE
1437 .PP
1438 \fIRestartForceExitStatus=\fR
1439 .RS 4
1440 Takes a list of exit status definitions that, when returned by the main service process, will force automatic service restarts, regardless of the restart setting configured with
1441 \fIRestart=\fR\&. The argument format is similar to
1442 \fIRestartPreventExitStatus=\fR\&.
1443 .sp
1444 Note that for
1445 \fIType=oneshot\fR
1446 services, a success exit status will prevent them from auto\-restarting, no matter whether the corresponding exit statuses are listed in this option or not\&.
1447 .sp
1448 Added in version 215\&.
1449 .RE
1450 .PP
1451 \fIRootDirectoryStartOnly=\fR
1452 .RS 4
1453 Takes a boolean argument\&. If true, the root directory, as configured with the
1454 \fIRootDirectory=\fR
1455 option (see
1456 \fBsystemd.exec\fR(5)
1457 for more information), is only applied to the process started with
1458 \fIExecStart=\fR, and not to the various other
1459 \fIExecStartPre=\fR,
1460 \fIExecStartPost=\fR,
1461 \fIExecReload=\fR,
1462 \fIExecReloadPost=\fR,
1463 \fIExecStop=\fR, and
1464 \fIExecStopPost=\fR
1465 commands\&. If false, the setting is applied to all configured commands the same way\&. Defaults to false\&.
1466 .RE
1467 .PP
1468 \fINonBlocking=\fR
1469 .RS 4
1470 Set the
1471 \fBO_NONBLOCK\fR
1472 flag for all file descriptors passed via socket\-based activation\&. If true, all file descriptors >= 3 (i\&.e\&. all except stdin, stdout, stderr), excluding those passed in via the file descriptor storage logic (see
1473 \fIFileDescriptorStoreMax=\fR
1474 for details), will have the
1475 \fBO_NONBLOCK\fR
1476 flag set and hence are in non\-blocking mode\&. This option is only useful in conjunction with a socket unit, as described in
1477 \fBsystemd.socket\fR(5)
1478 and has no effect on file descriptors which were previously saved in the file\-descriptor store for example\&. Defaults to false\&.
1479 .sp
1480 Note that if the same socket unit is configured to be passed to multiple service units (via the
1481 \fISockets=\fR
1482 setting, see below), and these services have different
1483 \fINonBlocking=\fR
1484 configurations, the precise state of
1485 \fBO_NONBLOCK\fR
1486 depends on the order in which these services are invoked, and will possibly change after service code already took possession of the socket file descriptor, simply because the
1487 \fBO_NONBLOCK\fR
1488 state of a socket is shared by all file descriptors referencing it\&. Hence it is essential that all services sharing the same socket use the same
1489 \fINonBlocking=\fR
1490 configuration, and do not change the flag in service code either\&.
1491 .RE
1492 .PP
1493 \fINotifyAccess=\fR
1494 .RS 4
1495 Controls access to the service status notification socket, as accessible via the
1496 \fBsd_notify\fR(3)
1497 call\&. Takes one of
1498 \fBnone\fR
1499 (the default),
1500 \fBmain\fR,
1501 \fBexec\fR
1502 or
1503 \fBall\fR\&. If
1504 \fBnone\fR, no daemon status updates are accepted from the service processes, all status update messages are ignored\&. If
1505 \fBmain\fR, only service updates sent from the main process of the service are accepted\&. If
1506 \fBexec\fR, only service updates sent from any of the main or control processes originating from one of the
1507 \fIExec*=\fR
1508 commands are accepted\&. If
1509 \fBall\fR, all services updates from all members of the service\*(Aqs control group are accepted\&. This option should be set to open access to the notification socket when using
1510 \fIType=notify\fR/\fIType=notify\-reload\fR
1511 or
1512 \fIWatchdogSec=\fR
1513 (see above)\&. If those options are used but
1514 \fINotifyAccess=\fR
1515 is not configured, it will be implicitly set to
1516 \fBmain\fR\&.
1517 .sp
1518 Note that
1519 \fBsd_notify()\fR
1520 notifications may be attributed to units correctly only if either the sending process is still around at the time PID 1 processes the message, or if the sending process is explicitly runtime\-tracked by the service manager\&. The latter is the case if the service manager originally forked off the process, i\&.e\&. on all processes that match
1521 \fBmain\fR
1522 or
1523 \fBexec\fR\&. Conversely, if an auxiliary process of the unit sends an
1524 \fBsd_notify()\fR
1525 message and immediately exits, the service manager might not be able to properly attribute the message to the unit, and thus will ignore it, even if
1526 \fINotifyAccess=\fR\fBall\fR
1527 is set for it\&.
1528 .sp
1529 Hence, to eliminate all race conditions involving lookup of the client\*(Aqs unit and attribution of notifications to units correctly,
1530 \fBsd_notify_barrier()\fR
1531 may be used\&. This call acts as a synchronization point and ensures all notifications sent before this call have been picked up by the service manager when it returns successfully\&. Use of
1532 \fBsd_notify_barrier()\fR
1533 is needed for clients which are not invoked by the service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the unit\&.
1534 .RE
1535 .PP
1536 \fISockets=\fR
1537 .RS 4
1538 Specifies the name of the socket units this service shall inherit socket file descriptors from when the service is started\&. Normally, it should not be necessary to use this setting, as all socket file descriptors whose unit shares the same name as the service (subject to the different unit name suffix of course) are passed to the spawned process\&.
1539 .sp
1540 Note that the same socket file descriptors may be passed to multiple processes simultaneously\&. Also note that a different service may be activated on incoming socket traffic than the one which is ultimately configured to inherit the socket file descriptors\&. Or, in other words: the
1541 \fIService=\fR
1542 setting of
1543 \&.socket
1544 units does not have to match the inverse of the
1545 \fISockets=\fR
1546 setting of the
1547 \&.service
1548 it refers to\&.
1549 .sp
1550 This option may appear more than once, in which case the list of socket units is merged\&. Note that once set, clearing the list of sockets again (for example, by assigning the empty string to this option) is not supported\&.
1551 .RE
1552 .PP
1553 \fIFileDescriptorStoreMax=\fR
1554 .RS 4
1555 Configure how many file descriptors may be stored in the service manager for the service using
1556 \fBsd_pid_notify_with_fds\fR(3)\*(Aqs
1557 "FDSTORE=1"
1558 messages\&. This is useful for implementing services that can restart after an explicit request or a crash without losing state\&. Any open sockets and other file descriptors which should not be closed during the restart may be stored this way\&. Application state can either be serialized to a file in
1559 \fIRuntimeDirectory=\fR, or stored in a
1560 \fBmemfd_create\fR(2)
1561 memory file descriptor\&. Defaults to 0, i\&.e\&. no file descriptors may be stored in the service manager\&. All file descriptors passed to the service manager from a specific service are passed back to the service\*(Aqs main process on the next service restart (see
1562 \fBsd_listen_fds\fR(3)
1563 for details about the precise protocol used and the order in which the file descriptors are passed)\&. Any file descriptors passed to the service manager are automatically closed when
1564 \fBPOLLHUP\fR
1565 or
1566 \fBPOLLERR\fR
1567 is seen on them, or when the service is fully stopped and no job is queued or being executed for it (the latter can be tweaked with
1568 \fIFileDescriptorStorePreserve=\fR, see below)\&. If this option is used,
1569 \fINotifyAccess=\fR
1570 (see above) should be set to open access to the notification socket provided by systemd\&. If
1571 \fINotifyAccess=\fR
1572 is not set, it will be implicitly set to
1573 \fBmain\fR\&.
1574 .sp
1575 The
1576 \fBfdstore\fR
1577 command of
1578 \fBsystemd-analyze\fR(1)
1579 may be used to list the current contents of a service\*(Aqs file descriptor store\&.
1580 .sp
1581 Note that the service manager will only pass file descriptors contained in the file descriptor store to the service\*(Aqs own processes, never to other clients via IPC or similar\&. However, it does allow unprivileged clients to query the list of currently open file descriptors of a service\&. Sensitive data may hence be safely placed inside the referenced files, but should not be attached to the metadata (e\&.g\&. included in filenames) of the stored file descriptors\&.
1582 .sp
1583 If this option is set to a non\-zero value the
1584 \fI$FDSTORE\fR
1585 environment variable will be set for processes invoked for this service\&. See
1586 \fBsystemd.exec\fR(5)
1587 for details\&.
1588 .sp
1589 For further information on the file descriptor store see the
1590 \m[blue]\fBFile Descriptor Store\fR\m[]\&\s-2\u[1]\d\s+2
1591 overview\&.
1592 .sp
1593 Added in version 219\&.
1594 .RE
1595 .PP
1596 \fIFileDescriptorStorePreserve=\fR
1597 .RS 4
1598 Takes one of
1599 \fBno\fR,
1600 \fByes\fR,
1601 \fBrestart\fR
1602 and controls when to release the service\*(Aqs file descriptor store (i\&.e\&. when to close the contained file descriptors, if any)\&. If set to
1603 \fBno\fR
1604 the file descriptor store is automatically released when the service is stopped; if
1605 \fBrestart\fR
1606 (the default) it is kept around as long as the unit is neither inactive nor failed, or a job is queued for the service, or the service is expected to be restarted\&. If
1607 \fByes\fR
1608 the file descriptor store is kept around until the unit is removed from memory (i\&.e\&. is not referenced anymore and inactive)\&. The latter is useful to keep entries in the file descriptor store pinned until the service manager exits\&.
1609 .sp
1610 Use
1611 \fBsystemctl clean \-\-what=fdstore \&...\fR
1612 to release the file descriptor store explicitly\&.
1613 .sp
1614 Added in version 254\&.
1615 .RE
1616 .PP
1617 \fIUSBFunctionDescriptors=\fR
1618 .RS 4
1619 Configure the location of a file containing
1620 \m[blue]\fBUSB FunctionFS\fR\m[]\&\s-2\u[2]\d\s+2
1621 descriptors, for implementation of USB gadget functions\&. This is used only in conjunction with a socket unit with
1622 \fIListenUSBFunction=\fR
1623 configured\&. The contents of this file are written to the
1624 ep0
1625 file after it is opened\&.
1626 .sp
1627 Added in version 227\&.
1628 .RE
1629 .PP
1630 \fIUSBFunctionStrings=\fR
1631 .RS 4
1632 Configure the location of a file containing USB FunctionFS strings\&. Behavior is similar to
1633 \fIUSBFunctionDescriptors=\fR
1634 above\&.
1635 .sp
1636 Added in version 227\&.
1637 .RE
1638 .PP
1639 \fIOOMPolicy=\fR
1640 .RS 4
1641 Configure the out\-of\-memory (OOM) killing policy for the kernel and the userspace OOM killer
1642 \fBsystemd-oomd.service\fR(8)\&. On Linux, when memory becomes scarce to the point that the kernel has trouble allocating memory for itself, it might decide to kill a running process in order to free up memory and reduce memory pressure\&. Note that
1643 systemd\-oomd\&.service
1644 is a more flexible solution that aims to prevent out\-of\-memory situations for the userspace too, not just the kernel, by attempting to terminate services earlier, before the kernel would have to act\&.
1645 .sp
1646 This setting takes one of
1647 \fBcontinue\fR,
1648 \fBstop\fR
1649 or
1650 \fBkill\fR\&. If set to
1651 \fBcontinue\fR
1652 and a process in the unit is killed by the OOM killer, this is logged but the unit continues running\&. If set to
1653 \fBstop\fR
1654 the event is logged and the unit\*(Aqs processes are terminated cleanly by the service manager\&. If set to
1655 \fBkill\fR
1656 and one of the unit\*(Aqs processes is killed by the OOM killer the kernel is instructed to kill all remaining processes of the unit too, by setting the
1657 memory\&.oom\&.group
1658 attribute to
1659 \fB1\fR; also see kernel page
1660 \m[blue]\fBControl Group v2\fR\m[]\&\s-2\u[3]\d\s+2\&. In case of both
1661 \fBstop\fR
1662 and
1663 \fBkill\fR, the service ultimately ends up in the
1664 \fBoom\-kill\fR
1665 failed state after which
1666 \fIRestart=\fR
1667 may apply\&.
1668 .sp
1669 Defaults to the setting
1670 \fIDefaultOOMPolicy=\fR
1671 in
1672 \fBsystemd-system.conf\fR(5)
1673 is set to, except for units where
1674 \fIDelegate=\fR
1675 is turned on, where it defaults to
1676 \fBcontinue\fR\&.
1677 .sp
1678 Use the
1679 \fIOOMScoreAdjust=\fR
1680 setting to configure whether processes of the unit shall be considered preferred or less preferred candidates for process termination by the Linux OOM killer logic\&. See
1681 \fBsystemd.exec\fR(5)
1682 for details\&.
1683 .sp
1684 This setting also applies to
1685 \fBsystemd-oomd.service\fR(8)\&. Similarly to the kernel OOM kills performed by the kernel, this setting determines the state of the unit after
1686 \fBsystemd\-oomd\fR
1687 kills a cgroup associated with it\&.
1688 .sp
1689 Added in version 243\&.
1690 .RE
1691 .PP
1692 \fIOpenFile=\fR
1693 .RS 4
1694 Takes an argument of the form
1695 "path[\fI:fd\-name:options\fR]", where:
1696 .sp
1697 .RS 4
1698 .ie n \{\
1699 \h'-04'\(bu\h'+03'\c
1700 .\}
1701 .el \{\
1702 .sp -1
1703 .IP \(bu 2.3
1704 .\}
1705 "path"
1706 is a path to a file or an
1707 \fBAF_UNIX\fR
1708 socket in the file system;
1709 .RE
1710 .sp
1711 .RS 4
1712 .ie n \{\
1713 \h'-04'\(bu\h'+03'\c
1714 .\}
1715 .el \{\
1716 .sp -1
1717 .IP \(bu 2.3
1718 .\}
1719 "fd\-name"
1720 is a name that will be associated with the file descriptor; the name may contain any ASCII character, but must exclude control characters and ":", and must be at most 255 characters in length; it is optional and, if not provided, defaults to the file name;
1721 .RE
1722 .sp
1723 .RS 4
1724 .ie n \{\
1725 \h'-04'\(bu\h'+03'\c
1726 .\}
1727 .el \{\
1728 .sp -1
1729 .IP \(bu 2.3
1730 .\}
1731 "options"
1732 is a comma\-separated list of access options; possible values are
1733 "read\-only",
1734 "append",
1735 "truncate",
1736 "graceful"; if not specified, files will be opened in
1737 \fBrw\fR
1738 mode; if
1739 "graceful"
1740 is specified, errors during file/socket opening are ignored\&. Specifying the same option several times is treated as an error\&.
1741 .RE
1742 .sp
1743 The file or socket is opened by the service manager and the file descriptor is passed to the service\&. If the path is a socket, we call
1744 \fBconnect()\fR
1745 on it\&. See
1746 \fBsd_listen_fds\fR(3)
1747 for more details on how to retrieve these file descriptors\&.
1748 .sp
1749 This setting is useful to allow services to access files/sockets that they cannot access themselves (due to running in a separate mount namespace, not having privileges, \&.\&.\&.)\&.
1750 .sp
1751 This setting can be specified multiple times, in which case all the specified paths are opened and the file descriptors passed to the service\&. If the empty string is assigned, the entire list of open files defined prior to this is reset\&.
1752 .sp
1753 Added in version 253\&.
1754 .RE
1755 .PP
1756 \fIReloadSignal=\fR
1757 .RS 4
1758 Configures the UNIX process signal to send to the service\*(Aqs main process when asked to reload the service\*(Aqs configuration\&. Defaults to
1759 \fBSIGHUP\fR\&. This option has no effect unless
1760 \fIType=\fR\fBnotify\-reload\fR
1761 is used, see above\&.
1762 .sp
1763 Added in version 253\&.
1764 .RE
1765 .PP
1766 \fIRefreshOnReload=\fR
1767 .RS 4
1768 Takes a boolean argument, or a list of resources defined in
1769 \fBsystemd.exec\fR(5)\&. Possible values are
1770 \fBextensions\fR
1771 and
1772 \fBcredentials\fR, separated by space\&. Prepending the list with a single tilde character ("~") inverts the effect\&. Defaults to
1773 \fBextensions\fR\&. An empty assignment resets the list to default\&. If enabled, the corresponding resources (\fBExtensionImages=\fR/\fBExtensionDirectories=\fR
1774 for
1775 \fBextensions\fR
1776 and
1777 \fBLoadCredential=\fR/\fBImportCredential=\fR/
1778 \fBSetCredential=\fR
1779 (along with their
1780 \fBEncrypted\fR
1781 counterparts) for
1782 \fBcredentials\fR) will be refreshed on service reload\&. If
1783 \fByes\fR, all resources listed above that are used by the service shall be refreshed\&.
1784 .sp
1785 Specially, if this option is set explicitly, and the respective resources are in use, the service may be reloaded without any actual reload mechanism (\fBExecReload=\fR
1786 or
1787 \fBType=notify\-reload\fR) for notifying the main process, in which case the reload is considered complete immediately after refreshing\&.
1788 .sp
1789 Added in version 260\&.
1790 .RE
1791 .PP
1792 Check
1793 \fBsystemd.unit\fR(5),
1794 \fBsystemd.exec\fR(5), and
1795 \fBsystemd.kill\fR(5)
1796 for more settings\&.
1797 .SH "COMMAND LINES"
1798 .PP
1799 This section describes command line parsing and variable and specifier substitutions for
1800 \fIExecStart=\fR,
1801 \fIExecStartPre=\fR,
1802 \fIExecStartPost=\fR,
1803 \fIExecReload=\fR,
1804 \fIExecStop=\fR,
1805 \fIExecStopPost=\fR, and
1806 \fIExecCondition=\fR
1807 options\&.
1808 .PP
1809 Multiple command lines may be specified by using the relevant setting multiple times\&.
1810 .PP
1811 Each command line is unquoted using the rules described in "Quoting" section in
1812 \fBsystemd.syntax\fR(7)\&. The first item becomes the command to execute, and the subsequent items the arguments\&.
1813 .PP
1814 This syntax is inspired by shell syntax, but only the meta\-characters and expansions described in the following paragraphs are understood, and the expansion of variables is different\&. Specifically, redirection using
1815 "<",
1816 "<<",
1817 ">", and
1818 ">>", pipes using
1819 "|", running programs in the background using
1820 "&", and
1821 \fIother elements of shell syntax are not supported\fR\&.
1822 .PP
1823 The command to execute may contain spaces, but control characters are not allowed\&.
1824 .PP
1825 Each command may be prefixed with a number of special characters:
1826 .sp
1827 .it 1 an-trap
1828 .nr an-no-space-flag 1
1829 .nr an-break-flag 1
1830 .br
1831 .B Table\ \&2.\ \&Special executable prefixes
1832 .TS
1833 allbox tab(:);
1834 lB lB.
1835 T{
1836 Prefix
1837 T}:T{
1838 Effect
1839 T}
1840 .T&
1841 l l
1842 l l
1843 l l
1844 l l
1845 l l
1846 l l.
1847 T{
1848 "@"
1849 T}:T{
1850 If the executable path is prefixed with "@", the second specified token will be passed as \fBargv[0]\fR to the executed process (instead of the actual filename), followed by the further arguments specified, unless "|" is also specified, in which case it enables login shell semantics for the shell spawned by prefixing "\-" to \fBargv[0]\fR\&.
1851 T}
1852 T{
1853 "\-"
1854 T}:T{
1855 If the executable path is prefixed with "\-", an exit code of the command normally considered a failure (i\&.e\&. non\-zero exit status or abnormal exit due to signal) is recorded, but has no further effect and is considered equivalent to success\&.
1856 T}
1857 T{
1858 ":"
1859 T}:T{
1860 If the executable path is prefixed with ":", environment variable substitution (as described below this table) is not applied\&.
1861 T}
1862 T{
1863 "+"
1864 T}:T{
1865 If the executable path is prefixed with "+" then the process is executed with full privileges\&. In this mode privilege restrictions configured with \fIUser=\fR, \fIGroup=\fR, \fICapabilityBoundingSet=\fR or the various file system namespacing options (such as \fIPrivateDevices=\fR, \fIPrivateTmp=\fR) are not applied to the invoked command line (but still affect any other \fIExecStart=\fR, \fIExecStop=\fR, \&... lines)\&. However, note that this will not bypass options that apply to the whole control group, such as \fIDevicePolicy=\fR, see \fBsystemd.resource-control\fR(5) for the full list\&.
1866 T}
1867 T{
1868 "!"
1869 T}:T{
1870 Similar to the "+" character discussed above this permits invoking command lines with elevated privileges\&. However, unlike "+" the "!" character exclusively alters the effect of \fIUser=\fR, \fIGroup=\fR and \fISupplementaryGroups=\fR, i\&.e\&. only the stanzas that affect user and group credentials\&. Note that this setting may be combined with \fIDynamicUser=\fR, in which case a dynamic user/group pair is allocated before the command is invoked, but credential changing is left to the executed process itself\&.
1871 T}
1872 T{
1873 "|"
1874 T}:T{
1875 If "|" is specified standalone as executable path, invoke the default shell of \fIUser=\fR\&. If specified as a prefix, use the shell ("\-c") to spawn the executable\&. When "@" is used in conjunction, \fBargv[0]\fR of shell will be prefixed with "\-" to enable login shell semantics\&.
1876 T}
1877 .TE
1878 .sp 1
1879 .PP
1880 "@",
1881 "|",
1882 "\-",
1883 ":", and one of
1884 "+"/"!"
1885 may be used together and they can appear in any order\&. However,
1886 "+"
1887 and
1888 "!"
1889 may not be specified at the same time\&.
1890 .PP
1891 For each command, the first argument must be either an absolute path to an executable or a simple file name without any slashes\&. If the command is not a full (absolute) path, it will be resolved to a full path using a fixed search path determined at compilation time\&. Searched directories include
1892 /usr/local/bin/,
1893 /usr/bin/, and their
1894 sbin/
1895 counterparts (only on systems using split
1896 bin/
1897 and
1898 sbin/)\&. It is thus safe to use just the executable name in case of executables located in any of the "standard" directories, and an absolute path must be used in other cases\&. Hint: this search path may be queried using
1899 \fBsystemd\-path search\-binaries\-default\fR\&.
1900 .PP
1901 The command line accepts
1902 "%"
1903 specifiers as described in
1904 \fBsystemd.unit\fR(5)\&.
1905 .PP
1906 An argument solely consisting of
1907 ";"
1908 must be escaped, i\&.e\&. specified as
1909 "\e;"\&.
1910 .PP
1911 Basic environment variable substitution is supported\&. Use
1912 "${FOO}"
1913 as part of a word, or as a word of its own, on the command line, in which case it will be erased and replaced by the exact value of the environment variable (if any) including all whitespace it contains, always resulting in exactly a single argument\&. Use
1914 "$FOO"
1915 as a separate word on the command line, in which case it will be replaced by the value of the environment variable split at whitespace, resulting in zero or more arguments\&. For this type of expansion, quotes are respected when splitting into words, and afterwards removed\&.
1916 .PP
1917 Example:
1918 .sp
1919 .if n \{\
1920 .RS 4
1921 .\}
1922 .nf
1923 Environment="ONE=one" \*(AqTWO=two two\*(Aq
1924 ExecStart=echo $ONE $TWO ${TWO}
1925 .fi
1926 .if n \{\
1927 .RE
1928 .\}
1929 .PP
1930 This will execute
1931 \fB/bin/echo\fR
1932 with four arguments:
1933 "one",
1934 "two",
1935 "two", and
1936 "two two"\&.
1937 .PP
1938 Example:
1939 .sp
1940 .if n \{\
1941 .RS 4
1942 .\}
1943 .nf
1944 Environment=ONE=\*(Aqone\*(Aq "TWO=\*(Aqtwo\ \&two\*(Aq\ \&too" THREE=
1945 ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
1946 ExecStart=/bin/echo $ONE $TWO $THREE
1947 .fi
1948 .if n \{\
1949 .RE
1950 .\}
1951 .PP
1952 This results in
1953 /bin/echo
1954 being called twice, the first time with arguments
1955 "\*(Aqone\*(Aq",
1956 "\*(Aqtwo\ \&two\*(Aq\ \&too",
1957 "", and the second time with arguments
1958 "one",
1959 "two\ \&two",
1960 "too"\&.
1961 .PP
1962 Unless for commands with the special executable prefix
1963 ":", to pass a literal dollar sign, use
1964 "$$"\&. Variables whose value is not known at expansion time are treated as empty strings\&. Note that the first argument (i\&.e\&. the program to execute) may not be a variable\&.
1965 .PP
1966 Variables to be used in this fashion may be defined through
1967 \fIEnvironment=\fR
1968 and
1969 \fIEnvironmentFile=\fR\&. In addition, variables listed in the section "Environment variables in spawned processes" in
1970 \fBsystemd.exec\fR(5), which are considered "static configuration", may be used (this includes e\&.g\&.
1971 \fI$USER\fR, but not
1972 \fI$TERM\fR)\&.
1973 .PP
1974 Note that shell command lines are not directly supported, and
1975 "|"
1976 invokes the user\*(Aqs default shell which isn\*(Aqt deterministic\&. It\*(Aqs recommended to specify a shell implementation explicitly if portability is desired\&. Example:
1977 .sp
1978 .if n \{\
1979 .RS 4
1980 .\}
1981 .nf
1982 ExecStart=sh \-c \*(Aqdmesg | tac\*(Aq
1983 .fi
1984 .if n \{\
1985 .RE
1986 .\}
1987 .PP
1988 Example:
1989 .sp
1990 .if n \{\
1991 .RS 4
1992 .\}
1993 .nf
1994 ExecStart=echo one
1995 ExecStart=echo "two two"
1996 .fi
1997 .if n \{\
1998 .RE
1999 .\}
2000 .PP
2001 This will execute
2002 \fBecho\fR
2003 two times, each time with one argument:
2004 "one"
2005 and
2006 "two two", respectively\&. Because two commands are specified,
2007 \fIType=oneshot\fR
2008 must be used\&.
2009 .PP
2010 Example:
2011 .sp
2012 .if n \{\
2013 .RS 4
2014 .\}
2015 .nf
2016 Type=oneshot
2017 ExecStart=:echo $USER
2018 ExecStart=\-false
2019 ExecStart=+:@true $TEST
2020 .fi
2021 .if n \{\
2022 .RE
2023 .\}
2024 .PP
2025 This will execute
2026 \fB/usr/bin/echo\fR
2027 with the literal argument
2028 "$USER"
2029 (":"
2030 suppresses variable expansion), and then
2031 \fB/usr/bin/false\fR
2032 (the return value will be ignored because
2033 "\-"
2034 suppresses checking of the return value), and
2035 \fB/usr/bin/true\fR
2036 (with elevated privileges, with
2037 "$TEST"
2038 as
2039 \fBargv[0]\fR)\&.
2040 .PP
2041 Example:
2042 .sp
2043 .if n \{\
2044 .RS 4
2045 .\}
2046 .nf
2047 ExecStart=echo / >/dev/null & \e; \e
2048 ls
2049 .fi
2050 .if n \{\
2051 .RE
2052 .\}
2053 .PP
2054 This will execute
2055 \fBecho\fR
2056 with five arguments:
2057 "/",
2058 ">/dev/null",
2059 "&",
2060 ";", and
2061 "ls"\&.
2062 .SH "EXAMPLES"
2063 .PP
2064 \fBExample\ \&3.\ \&Simple service\fR
2065 .PP
2066 The following unit file creates a service that will execute
2067 /usr/sbin/foo\-daemon\&. Since no
2068 \fIType=\fR
2069 is specified, the default
2070 \fIType=\fR\fBsimple\fR
2071 will be assumed\&. systemd will assume the unit to be started immediately after the program has begun executing\&.
2072 .sp
2073 .if n \{\
2074 .RS 4
2075 .\}
2076 .nf
2077 [Unit]
2078 Description=Foo
2079
2080 [Service]
2081 ExecStart=/usr/sbin/foo\-daemon
2082
2083 [Install]
2084 WantedBy=multi\-user\&.target
2085 .fi
2086 .if n \{\
2087 .RE
2088 .\}
2089 .PP
2090 Note that systemd assumes here that the process started by systemd will continue running until the service terminates\&. If the program daemonizes itself (i\&.e\&. forks), please use
2091 \fIType=\fR\fBforking\fR
2092 instead\&.
2093 .PP
2094 Since no
2095 \fIExecStop=\fR
2096 was specified, systemd will send SIGTERM to all processes started from this service, and after a timeout also SIGKILL\&. This behavior can be modified, see
2097 \fBsystemd.kill\fR(5)
2098 for details\&.
2099 .PP
2100 Note that this unit type does not include any type of notification when a service has completed initialization\&. For this, you should use other unit types, such as
2101 \fIType=\fR\fBnotify\fR/\fIType=\fR\fBnotify\-reload\fR
2102 if the service understands systemd\*(Aqs notification protocol,
2103 \fIType=\fR\fBforking\fR
2104 if the service can background itself or
2105 \fIType=\fR\fBdbus\fR
2106 if the unit acquires a DBus name once initialization is complete\&. See below\&.
2107 .PP
2108 \fBExample\ \&4.\ \&Oneshot service\fR
2109 .PP
2110 Sometimes, units should just execute an action without keeping active processes, such as a filesystem check or a cleanup action on boot\&. For this,
2111 \fIType=\fR\fBoneshot\fR
2112 exists\&. Units of this type will wait until the process specified terminates and then fall back to being inactive\&. The following unit will perform a cleanup action:
2113 .sp
2114 .if n \{\
2115 .RS 4
2116 .\}
2117 .nf
2118 [Unit]
2119 Description=Cleanup old Foo data
2120
2121 [Service]
2122 Type=oneshot
2123 ExecStart=/usr/sbin/foo\-cleanup
2124
2125 [Install]
2126 WantedBy=multi\-user\&.target
2127 .fi
2128 .if n \{\
2129 .RE
2130 .\}
2131 .PP
2132 Note that systemd will consider the unit to be in the state "starting" until the program has terminated, so ordered dependencies will wait for the program to finish before starting themselves\&. The unit will revert to the "inactive" state after the execution is done, never reaching the "active" state\&. That means another request to start the unit will perform the action again\&.
2133 .PP
2134 \fIType=\fR\fBoneshot\fR
2135 are the only service units that may have more than one
2136 \fIExecStart=\fR
2137 specified\&. For units with multiple commands (\fIType=oneshot\fR), all commands will be run again\&.
2138 .PP
2139 For
2140 \fIType=oneshot\fR,
2141 \fIRestart=\fR\fBalways\fR
2142 and
2143 \fIRestart=\fR\fBon\-success\fR
2144 are
2145 \fInot\fR
2146 allowed\&.
2147 .PP
2148 \fBExample\ \&5.\ \&Stoppable oneshot service\fR
2149 .PP
2150 Similarly to the oneshot services, there are sometimes units that need to execute a program to set up something and then execute another to shut it down, but no process remains active while they are considered "started"\&. Network configuration can sometimes fall into this category\&. Another use case is if a oneshot service shall not be executed each time when they are pulled in as a dependency, but only the first time\&.
2151 .PP
2152 For this, systemd knows the setting
2153 \fIRemainAfterExit=\fR\fByes\fR, which causes systemd to consider the unit to be active if the start action exited successfully\&. This directive can be used with all types, but is most useful with
2154 \fIType=\fR\fBoneshot\fR
2155 and
2156 \fIType=\fR\fBsimple\fR\&. With
2157 \fIType=\fR\fBoneshot\fR, systemd waits until the start action has completed before it considers the unit to be active, so dependencies start only after the start action has succeeded\&. With
2158 \fIType=\fR\fBsimple\fR, dependencies will start immediately after the start action has been dispatched\&. The following unit provides an example for a simple static firewall\&.
2159 .sp
2160 .if n \{\
2161 .RS 4
2162 .\}
2163 .nf
2164 [Unit]
2165 Description=Simple firewall
2166
2167 [Service]
2168 Type=oneshot
2169 RemainAfterExit=yes
2170 ExecStart=/usr/local/sbin/simple\-firewall\-start
2171 ExecStop=/usr/local/sbin/simple\-firewall\-stop
2172
2173 [Install]
2174 WantedBy=multi\-user\&.target
2175 .fi
2176 .if n \{\
2177 .RE
2178 .\}
2179 .PP
2180 Since the unit is considered to be running after the start action has exited, invoking
2181 \fBsystemctl start\fR
2182 on that unit again will cause no action to be taken\&.
2183 .PP
2184 \fBExample\ \&6.\ \&Traditional forking services\fR
2185 .PP
2186 Many traditional daemons/services background (i\&.e\&. fork, daemonize) themselves when starting\&. Set
2187 \fIType=\fR\fBforking\fR
2188 in the service\*(Aqs unit file to support this mode of operation\&. systemd will consider the service to be in the process of initialization while the original program is still running\&. Once it exits successfully and at least a process remains (and
2189 \fIRemainAfterExit=\fR\fBno\fR), the service is considered started\&.
2190 .PP
2191 Often, a traditional daemon only consists of one process\&. Therefore, if only one process is left after the original process terminates, systemd will consider that process the main process of the service\&. In that case, the
2192 \fI$MAINPID\fR
2193 variable will be available in
2194 \fIExecReload=\fR,
2195 \fIExecStop=\fR, etc\&.
2196 .PP
2197 In case more than one process remains, systemd will be unable to determine the main process, so it will not assume there is one\&. In that case,
2198 \fI$MAINPID\fR
2199 will not expand to anything\&. However, if the process decides to write a traditional PID file, systemd will be able to read the main PID from there\&. Please set
2200 \fIPIDFile=\fR
2201 accordingly\&. Note that the daemon should write that file before finishing with its initialization\&. Otherwise, systemd might try to read the file before it exists\&.
2202 .PP
2203 The following example shows a simple daemon that forks and just starts one process in the background:
2204 .sp
2205 .if n \{\
2206 .RS 4
2207 .\}
2208 .nf
2209 [Unit]
2210 Description=My Simple Daemon
2211
2212 [Service]
2213 Type=forking
2214 ExecStart=/usr/sbin/my\-simple\-daemon \-d
2215
2216 [Install]
2217 WantedBy=multi\-user\&.target
2218 .fi
2219 .if n \{\
2220 .RE
2221 .\}
2222 .PP
2223 Please see
2224 \fBsystemd.kill\fR(5)
2225 for details on how you can influence the way systemd terminates the service\&.
2226 .PP
2227 \fBExample\ \&7.\ \&DBus services\fR
2228 .PP
2229 For services that acquire a name on the DBus system bus, use
2230 \fIType=\fR\fBdbus\fR
2231 and set
2232 \fIBusName=\fR
2233 accordingly\&. The service should not fork (daemonize)\&. systemd will consider the service to be initialized once the name has been acquired on the system bus\&. The following example shows a typical DBus service:
2234 .sp
2235 .if n \{\
2236 .RS 4
2237 .\}
2238 .nf
2239 [Unit]
2240 Description=Simple DBus Service
2241
2242 [Service]
2243 Type=dbus
2244 BusName=org\&.example\&.simple\-dbus\-service
2245 ExecStart=/usr/sbin/simple\-dbus\-service
2246
2247 [Install]
2248 WantedBy=multi\-user\&.target
2249 .fi
2250 .if n \{\
2251 .RE
2252 .\}
2253 .PP
2254 For
2255 \fIbus\-activatable\fR
2256 services, do not include a [Install] section in the systemd service file, but use the
2257 \fISystemdService=\fR
2258 option in the corresponding DBus service file, for example (/usr/share/dbus\-1/system\-services/org\&.example\&.simple\-dbus\-service\&.service):
2259 .sp
2260 .if n \{\
2261 .RS 4
2262 .\}
2263 .nf
2264 [D\-BUS Service]
2265 Name=org\&.example\&.simple\-dbus\-service
2266 Exec=/usr/sbin/simple\-dbus\-service
2267 User=root
2268 SystemdService=simple\-dbus\-service\&.service
2269 .fi
2270 .if n \{\
2271 .RE
2272 .\}
2273 .PP
2274 Please see
2275 \fBsystemd.kill\fR(5)
2276 for details on how you can influence the way systemd terminates the service\&.
2277 .PP
2278 \fBExample\ \&8.\ \&Services that notify systemd about their initialization\fR
2279 .PP
2280 \fIType=\fR\fBsimple\fR
2281 services are really easy to write, but have the major disadvantage of systemd not being able to tell when initialization of the given service is complete\&. For this reason, systemd supports a simple notification protocol that allows daemons to make systemd aware that they are done initializing\&. Use
2282 \fIType=\fR\fBnotify\fR
2283 or
2284 \fIType=\fR\fBnotify\-reload\fR
2285 for this\&. A typical service file for such a daemon would look like this:
2286 .sp
2287 .if n \{\
2288 .RS 4
2289 .\}
2290 .nf
2291 [Unit]
2292 Description=Simple Notifying Service
2293
2294 [Service]
2295 Type=notify\-reload
2296 ExecStart=/usr/sbin/simple\-notifying\-service
2297
2298 [Install]
2299 WantedBy=multi\-user\&.target
2300 .fi
2301 .if n \{\
2302 .RE
2303 .\}
2304 .PP
2305 Note that the daemon has to support systemd\*(Aqs notification protocol, else systemd will think the service has not started yet and kill it after a timeout\&. For an example of how to update daemons to support this protocol transparently, take a look at
2306 \fBsd_notify\fR(3)\&. systemd will consider the unit to be in the \*(Aqstarting\*(Aq state until a readiness notification has arrived\&.
2307 .PP
2308 Please see
2309 \fBsystemd.kill\fR(5)
2310 for details on how you can influence the way systemd terminates the service\&.
2311 .PP
2312 To avoid code duplication, it is preferable to use
2313 \fBsd_notify\fR(3)
2314 when possible, especially when other APIs provided by
2315 \fBlibsystemd\fR(3)
2316 are also used, but note that the notification protocol is very simple and guaranteed to be stable as per the
2317 \m[blue]\fBInterface Portability and Stability Promise\fR\m[]\&\s-2\u[4]\d\s+2, so it can be reimplemented by services with no external dependencies\&. For a self\-contained example, see
2318 \fBsd_notify\fR(3)\&.
2319 .SH "SEE ALSO"
2320 .PP
2321 \fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd-system.conf\fR(5), \fBsystemd.unit\fR(5), \fBsystemd.exec\fR(5), \fBsystemd.resource-control\fR(5), \fBsystemd.kill\fR(5), \fBsystemd.directives\fR(7), \fBsystemd-run\fR(1)
2322 .SH "NOTES"
2323 .IP " 1." 4
2324 File Descriptor Store
2325 .RS 4
2326 \%https://systemd.io/FILE_DESCRIPTOR_STORE
2327 .RE
2328 .IP " 2." 4
2329 USB FunctionFS
2330 .RS 4
2331 \%https://docs.kernel.org/usb/functionfs.html
2332 .RE
2333 .IP " 3." 4
2334 Control Group v2
2335 .RS 4
2336 \%https://docs.kernel.org/admin-guide/cgroup-v2.html
2337 .RE
2338 .IP " 4." 4
2339 Interface Portability and Stability Promise
2340 .RS 4
2341 \%https://systemd.io/PORTABILITY_AND_STABILITY/
2342 .RE