1SYSTEMD.SERVICE(5) systemd.service SYSTEMD.SERVICE(5)
2
6 systemd.service - Service unit configuration
7
9 service.service
10
12 A unit configuration file whose name ends in ".service" encodes
13 information about a process controlled and supervised by systemd.
14 This man page lists the configuration options specific to this unit
16 type. See systemd.unit(5) for the common options of all unit
17 configuration files. The common configuration items are configured in
18 the generic "[Unit]" and "[Install]" sections. The service specific
19 configuration options are configured in the "[Service]" section.
20 Additional options are listed in systemd.exec(5), which define the
22 execution environment the commands are executed in, and in
23 systemd.kill(5), which define the way the processes of the service are
24 terminated, and in systemd.resource-control(5), which configure
25 resource control settings for the processes of the service.
26 If a service is requested under a certain name but no unit
28 configuration file is found, systemd looks for a SysV init script by
29 the same name (with the .service suffix removed) and dynamically
30 creates a service unit from that script. This is useful for
31 compatibility with SysV. Note that this compatibility is quite
32 comprehensive but not 100%. For details about the incompatibilities,
33 see the Incompatibilities with SysV[1] document.
34
36 It is possible for systemd services to take a single argument via the
37 "service@argument.service" syntax. Such services are called
38 "instantiated" services, while the unit definition without the argument
39 parameter is called a "template". An example could be a dhcpcd@.service
40 service template which takes a network interface as a parameter to form
41 an instantiated service. Within the service file, this parameter or
42 "instance name" can be accessed with %-specifiers. See systemd.unit(5)
43 for details.
44
46 Implicit Dependencies
47 The following dependencies are implicitly added:
48 · Services with Type=dbus set automatically acquire dependencies of
50 type Requires= and After= on dbus.socket.
51 · Socket activated services are automatically ordered after their
53 activating .socket units via an automatic After= dependency.
54 Services also pull in all .socket units listed in Sockets= via
55 automatic Wants= and After= dependencies.
56 Additional implicit dependencies may be added as result of execution
58 and resource control parameters as documented in systemd.exec(5) and
59 systemd.resource-control(5).
60 Default Dependencies
62 The following dependencies are added unless DefaultDependencies=no is
63 set:
64 · Service units will have dependencies of type Requires= and After=
66 on sysinit.target, a dependency of type After= on basic.target as
67 well as dependencies of type Conflicts= and Before= on
68 shutdown.target. These ensure that normal service units pull in
69 basic system initialization, and are terminated cleanly prior to
70 system shutdown. Only services involved with early boot or late
71 system shutdown should disable this option.
72 · Instanced service units (i.e. service units with an "@" in their
74 name) are assigned by default a per-template slice unit (see
75 systemd.slice(5)), named after the template unit, containing all
76 instances of the specific template. This slice is normally stopped
77 at shutdown, together with all template instances. If that is not
78 desired, set DefaultDependencies=no in the template unit, and
79 either define your own per-template slice unit file that also sets
80 DefaultDependencies=no, or set Slice=system.slice (or another
81 suitable slice) in the template unit. Also see systemd.resource-
82 control(5).
83
85 Service files must include a "[Service]" section, which carries
86 information about the service and the process it supervises. A number
87 of options that may be used in this section are shared with other unit
88 types. These options are documented in systemd.exec(5), systemd.kill(5)
89 and systemd.resource-control(5). The options specific to the
90 "[Service]" section of service units are the following:
91 Type=
93 Configures the process start-up type for this service unit. One of
94 simple, exec, forking, oneshot, dbus, notify or idle:
95 · If set to simple (the default if ExecStart= is specified but
97 neither Type= nor BusName= are), the service manager will
98 consider the unit started immediately after the main service
99 process has been forked off. It is expected that the process
100 configured with ExecStart= is the main process of the service.
101 In this mode, if the process offers functionality to other
102 processes on the system, its communication channels should be
103 installed before the service is started up (e.g. sockets set up
104 by systemd, via socket activation), as the service manager will
105 immediately proceed starting follow-up units, right after
106 creating the main service process, and before executing the
107 service's binary. Note that this means systemctl start command
108 lines for simple services will report success even if the
109 service's binary cannot be invoked successfully (for example
110 because the selected User= doesn't exist, or the service binary
111 is missing).
112 · The exec type is similar to simple, but the service manager
114 will consider the unit started immediately after the main
115 service binary has been executed. The service manager will
116 delay starting of follow-up units until that point. (Or in
117 other words: simple proceeds with further jobs right after
118 fork() returns, while exec will not proceed before both fork()
119 and execve() in the service process succeeded.) Note that this
120 means systemctl start command lines for exec services will
121 report failure when the service's binary cannot be invoked
122 successfully (for example because the selected User= doesn't
123 exist, or the service binary is missing).
124 · If set to forking, it is expected that the process configured
126 with ExecStart= will call fork() as part of its start-up. The
127 parent process is expected to exit when start-up is complete
128 and all communication channels are set up. The child continues
129 to run as the main service process, and the service manager
130 will consider the unit started when the parent process exits.
131 This is the behavior of traditional UNIX services. If this
132 setting is used, it is recommended to also use the PIDFile=
133 option, so that systemd can reliably identify the main process
134 of the service. systemd will proceed with starting follow-up
135 units as soon as the parent process exits.
136 · Behavior of oneshot is similar to simple; however, the service
138 manager will consider the unit started after the main process
139 exits. It will then start follow-up units. RemainAfterExit= is
140 particularly useful for this type of service. Type=oneshot is
141 the implied default if neither Type= nor ExecStart= are
142 specified.
143 · Behavior of dbus is similar to simple; however, it is expected
145 that the service acquires a name on the D-Bus bus, as
146 configured by BusName=. systemd will proceed with starting
147 follow-up units after the D-Bus bus name has been acquired.
148 Service units with this option configured implicitly gain
149 dependencies on the dbus.socket unit. This type is the default
150 if BusName= is specified.
151 · Behavior of notify is similar to exec; however, it is expected
153 that the service sends a notification message via sd_notify(3)
154 or an equivalent call when it has finished starting up. systemd
155 will proceed with starting follow-up units after this
156 notification message has been sent. If this option is used,
157 NotifyAccess= (see below) should be set to open access to the
158 notification socket provided by systemd. If NotifyAccess= is
159 missing or set to none, it will be forcibly set to main. Note
160 that currently Type=notify will not work if used in combination
161 with PrivateNetwork=yes.
162 · Behavior of idle is very similar to simple; however, actual
164 execution of the service program is delayed until all active
165 jobs are dispatched. This may be used to avoid interleaving of
166 output of shell services with the status output on the console.
167 Note that this type is useful only to improve console output,
168 it is not useful as a general unit ordering tool, and the
169 effect of this service type is subject to a 5s timeout, after
170 which the service program is invoked anyway.
171 It is generally recommended to use Type=simple for long-running
173 services whenever possible, as it is the simplest and fastest
174 option. However, as this service type won't propagate service
175 start-up failures and doesn't allow ordering of other units against
176 completion of initialization of the service (which for example is
177 useful if clients need to connect to the service through some form
178 of IPC, and the IPC channel is only established by the service
179 itself — in contrast to doing this ahead of time through socket or
180 bus activation or similar), it might not be sufficient for many
181 cases. If so, notify or dbus (the latter only in case the service
182 provides a D-Bus interface) are the preferred options as they allow
183 service program code to precisely schedule when to consider the
184 service started up successfully and when to proceed with follow-up
185 units. The notify service type requires explicit support in the
186 service codebase (as sd_notify() or an equivalent API needs to be
187 invoked by the service at the appropriate time) — if it's not
188 supported, then forking is an alternative: it supports the
189 traditional UNIX service start-up protocol. Finally, exec might be
190 an option for cases where it is enough to ensure the service binary
191 is invoked, and where the service binary itself executes no or
192 little initialization on its own (and its initialization is
193 unlikely to fail). Note that using any type other than simple
194 possibly delays the boot process, as the service manager needs to
195 wait for service initialization to complete. It is hence
196 recommended not to needlessly use any types other than simple.
197 (Also note it is generally not recommended to use idle or oneshot
198 for long-running services.)
199 RemainAfterExit=
201 Takes a boolean value that specifies whether the service shall be
202 considered active even when all its processes exited. Defaults to
203 no.
204 GuessMainPID=
206 Takes a boolean value that specifies whether systemd should try to
207 guess the main PID of a service if it cannot be determined
208 reliably. This option is ignored unless Type=forking is set and
209 PIDFile= is unset because for the other types or with an explicitly
210 configured PID file, the main PID is always known. The guessing
211 algorithm might come to incorrect conclusions if a daemon consists
212 of more than one process. If the main PID cannot be determined,
213 failure detection and automatic restarting of a service will not
214 work reliably. Defaults to yes.
215 PIDFile=
217 Takes a path referring to the PID file of the service. Usage of
218 this option is recommended for services where Type= is set to
219 forking. The path specified typically points to a file below /run/.
220 If a relative path is specified it is hence prefixed with /run/.
221 The service manager will read the PID of the main process of the
222 service from this file after start-up of the service. The service
223 manager will not write to the file configured here, although it
224 will remove the file after the service has shut down if it still
225 exists. The PID file does not need to be owned by a privileged
226 user, but if it is owned by an unprivileged user additional safety
227 restrictions are enforced: the file may not be a symlink to a file
228 owned by a different user (neither directly nor indirectly), and
229 the PID file must refer to a process already belonging to the
230 service.
231 BusName=
233 Takes a D-Bus bus name that this service is reachable as. This
234 option is mandatory for services where Type= is set to dbus.
235 ExecStart=
237 Commands with their arguments that are executed when this service
238 is started. The value is split into zero or more command lines
239 according to the rules described below (see section "Command Lines"
240 below).
241 Unless Type= is oneshot, exactly one command must be given. When
243 Type=oneshot is used, zero or more commands may be specified.
244 Commands may be specified by providing multiple command lines in
245 the same directive, or alternatively, this directive may be
246 specified more than once with the same effect. If the empty string
247 is assigned to this option, the list of commands to start is reset,
248 prior assignments of this option will have no effect. If no
249 ExecStart= is specified, then the service must have
250 RemainAfterExit=yes and at least one ExecStop= line set. (Services
251 lacking both ExecStart= and ExecStop= are not valid.)
252 For each of the specified commands, the first argument must be
254 either an absolute path to an executable or a simple file name
255 without any slashes. Optionally, this filename may be prefixed with
256 a number of special characters:
257 Table 1. Special executable prefixes
259 ┌───────┬────────────────────────────┐
260 │Prefix │ Effect │
261 ├───────┼────────────────────────────┤
262 │"@" │ If the executable path is │
263 │ │ prefixed with "@", the │
264 │ │ second specified token │
265 │ │ will be passed as │
266 │ │ "argv[0]" to the executed │
267 │ │ process (instead of the │
268 │ │ actual filename), followed │
269 │ │ by the further arguments │
270 │ │ specified. │
271 ├───────┼────────────────────────────┤
272 │"-" │ If the executable path is │
273 │ │ prefixed with "-", an exit │
274 │ │ code of the command │
275 │ │ normally considered a │
276 │ │ failure (i.e. non-zero │
277 │ │ exit status or abnormal │
278 │ │ exit due to signal) is │
279 │ │ recorded, but has no │
280 │ │ further effect and is │
281 │ │ considered equivalent to │
282 │ │ success. │
283 ├───────┼────────────────────────────┤
284 │"+" │ If the executable path is │
285 │ │ prefixed with "+" then the │
286 │ │ process is executed with │
287 │ │ full privileges. In this │
288 │ │ mode privilege │
289 │ │ restrictions configured │
290 │ │ with User=, Group=, │
291 │ │ CapabilityBoundingSet= or │
292 │ │ the various file system │
293 │ │ namespacing options (such │
294 │ │ as PrivateDevices=, │
295 │ │ PrivateTmp=) are not │
296 │ │ applied to the invoked │
297 │ │ command line (but still │
298 │ │ affect any other │
299 │ │ ExecStart=, ExecStop=, ... │
300 │ │ lines). │
301 ├───────┼────────────────────────────┤
302 │"!" │ Similar to the "+" │
303 │ │ character discussed above │
304 │ │ this permits invoking │
305 │ │ command lines with │
306 │ │ elevated privileges. │
307 │ │ However, unlike "+" the │
308 │ │ "!" character exclusively │
309 │ │ alters the effect of │
310 │ │ User=, Group= and │
311 │ │ SupplementaryGroups=, i.e. │
312 │ │ only the stanzas that │
313 │ │ affect user and group │
314 │ │ credentials. Note that │
315 │ │ this setting may be │
316 │ │ combined with │
317 │ │ DynamicUser=, in which │
318 │ │ case a dynamic user/group │
319 │ │ pair is allocated before │
320 │ │ the command is invoked, │
321 │ │ but credential changing is │
322 │ │ left to the executed │
323 │ │ process itself. │
324 ├───────┼────────────────────────────┤
325 │"!!" │ This prefix is very │
326 │ │ similar to "!", however it │
327 │ │ only has an effect on │
328 │ │ systems lacking support │
329 │ │ for ambient process │
330 │ │ capabilities, i.e. without │
331 │ │ support for │
332 │ │ AmbientCapabilities=. It's │
333 │ │ intended to be used for │
334 │ │ unit files that take │
335 │ │ benefit of ambient │
336 │ │ capabilities to run │
337 │ │ processes with minimal │
338 │ │ privileges wherever │
339 │ │ possible while remaining │
340 │ │ compatible with systems │
341 │ │ that lack ambient │
342 │ │ capabilities support. Note │
343 │ │ that when "!!" is used, │
344 │ │ and a system lacking │
345 │ │ ambient capability support │
346 │ │ is detected any configured │
347 │ │ SystemCallFilter= and │
348 │ │ CapabilityBoundingSet= │
349 │ │ stanzas are implicitly │
350 │ │ modified, in order to │
351 │ │ permit spawned processes │
352 │ │ to drop credentials and │
353 │ │ capabilities themselves, │
354 │ │ even if this is configured │
355 │ │ to not be allowed. │
356 │ │ Moreover, if this prefix │
357 │ │ is used and a system │
358 │ │ lacking ambient capability │
359 │ │ support is detected │
360 │ │ AmbientCapabilities= will │
361 │ │ be skipped and not be │
362 │ │ applied. On systems │
363 │ │ supporting ambient │
364 │ │ capabilities, "!!" has no │
365 │ │ effect and is redundant. │
366 └───────┴────────────────────────────┘
367 "@", "-", and one of "+"/"!"/"!!" may be used together and they
368 can appear in any order. However, only one of "+", "!", "!!" may
369 be used at a time. Note that these prefixes are also supported for
370 the other command line settings, i.e. ExecStartPre=,
371 ExecStartPost=, ExecReload=, ExecStop= and ExecStopPost=.
372 If more than one command is specified, the commands are invoked
374 sequentially in the order they appear in the unit file. If one of
375 the commands fails (and is not prefixed with "-"), other lines are
376 not executed, and the unit is considered failed.
377 Unless Type=forking is set, the process started via this command
379 line will be considered the main process of the daemon.
380 ExecStartPre=, ExecStartPost=
382 Additional commands that are executed before or after the command
383 in ExecStart=, respectively. Syntax is the same as for ExecStart=,
384 except that multiple command lines are allowed and the commands are
385 executed one after the other, serially.
386 If any of those commands (not prefixed with "-") fail, the rest are
388 not executed and the unit is considered failed.
389 ExecStart= commands are only run after all ExecStartPre= commands
391 that were not prefixed with a "-" exit successfully.
392 ExecStartPost= commands are only run after the commands specified
394 in ExecStart= have been invoked successfully, as determined by
395 Type= (i.e. the process has been started for Type=simple or
396 Type=idle, the last ExecStart= process exited successfully for
397 Type=oneshot, the initial process exited successfully for
398 Type=forking, "READY=1" is sent for Type=notify, or the BusName=
399 has been taken for Type=dbus).
400 Note that ExecStartPre= may not be used to start long-running
402 processes. All processes forked off by processes invoked via
403 ExecStartPre= will be killed before the next service process is
404 run.
405 Note that if any of the commands specified in ExecStartPre=,
407 ExecStart=, or ExecStartPost= fail (and are not prefixed with "-",
408 see above) or time out before the service is fully up, execution
409 continues with commands specified in ExecStopPost=, the commands in
410 ExecStop= are skipped.
411 ExecReload=
413 Commands to execute to trigger a configuration reload in the
414 service. This argument takes multiple command lines, following the
415 same scheme as described for ExecStart= above. Use of this setting
416 is optional. Specifier and environment variable substitution is
417 supported here following the same scheme as for ExecStart=.
418 One additional, special environment variable is set: if known,
420 $MAINPID is set to the main process of the daemon, and may be used
421 for command lines like the following:
422 /bin/kill -HUP $MAINPID
424 Note however that reloading a daemon by sending a signal (as with
426 the example line above) is usually not a good choice, because this
427 is an asynchronous operation and hence not suitable to order
428 reloads of multiple services against each other. It is strongly
429 recommended to set ExecReload= to a command that not only triggers
430 a configuration reload of the daemon, but also synchronously waits
431 for it to complete.
432 ExecStop=
434 Commands to execute to stop the service started via ExecStart=.
435 This argument takes multiple command lines, following the same
436 scheme as described for ExecStart= above. Use of this setting is
437 optional. After the commands configured in this option are run, it
438 is implied that the service is stopped, and any processes remaining
439 for it are terminated according to the KillMode= setting (see
440 systemd.kill(5)). If this option is not specified, the process is
441 terminated by sending the signal specified in KillSignal= when
442 service stop is requested. Specifier and environment variable
443 substitution is supported (including $MAINPID, see above).
444 Note that it is usually not sufficient to specify a command for
446 this setting that only asks the service to terminate (for example,
447 by queuing some form of termination signal for it), but does not
448 wait for it to do so. Since the remaining processes of the services
449 are killed according to KillMode= and KillSignal= as described
450 above immediately after the command exited, this may not result in
451 a clean stop. The specified command should hence be a synchronous
452 operation, not an asynchronous one.
453 Note that the commands specified in ExecStop= are only executed
455 when the service started successfully first. They are not invoked
456 if the service was never started at all, or in case its start-up
457 failed, for example because any of the commands specified in
458 ExecStart=, ExecStartPre= or ExecStartPost= failed (and weren't
459 prefixed with "-", see above) or timed out. Use ExecStopPost= to
460 invoke commands when a service failed to start up correctly and is
461 shut down again. Also note that the stop operation is always
462 performed if the service started successfully, even if the
463 processes in the service terminated on their own or were killed.
464 The stop commands must be prepared to deal with that case.
465 $MAINPID will be unset if systemd knows that the main process
466 exited by the time the stop commands are called.
467 Service restart requests are implemented as stop operations
469 followed by start operations. This means that ExecStop= and
470 ExecStopPost= are executed during a service restart operation.
471 It is recommended to use this setting for commands that communicate
473 with the service requesting clean termination. For post-mortem
474 clean-up steps use ExecStopPost= instead.
475 ExecStopPost=
477 Additional commands that are executed after the service is stopped.
478 This includes cases where the commands configured in ExecStop= were
479 used, where the service does not have any ExecStop= defined, or
480 where the service exited unexpectedly. This argument takes multiple
481 command lines, following the same scheme as described for
482 ExecStart=. Use of these settings is optional. Specifier and
483 environment variable substitution is supported. Note that – unlike
484 ExecStop= – commands specified with this setting are invoked when a
485 service failed to start up correctly and is shut down again.
486 It is recommended to use this setting for clean-up operations that
488 shall be executed even when the service failed to start up
489 correctly. Commands configured with this setting need to be able to
490 operate even if the service failed starting up half-way and left
491 incompletely initialized data around. As the service's processes
492 have been terminated already when the commands specified with this
493 setting are executed they should not attempt to communicate with
494 them.
495 Note that all commands that are configured with this setting are
497 invoked with the result code of the service, as well as the main
498 process' exit code and status, set in the $SERVICE_RESULT,
499 $EXIT_CODE and $EXIT_STATUS environment variables, see
500 systemd.exec(5) for details.
501 RestartSec=
503 Configures the time to sleep before restarting a service (as
504 configured with Restart=). Takes a unit-less value in seconds, or a
505 time span value such as "5min 20s". Defaults to 100ms.
506 TimeoutStartSec=
508 Configures the time to wait for start-up. If a daemon service does
509 not signal start-up completion within the configured time, the
510 service will be considered failed and will be shut down again.
511 Takes a unit-less value in seconds, or a time span value such as
512 "5min 20s". Pass "infinity" to disable the timeout logic. Defaults
513 to DefaultTimeoutStartSec= from the manager configuration file,
514 except when Type=oneshot is used, in which case the timeout is
515 disabled by default (see systemd-system.conf(5)).
516 If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this
518 may cause the start time to be extended beyond TimeoutStartSec=.
519 The first receipt of this message must occur before
520 TimeoutStartSec= is exceeded, and once the start time has exended
521 beyond TimeoutStartSec=, the service manager will allow the service
522 to continue to start, provided the service repeats
523 "EXTEND_TIMEOUT_USEC=..." within the interval specified until the
524 service startup status is finished by "READY=1". (see
525 sd_notify(3)).
526 TimeoutStopSec=
528 This option serves two purposes. First, it configures the time to
529 wait for each ExecStop= command. If any of them times out,
530 subsequent ExecStop= commands are skipped and the service will be
531 terminated by SIGTERM. If no ExecStop= commands are specified, the
532 service gets the SIGTERM immediately. Second, it configures the
533 time to wait for the service itself to stop. If it doesn't
534 terminate in the specified time, it will be forcibly terminated by
535 SIGKILL (see KillMode= in systemd.kill(5)). Takes a unit-less value
536 in seconds, or a time span value such as "5min 20s". Pass
537 "infinity" to disable the timeout logic. Defaults to
538 DefaultTimeoutStopSec= from the manager configuration file (see
539 systemd-system.conf(5)).
540 If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this
542 may cause the stop time to be extended beyond TimeoutStopSec=. The
543 first receipt of this message must occur before TimeoutStopSec= is
544 exceeded, and once the stop time has exended beyond
545 TimeoutStopSec=, the service manager will allow the service to
546 continue to stop, provided the service repeats
547 "EXTEND_TIMEOUT_USEC=..." within the interval specified, or
548 terminates itself (see sd_notify(3)).
549 TimeoutSec=
551 A shorthand for configuring both TimeoutStartSec= and
552 TimeoutStopSec= to the specified value.
553 RuntimeMaxSec=
555 Configures a maximum time for the service to run. If this is used
556 and the service has been active for longer than the specified time
557 it is terminated and put into a failure state. Note that this
558 setting does not have any effect on Type=oneshot services, as they
559 terminate immediately after activation completed. Pass "infinity"
560 (the default) to configure no runtime limit.
561 If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this
563 may cause the runtime to be extended beyond RuntimeMaxSec=. The
564 first receipt of this message must occur before RuntimeMaxSec= is
565 exceeded, and once the runtime has exended beyond RuntimeMaxSec=,
566 the service manager will allow the service to continue to run,
567 provided the service repeats "EXTEND_TIMEOUT_USEC=..." within the
568 interval specified until the service shutdown is achieved by
569 "STOPPING=1" (or termination). (see sd_notify(3)).
570 WatchdogSec=
572 Configures the watchdog timeout for a service. The watchdog is
573 activated when the start-up is completed. The service must call
574 sd_notify(3) regularly with "WATCHDOG=1" (i.e. the "keep-alive
575 ping"). If the time between two such calls is larger than the
576 configured time, then the service is placed in a failed state and
577 it will be terminated with SIGABRT (or the signal specified by
578 WatchdogSignal=). By setting Restart= to on-failure, on-watchdog,
579 on-abnormal or always, the service will be automatically restarted.
580 The time configured here will be passed to the executed service
581 process in the WATCHDOG_USEC= environment variable. This allows
582 daemons to automatically enable the keep-alive pinging logic if
583 watchdog support is enabled for the service. If this option is
584 used, NotifyAccess= (see below) should be set to open access to the
585 notification socket provided by systemd. If NotifyAccess= is not
586 set, it will be implicitly set to main. Defaults to 0, which
587 disables this feature. The service can check whether the service
588 manager expects watchdog keep-alive notifications. See
589 sd_watchdog_enabled(3) for details. sd_event_set_watchdog(3) may
590 be used to enable automatic watchdog notification support.
591 Restart=
593 Configures whether the service shall be restarted when the service
594 process exits, is killed, or a timeout is reached. The service
595 process may be the main service process, but it may also be one of
596 the processes specified with ExecStartPre=, ExecStartPost=,
597 ExecStop=, ExecStopPost=, or ExecReload=. When the death of the
598 process is a result of systemd operation (e.g. service stop or
599 restart), the service will not be restarted. Timeouts include
600 missing the watchdog "keep-alive ping" deadline and a service
601 start, reload, and stop operation timeouts.
602 Takes one of no, on-success, on-failure, on-abnormal, on-watchdog,
604 on-abort, or always. If set to no (the default), the service will
605 not be restarted. If set to on-success, it will be restarted only
606 when the service process exits cleanly. In this context, a clean
607 exit means an exit code of 0, or one of the signals SIGHUP, SIGINT,
608 SIGTERM or SIGPIPE, and additionally, exit statuses and signals
609 specified in SuccessExitStatus=. If set to on-failure, the service
610 will be restarted when the process exits with a non-zero exit code,
611 is terminated by a signal (including on core dump, but excluding
612 the aforementioned four signals), when an operation (such as
613 service reload) times out, and when the configured watchdog timeout
614 is triggered. If set to on-abnormal, the service will be restarted
615 when the process is terminated by a signal (including on core dump,
616 excluding the aforementioned four signals), when an operation times
617 out, or when the watchdog timeout is triggered. If set to on-abort,
618 the service will be restarted only if the service process exits due
619 to an uncaught signal not specified as a clean exit status. If set
620 to on-watchdog, the service will be restarted only if the watchdog
621 timeout for the service expires. If set to always, the service will
622 be restarted regardless of whether it exited cleanly or not, got
623 terminated abnormally by a signal, or hit a timeout.
624 Table 2. Exit causes and the effect of the Restart= settings on
626 them
627 ┌──────────────┬────┬────────┬────────────┬────────────┬─────────────┬──────────┬─────────────┐
628 │Restart │ no │ always │ on-success │ on-failure │ on-abnormal │ on-abort │ on-watchdog │
629 │settings/Exit │ │ │ │ │ │ │ │
630 │causes │ │ │ │ │ │ │ │
631 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
632 │Clean exit │ │ X │ X │ │ │ │ │
633 │code or │ │ │ │ │ │ │ │
634 │signal │ │ │ │ │ │ │ │
635 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
636 │Unclean exit │ │ X │ │ X │ │ │ │
637 │code │ │ │ │ │ │ │ │
638 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
639 │Unclean │ │ X │ │ X │ X │ X │ │
640 │signal │ │ │ │ │ │ │ │
641 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
642 │Timeout │ │ X │ │ X │ X │ │ │
643 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
644 │Watchdog │ │ X │ │ X │ X │ │ X │
645 └──────────────┴────┴────────┴────────────┴────────────┴─────────────┴──────────┴─────────────┘
646 As exceptions to the setting above, the service will not be
647 restarted if the exit code or signal is specified in
648 RestartPreventExitStatus= (see below) or the service is stopped
649 with systemctl stop or an equivalent operation. Also, the services
650 will always be restarted if the exit code or signal is specified in
651 RestartForceExitStatus= (see below).
652 Note that service restart is subject to unit start rate limiting
654 configured with StartLimitIntervalSec= and StartLimitBurst=, see
655 systemd.unit(5) for details. A restarted service enters the failed
656 state only after the start limits are reached.
657 Setting this to on-failure is the recommended choice for
659 long-running services, in order to increase reliability by
660 attempting automatic recovery from errors. For services that shall
661 be able to terminate on their own choice (and avoid immediate
662 restarting), on-abnormal is an alternative choice.
663 SuccessExitStatus=
665 Takes a list of exit status definitions that, when returned by the
666 main service process, will be considered successful termination, in
667 addition to the normal successful exit code 0 and the signals
668 SIGHUP, SIGINT, SIGTERM, and SIGPIPE. Exit status definitions can
669 either be numeric exit codes or termination signal names, separated
670 by spaces. For example:
671 SuccessExitStatus=1 2 8 SIGKILL
673 ensures that exit codes 1, 2, 8 and the termination signal SIGKILL
675 are considered clean service terminations.
676 This option may appear more than once, in which case the list of
678 successful exit statuses is merged. If the empty string is assigned
679 to this option, the list is reset, all prior assignments of this
680 option will have no effect.
681 RestartPreventExitStatus=
683 Takes a list of exit status definitions that, when returned by the
684 main service process, will prevent automatic service restarts,
685 regardless of the restart setting configured with Restart=. Exit
686 status definitions can either be numeric exit codes or termination
687 signal names, and are separated by spaces. Defaults to the empty
688 list, so that, by default, no exit status is excluded from the
689 configured restart logic. For example:
690 RestartPreventExitStatus=1 6 SIGABRT
692 ensures that exit codes 1 and 6 and the termination signal SIGABRT
694 will not result in automatic service restarting. This option may
695 appear more than once, in which case the list of restart-preventing
696 statuses is merged. If the empty string is assigned to this option,
697 the list is reset and all prior assignments of this option will
698 have no effect.
699 Note that this setting has no effect on processes configured via
701 ExecStartPre=, ExecStartPost=, ExecStop=, ExecStopPost= or
702 ExecReload=, but only on the main service process, i.e. either the
703 one invoked by ExecStart= or (depending on Type=, PIDFile=, ...)
704 the otherwise configured main process.
705 RestartForceExitStatus=
707 Takes a list of exit status definitions that, when returned by the
708 main service process, will force automatic service restarts,
709 regardless of the restart setting configured with Restart=. The
710 argument format is similar to RestartPreventExitStatus=.
711 RootDirectoryStartOnly=
713 Takes a boolean argument. If true, the root directory, as
714 configured with the RootDirectory= option (see systemd.exec(5) for
715 more information), is only applied to the process started with
716 ExecStart=, and not to the various other ExecStartPre=,
717 ExecStartPost=, ExecReload=, ExecStop=, and ExecStopPost= commands.
718 If false, the setting is applied to all configured commands the
719 same way. Defaults to false.
720 NonBlocking=
722 Set the O_NONBLOCK flag for all file descriptors passed via
723 socket-based activation. If true, all file descriptors >= 3 (i.e.
724 all except stdin, stdout, stderr), excluding those passed in via
725 the file descriptor storage logic (see FileDescriptorStoreMax= for
726 details), will have the O_NONBLOCK flag set and hence are in
727 non-blocking mode. This option is only useful in conjunction with a
728 socket unit, as described in systemd.socket(5) and has no effect on
729 file descriptors which were previously saved in the file-descriptor
730 store for example. Defaults to false.
731 NotifyAccess=
733 Controls access to the service status notification socket, as
734 accessible via the sd_notify(3) call. Takes one of none (the
735 default), main, exec or all. If none, no daemon status updates are
736 accepted from the service processes, all status update messages are
737 ignored. If main, only service updates sent from the main process
738 of the service are accepted. If exec, only service updates sent
739 from any of the main or control processes originating from one of
740 the Exec*= commands are accepted. If all, all services updates from
741 all members of the service's control group are accepted. This
742 option should be set to open access to the notification socket when
743 using Type=notify or WatchdogSec= (see above). If those options are
744 used but NotifyAccess= is not configured, it will be implicitly set
745 to main.
746 Note that sd_notify() notifications may be attributed to units
748 correctly only if either the sending process is still around at the
749 time PID 1 processes the message, or if the sending process is
750 explicitly runtime-tracked by the service manager. The latter is
751 the case if the service manager originally forked off the process,
752 i.e. on all processes that match main or exec. Conversely, if an
753 auxiliary process of the unit sends an sd_notify() message and
754 immediately exits, the service manager might not be able to
755 properly attribute the message to the unit, and thus will ignore
756 it, even if NotifyAccess=all is set for it.
757 Sockets=
759 Specifies the name of the socket units this service shall inherit
760 socket file descriptors from when the service is started. Normally,
761 it should not be necessary to use this setting, as all socket file
762 descriptors whose unit shares the same name as the service (subject
763 to the different unit name suffix of course) are passed to the
764 spawned process.
765 Note that the same socket file descriptors may be passed to
767 multiple processes simultaneously. Also note that a different
768 service may be activated on incoming socket traffic than the one
769 which is ultimately configured to inherit the socket file
770 descriptors. Or, in other words: the Service= setting of .socket
771 units does not have to match the inverse of the Sockets= setting of
772 the .service it refers to.
773 This option may appear more than once, in which case the list of
775 socket units is merged. If the empty string is assigned to this
776 option, the list of sockets is reset, and all prior uses of this
777 setting will have no effect.
778 FileDescriptorStoreMax=
780 Configure how many file descriptors may be stored in the service
781 manager for the service using sd_pid_notify_with_fds(3)'s
782 "FDSTORE=1" messages. This is useful for implementing services that
783 can restart after an explicit request or a crash without losing
784 state. Any open sockets and other file descriptors which should not
785 be closed during the restart may be stored this way. Application
786 state can either be serialized to a file in /run, or better, stored
787 in a memfd_create(2) memory file descriptor. Defaults to 0, i.e. no
788 file descriptors may be stored in the service manager. All file
789 descriptors passed to the service manager from a specific service
790 are passed back to the service's main process on the next service
791 restart. Any file descriptors passed to the service manager are
792 automatically closed when POLLHUP or POLLERR is seen on them, or
793 when the service is fully stopped and no job is queued or being
794 executed for it. If this option is used, NotifyAccess= (see above)
795 should be set to open access to the notification socket provided by
796 systemd. If NotifyAccess= is not set, it will be implicitly set to
797 main.
798 USBFunctionDescriptors=
800 Configure the location of a file containing USB FunctionFS[2]
801 descriptors, for implementation of USB gadget functions. This is
802 used only in conjunction with a socket unit with ListenUSBFunction=
803 configured. The contents of this file are written to the ep0 file
804 after it is opened.
805 USBFunctionStrings=
807 Configure the location of a file containing USB FunctionFS strings.
808 Behavior is similar to USBFunctionDescriptors= above.
809 Check systemd.exec(5) and systemd.kill(5) for more settings.
811
813 This section describes command line parsing and variable and specifier
814 substitutions for ExecStart=, ExecStartPre=, ExecStartPost=,
815 ExecReload=, ExecStop=, and ExecStopPost= options.
816 Multiple command lines may be concatenated in a single directive by
818 separating them with semicolons (these semicolons must be passed as
819 separate words). Lone semicolons may be escaped as "\;".
820 Each command line is split on whitespace, with the first item being the
822 command to execute, and the subsequent items being the arguments.
823 Double quotes ("...") and single quotes ('...') may be used to wrap a
824 whole item (the opening quote may appear only at the beginning or after
825 whitespace that is not quoted, and the closing quote must be followed
826 by whitespace or the end of line), in which case everything until the
827 next matching quote becomes part of the same argument. Quotes
828 themselves are removed. C-style escapes are also supported. The table
829 below contains the list of known escape patterns. Only escape patterns
830 which match the syntax in the table are allowed; other patterns may be
831 added in the future and unknown patterns will result in a warning. In
832 particular, any backslashes should be doubled. Finally, a trailing
833 backslash ("\") may be used to merge lines.
834 This syntax is inspired by shell syntax, but only the meta-characters
836 and expansions described in the following paragraphs are understood,
837 and the expansion of variables is different. Specifically, redirection
838 using "<", "<<", ">", and ">>", pipes using "|", running programs in
839 the background using "&", and other elements of shell syntax are not
840 supported.
841 The command to execute may contain spaces, but control characters are
843 not allowed.
844 The command line accepts "%" specifiers as described in
846 systemd.unit(5).
847 Basic environment variable substitution is supported. Use "${FOO}" as
849 part of a word, or as a word of its own, on the command line, in which
850 case it will be replaced by the value of the environment variable
851 including all whitespace it contains, resulting in a single argument.
852 Use "$FOO" as a separate word on the command line, in which case it
853 will be replaced by the value of the environment variable split at
854 whitespace, resulting in zero or more arguments. For this type of
855 expansion, quotes are respected when splitting into words, and
856 afterwards removed.
857 If the command is not a full (absolute) path, it will be resolved to a
859 full path using a fixed search path determinted at compilation time.
860 Searched directories include /usr/local/bin/, /usr/bin/, /bin/ on
861 systems using split /usr/bin/ and /bin/ directories, and their sbin/
862 counterparts on systems using split bin/ and sbin/. It is thus safe to
863 use just the executable name in case of executables located in any of
864 the "standard" directories, and an absolute path must be used in other
865 cases. Using an absolute path is recommended to avoid ambiguity. Hint:
866 this search path may be queried using systemd-path
867 search-binaries-default.
868 Example:
870 Environment="ONE=one" 'TWO=two two'
872 ExecStart=echo $ONE $TWO ${TWO}
873 This will execute /bin/echo with four arguments: "one", "two", "two",
875 and "two two".
876 Example:
878 Environment=ONE='one' "TWO='two two' too" THREE=
880 ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
881 ExecStart=/bin/echo $ONE $TWO $THREE
882 This results in /bin/echo being called twice, the first time with
884 arguments "'one'", "'two two' too", "", and the second time with
885 arguments "one", "two two", "too".
886 To pass a literal dollar sign, use "$$". Variables whose value is not
888 known at expansion time are treated as empty strings. Note that the
889 first argument (i.e. the program to execute) may not be a variable.
890 Variables to be used in this fashion may be defined through
892 Environment= and EnvironmentFile=. In addition, variables listed in the
893 section "Environment variables in spawned processes" in
894 systemd.exec(5), which are considered "static configuration", may be
895 used (this includes e.g. $USER, but not $TERM).
896 Note that shell command lines are not directly supported. If shell
898 command lines are to be used, they need to be passed explicitly to a
899 shell implementation of some kind. Example:
900 ExecStart=sh -c 'dmesg | tac'
902 Example:
904 ExecStart=echo one ; echo "two two"
906 This will execute echo two times, each time with one argument: "one"
908 and "two two", respectively. Because two commands are specified,
909 Type=oneshot must be used.
910 Example:
912 ExecStart=echo / >/dev/null & \; \
914 ls
915 This will execute echo with five arguments: "/", ">/dev/null", "&",
917 ";", and "ls".
918 Table 3. C escapes supported in command lines and environment variables
920 ┌────────┬─────────────────────────┐
921 │Literal │ Actual value │
922 ├────────┼─────────────────────────┤
923 │"\a" │ bell │
924 ├────────┼─────────────────────────┤
925 │"\b" │ backspace │
926 ├────────┼─────────────────────────┤
927 │"\f" │ form feed │
928 ├────────┼─────────────────────────┤
929 │"\n" │ newline │
930 ├────────┼─────────────────────────┤
931 │"\r" │ carriage return │
932 ├────────┼─────────────────────────┤
933 │"\t" │ tab │
934 ├────────┼─────────────────────────┤
935 │"\v" │ vertical tab │
936 ├────────┼─────────────────────────┤
937 │"\\" │ backslash │
938 ├────────┼─────────────────────────┤
939 │"\"" │ double quotation mark │
940 ├────────┼─────────────────────────┤
941 │"\'" │ single quotation mark │
942 ├────────┼─────────────────────────┤
943 │"\s" │ space │
944 ├────────┼─────────────────────────┤
945 │"\xxx" │ character number xx in │
946 │ │ hexadecimal encoding │
947 ├────────┼─────────────────────────┤
948 │"\nnn" │ character number nnn in │
949 │ │ octal encoding │
950 └────────┴─────────────────────────┘
951
953 Example 1. Simple service
954 The following unit file creates a service that will execute
956 /usr/sbin/foo-daemon. Since no Type= is specified, the default
957 Type=simple will be assumed. systemd will assume the unit to be started
958 immediately after the program has begun executing.
959 [Unit]
961 Description=Foo
962 [Service]
964 ExecStart=/usr/sbin/foo-daemon
965 [Install]
967 WantedBy=multi-user.target
968 Note that systemd assumes here that the process started by systemd will
970 continue running until the service terminates. If the program
971 daemonizes itself (i.e. forks), please use Type=forking instead.
972 Since no ExecStop= was specified, systemd will send SIGTERM to all
974 processes started from this service, and after a timeout also SIGKILL.
975 This behavior can be modified, see systemd.kill(5) for details.
976 Note that this unit type does not include any type of notification when
978 a service has completed initialization. For this, you should use other
979 unit types, such as Type=notify if the service understands systemd's
980 notification protocol, Type=forking if the service can background
981 itself or Type=dbus if the unit acquires a DBus name once
982 initialization is complete. See below.
983 Example 2. Oneshot service
985 Sometimes, units should just execute an action without keeping active
987 processes, such as a filesystem check or a cleanup action on boot. For
988 this, Type=oneshot exists. Units of this type will wait until the
989 process specified terminates and then fall back to being inactive. The
990 following unit will perform a cleanup action:
991 [Unit]
993 Description=Cleanup old Foo data
994 [Service]
996 Type=oneshot
997 ExecStart=/usr/sbin/foo-cleanup
998 [Install]
1000 WantedBy=multi-user.target
1001 Note that systemd will consider the unit to be in the state "starting"
1003 until the program has terminated, so ordered dependencies will wait for
1004 the program to finish before starting themselves. The unit will revert
1005 to the "inactive" state after the execution is done, never reaching the
1006 "active" state. That means another request to start the unit will
1007 perform the action again.
1008 Type=oneshot are the only service units that may have more than one
1010 ExecStart= specified. They will be executed in order until either they
1011 are all successful or one of them fails.
1012 Example 3. Stoppable oneshot service
1014 Similarly to the oneshot services, there are sometimes units that need
1016 to execute a program to set up something and then execute another to
1017 shut it down, but no process remains active while they are considered
1018 "started". Network configuration can sometimes fall into this category.
1019 Another use case is if a oneshot service shall not be executed each
1020 time when they are pulled in as a dependency, but only the first time.
1021 For this, systemd knows the setting RemainAfterExit=yes, which causes
1023 systemd to consider the unit to be active if the start action exited
1024 successfully. This directive can be used with all types, but is most
1025 useful with Type=oneshot and Type=simple. With Type=oneshot, systemd
1026 waits until the start action has completed before it considers the unit
1027 to be active, so dependencies start only after the start action has
1028 succeeded. With Type=simple, dependencies will start immediately after
1029 the start action has been dispatched. The following unit provides an
1030 example for a simple static firewall.
1031 [Unit]
1033 Description=Simple firewall
1034 [Service]
1036 Type=oneshot
1037 RemainAfterExit=yes
1038 ExecStart=/usr/local/sbin/simple-firewall-start
1039 ExecStop=/usr/local/sbin/simple-firewall-stop
1040 [Install]
1042 WantedBy=multi-user.target
1043 Since the unit is considered to be running after the start action has
1045 exited, invoking systemctl start on that unit again will cause no
1046 action to be taken.
1047 Example 4. Traditional forking services
1049 Many traditional daemons/services background (i.e. fork, daemonize)
1051 themselves when starting. Set Type=forking in the service's unit file
1052 to support this mode of operation. systemd will consider the service to
1053 be in the process of initialization while the original program is still
1054 running. Once it exits successfully and at least a process remains (and
1055 RemainAfterExit=no), the service is considered started.
1056 Often, a traditional daemon only consists of one process. Therefore, if
1058 only one process is left after the original process terminates, systemd
1059 will consider that process the main process of the service. In that
1060 case, the $MAINPID variable will be available in ExecReload=,
1061 ExecStop=, etc.
1062 In case more than one process remains, systemd will be unable to
1064 determine the main process, so it will not assume there is one. In that
1065 case, $MAINPID will not expand to anything. However, if the process
1066 decides to write a traditional PID file, systemd will be able to read
1067 the main PID from there. Please set PIDFile= accordingly. Note that the
1068 daemon should write that file before finishing with its initialization.
1069 Otherwise, systemd might try to read the file before it exists.
1070 The following example shows a simple daemon that forks and just starts
1072 one process in the background:
1073 [Unit]
1075 Description=Some simple daemon
1076 [Service]
1078 Type=forking
1079 ExecStart=/usr/sbin/my-simple-daemon -d
1080 [Install]
1082 WantedBy=multi-user.target
1083 Please see systemd.kill(5) for details on how you can influence the way
1085 systemd terminates the service.
1086 Example 5. DBus services
1088 For services that acquire a name on the DBus system bus, use Type=dbus
1090 and set BusName= accordingly. The service should not fork (daemonize).
1091 systemd will consider the service to be initialized once the name has
1092 been acquired on the system bus. The following example shows a typical
1093 DBus service:
1094 [Unit]
1096 Description=Simple DBus service
1097 [Service]
1099 Type=dbus
1100 BusName=org.example.simple-dbus-service
1101 ExecStart=/usr/sbin/simple-dbus-service
1102 [Install]
1104 WantedBy=multi-user.target
1105 For bus-activatable services, do not include a "[Install]" section in
1107 the systemd service file, but use the SystemdService= option in the
1108 corresponding DBus service file, for example
1109 (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service):
1110 [D-BUS Service]
1112 Name=org.example.simple-dbus-service
1113 Exec=/usr/sbin/simple-dbus-service
1114 User=root
1115 SystemdService=simple-dbus-service.service
1116 Please see systemd.kill(5) for details on how you can influence the way
1118 systemd terminates the service.
1119 Example 6. Services that notify systemd about their initialization
1121 Type=simple services are really easy to write, but have the major
1123 disadvantage of systemd not being able to tell when initialization of
1124 the given service is complete. For this reason, systemd supports a
1125 simple notification protocol that allows daemons to make systemd aware
1126 that they are done initializing. Use Type=notify for this. A typical
1127 service file for such a daemon would look like this:
1128 [Unit]
1130 Description=Simple notifying service
1131 [Service]
1133 Type=notify
1134 ExecStart=/usr/sbin/simple-notifying-service
1135 [Install]
1137 WantedBy=multi-user.target
1138 Note that the daemon has to support systemd's notification protocol,
1140 else systemd will think the service has not started yet and kill it
1141 after a timeout. For an example of how to update daemons to support
1142 this protocol transparently, take a look at sd_notify(3). systemd will
1143 consider the unit to be in the 'starting' state until a readiness
1144 notification has arrived.
1145 Please see systemd.kill(5) for details on how you can influence the way
1147 systemd terminates the service.
1148
1150 systemd(1), systemctl(1), systemd-system.conf(5), systemd.unit(5),
1151 systemd.exec(5), systemd.resource-control(5), systemd.kill(5),
1152 systemd.directives(7)
1153
1155 1. Incompatibilities with SysV
1156 https://www.freedesktop.org/wiki/Software/systemd/Incompatibilities
1157 2. USB FunctionFS
1159 https://www.kernel.org/doc/Documentation/usb/functionfs.txt
1160systemd 241 SYSTEMD.SERVICE(5)