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