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 SysV init compat is enabled, systemd automatically creates service
28 units that wrap SysV init scripts (the service name is the same as the
29 name of the script, with a ".service" suffix added); see systemd-sysv-
30 generator(8).
31 The systemd-run(1) command allows creating .service and .scope units
33 dynamically and transiently from the command line.
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 unit files may include [Unit] and [Install] sections, which are
86 described in systemd.unit(5).
87 Service unit files must include a [Service] section, which carries
89 information about the service and the process it supervises. A number
90 of options that may be used in this section are shared with other unit
91 types. These options are documented in systemd.exec(5), systemd.kill(5)
92 and systemd.resource-control(5). The options specific to the [Service]
93 section of service units are the following:
94 Type=
96 Configures the process start-up type for this service unit. One of
97 simple, exec, forking, oneshot, dbus, notify or idle:
98 • If set to simple (the default if ExecStart= is specified but
100 neither Type= nor BusName= are), the service manager will
101 consider the unit started immediately after the main service
102 process has been forked off. It is expected that the process
103 configured with ExecStart= is the main process of the service.
104 In this mode, if the process offers functionality to other
105 processes on the system, its communication channels should be
106 installed before the service is started up (e.g. sockets set up
107 by systemd, via socket activation), as the service manager will
108 immediately proceed starting follow-up units, right after
109 creating the main service process, and before executing the
110 service's binary. Note that this means systemctl start command
111 lines for simple services will report success even if the
112 service's binary cannot be invoked successfully (for example
113 because the selected User= doesn't exist, or the service binary
114 is missing).
115 • The exec type is similar to simple, but the service manager
117 will consider the unit started immediately after the main
118 service binary has been executed. The service manager will
119 delay starting of follow-up units until that point. (Or in
120 other words: simple proceeds with further jobs right after
121 fork() returns, while exec will not proceed before both fork()
122 and execve() in the service process succeeded.) Note that this
123 means systemctl start command lines for exec services will
124 report failure when the service's binary cannot be invoked
125 successfully (for example because the selected User= doesn't
126 exist, or the service binary is missing).
127 • If set to forking, it is expected that the process configured
129 with ExecStart= will call fork() as part of its start-up. The
130 parent process is expected to exit when start-up is complete
131 and all communication channels are set up. The child continues
132 to run as the main service process, and the service manager
133 will consider the unit started when the parent process exits.
134 This is the behavior of traditional UNIX services. If this
135 setting is used, it is recommended to also use the PIDFile=
136 option, so that systemd can reliably identify the main process
137 of the service. systemd will proceed with starting follow-up
138 units as soon as the parent process exits.
139 • Behavior of oneshot is similar to simple; however, the service
141 manager will consider the unit up after the main process exits.
142 It will then start follow-up units. RemainAfterExit= is
143 particularly useful for this type of service. Type=oneshot is
144 the implied default if neither Type= nor ExecStart= are
145 specified. Note that if this option is used without
146 RemainAfterExit= the service will never enter "active" unit
147 state, but directly transition from "activating" to
148 "deactivating" or "dead" since no process is configured that
149 shall run continuously. In particular this means that after a
150 service of this type ran (and which has RemainAfterExit= not
151 set) it will not show up as started afterwards, but as dead.
152 • Behavior of dbus is similar to simple; however, it is expected
154 that the service acquires a name on the D-Bus bus, as
155 configured by BusName=. systemd will proceed with starting
156 follow-up units after the D-Bus bus name has been acquired.
157 Service units with this option configured implicitly gain
158 dependencies on the dbus.socket unit. This type is the default
159 if BusName= is specified. A service unit of this type is
160 considered to be in the activating state until the specified
161 bus name is acquired. It is considered activated while the bus
162 name is taken. Once the bus name is released the service is
163 considered being no longer functional which has the effect that
164 the service manager attempts to terminate any remaining
165 processes belonging to the service. Services that drop their
166 bus name as part of their shutdown logic thus should be
167 prepared to receive a SIGTERM (or whichever signal is
168 configured in KillSignal=) as result.
169 • Behavior of notify is similar to exec; however, it is expected
171 that the service sends a notification message via sd_notify(3)
172 or an equivalent call when it has finished starting up. systemd
173 will proceed with starting follow-up units after this
174 notification message has been sent. If this option is used,
175 NotifyAccess= (see below) should be set to open access to the
176 notification socket provided by systemd. If NotifyAccess= is
177 missing or set to none, it will be forcibly set to main.
178 • Behavior of idle is very similar to simple; however, actual
180 execution of the service program is delayed until all active
181 jobs are dispatched. This may be used to avoid interleaving of
182 output of shell services with the status output on the console.
183 Note that this type is useful only to improve console output,
184 it is not useful as a general unit ordering tool, and the
185 effect of this service type is subject to a 5s timeout, after
186 which the service program is invoked anyway.
187 It is generally recommended to use Type=simple for long-running
189 services whenever possible, as it is the simplest and fastest
190 option. However, as this service type won't propagate service
191 start-up failures and doesn't allow ordering of other units against
192 completion of initialization of the service (which for example is
193 useful if clients need to connect to the service through some form
194 of IPC, and the IPC channel is only established by the service
195 itself — in contrast to doing this ahead of time through socket or
196 bus activation or similar), it might not be sufficient for many
197 cases. If so, notify or dbus (the latter only in case the service
198 provides a D-Bus interface) are the preferred options as they allow
199 service program code to precisely schedule when to consider the
200 service started up successfully and when to proceed with follow-up
201 units. The notify service type requires explicit support in the
202 service codebase (as sd_notify() or an equivalent API needs to be
203 invoked by the service at the appropriate time) — if it's not
204 supported, then forking is an alternative: it supports the
205 traditional UNIX service start-up protocol. Finally, exec might be
206 an option for cases where it is enough to ensure the service binary
207 is invoked, and where the service binary itself executes no or
208 little initialization on its own (and its initialization is
209 unlikely to fail). Note that using any type other than simple
210 possibly delays the boot process, as the service manager needs to
211 wait for service initialization to complete. It is hence
212 recommended not to needlessly use any types other than simple.
213 (Also note it is generally not recommended to use idle or oneshot
214 for long-running services.)
215 ExitType=
217 Specifies when the manager should consider the service to be
218 finished. One of main or cgroup:
219 • If set to main (the default), the service manager will consider
221 the unit stopped when the main process, which is determined
222 according to the Type=, exits. Consequently, it cannot be used
223 with Type=oneshot.
224 • If set to cgroup, the service will be considered running as
226 long as at least one process in the cgroup has not exited.
227 It is generally recommended to use ExitType=main when a service has
229 a known forking model and a main process can reliably be
230 determined. ExitType= cgroup is meant for applications whose
231 forking model is not known ahead of time and which might not have a
232 specific main process. It is well suited for transient or
233 automatically generated services, such as graphical applications
234 inside of a desktop environment.
235 RemainAfterExit=
237 Takes a boolean value that specifies whether the service shall be
238 considered active even when all its processes exited. Defaults to
239 no.
240 GuessMainPID=
242 Takes a boolean value that specifies whether systemd should try to
243 guess the main PID of a service if it cannot be determined
244 reliably. This option is ignored unless Type=forking is set and
245 PIDFile= is unset because for the other types or with an explicitly
246 configured PID file, the main PID is always known. The guessing
247 algorithm might come to incorrect conclusions if a daemon consists
248 of more than one process. If the main PID cannot be determined,
249 failure detection and automatic restarting of a service will not
250 work reliably. Defaults to yes.
251 PIDFile=
253 Takes a path referring to the PID file of the service. Usage of
254 this option is recommended for services where Type= is set to
255 forking. The path specified typically points to a file below /run/.
256 If a relative path is specified it is hence prefixed with /run/.
257 The service manager will read the PID of the main process of the
258 service from this file after start-up of the service. The service
259 manager will not write to the file configured here, although it
260 will remove the file after the service has shut down if it still
261 exists. The PID file does not need to be owned by a privileged
262 user, but if it is owned by an unprivileged user additional safety
263 restrictions are enforced: the file may not be a symlink to a file
264 owned by a different user (neither directly nor indirectly), and
265 the PID file must refer to a process already belonging to the
266 service.
267 Note that PID files should be avoided in modern projects. Use
269 Type=notify or Type=simple where possible, which does not require
270 use of PID files to determine the main process of a service and
271 avoids needless forking.
272 BusName=
274 Takes a D-Bus destination name that this service shall use. This
275 option is mandatory for services where Type= is set to dbus. It is
276 recommended to always set this property if known to make it easy to
277 map the service name to the D-Bus destination. In particular,
278 systemctl service-log-level/service-log-target verbs make use of
279 this.
280 ExecStart=
282 Commands with their arguments that are executed when this service
283 is started. The value is split into zero or more command lines
284 according to the rules described below (see section "Command Lines"
285 below).
286 Unless Type= is oneshot, exactly one command must be given. When
288 Type=oneshot is used, zero or more commands may be specified.
289 Commands may be specified by providing multiple command lines in
290 the same directive, or alternatively, this directive may be
291 specified more than once with the same effect. If the empty string
292 is assigned to this option, the list of commands to start is reset,
293 prior assignments of this option will have no effect. If no
294 ExecStart= is specified, then the service must have
295 RemainAfterExit=yes and at least one ExecStop= line set. (Services
296 lacking both ExecStart= and ExecStop= are not valid.)
297 For each of the specified commands, the first argument must be
299 either an absolute path to an executable or a simple file name
300 without any slashes. Optionally, this filename may be prefixed with
301 a number of special characters:
302 Table 1. Special executable prefixes
304 ┌───────┬────────────────────────────┐
305 │Prefix │ Effect │
306 ├───────┼────────────────────────────┤
307 │"@" │ If the executable path is │
308 │ │ prefixed with "@", the │
309 │ │ second specified token │
310 │ │ will be passed as │
311 │ │ "argv[0]" to the executed │
312 │ │ process (instead of the │
313 │ │ actual filename), followed │
314 │ │ by the further arguments │
315 │ │ specified. │
316 ├───────┼────────────────────────────┤
317 │"-" │ If the executable path is │
318 │ │ prefixed with "-", an exit │
319 │ │ code of the command │
320 │ │ normally considered a │
321 │ │ failure (i.e. non-zero │
322 │ │ exit status or abnormal │
323 │ │ exit due to signal) is │
324 │ │ recorded, but has no │
325 │ │ further effect and is │
326 │ │ considered equivalent to │
327 │ │ success. │
328 ├───────┼────────────────────────────┤
329 │":" │ If the executable path is │
330 │ │ prefixed with ":", │
331 │ │ environment variable │
332 │ │ substitution (as described │
333 │ │ by the "Command Lines" │
334 │ │ section below) is not │
335 │ │ applied. │
336 ├───────┼────────────────────────────┤
337 │"+" │ If the executable path is │
338 │ │ prefixed with "+" then the │
339 │ │ process is executed with │
340 │ │ full privileges. In this │
341 │ │ mode privilege │
342 │ │ restrictions configured │
343 │ │ with User=, Group=, │
344 │ │ CapabilityBoundingSet= or │
345 │ │ the various file system │
346 │ │ namespacing options (such │
347 │ │ as PrivateDevices=, │
348 │ │ PrivateTmp=) are not │
349 │ │ applied to the invoked │
350 │ │ command line (but still │
351 │ │ affect any other │
352 │ │ ExecStart=, ExecStop=, ... │
353 │ │ lines). │
354 ├───────┼────────────────────────────┤
355 │"!" │ Similar to the "+" │
356 │ │ character discussed above │
357 │ │ this permits invoking │
358 │ │ command lines with │
359 │ │ elevated privileges. │
360 │ │ However, unlike "+" the │
361 │ │ "!" character exclusively │
362 │ │ alters the effect of │
363 │ │ User=, Group= and │
364 │ │ SupplementaryGroups=, i.e. │
365 │ │ only the stanzas that │
366 │ │ affect user and group │
367 │ │ credentials. Note that │
368 │ │ this setting may be │
369 │ │ combined with │
370 │ │ DynamicUser=, in which │
371 │ │ case a dynamic user/group │
372 │ │ pair is allocated before │
373 │ │ the command is invoked, │
374 │ │ but credential changing is │
375 │ │ left to the executed │
376 │ │ process itself. │
377 ├───────┼────────────────────────────┤
378 │"!!" │ This prefix is very │
379 │ │ similar to "!", however it │
380 │ │ only has an effect on │
381 │ │ systems lacking support │
382 │ │ for ambient process │
383 │ │ capabilities, i.e. without │
384 │ │ support for │
385 │ │ AmbientCapabilities=. It's │
386 │ │ intended to be used for │
387 │ │ unit files that take │
388 │ │ benefit of ambient │
389 │ │ capabilities to run │
390 │ │ processes with minimal │
391 │ │ privileges wherever │
392 │ │ possible while remaining │
393 │ │ compatible with systems │
394 │ │ that lack ambient │
395 │ │ capabilities support. Note │
396 │ │ that when "!!" is used, │
397 │ │ and a system lacking │
398 │ │ ambient capability support │
399 │ │ is detected any configured │
400 │ │ SystemCallFilter= and │
401 │ │ CapabilityBoundingSet= │
402 │ │ stanzas are implicitly │
403 │ │ modified, in order to │
404 │ │ permit spawned processes │
405 │ │ to drop credentials and │
406 │ │ capabilities themselves, │
407 │ │ even if this is configured │
408 │ │ to not be allowed. │
409 │ │ Moreover, if this prefix │
410 │ │ is used and a system │
411 │ │ lacking ambient capability │
412 │ │ support is detected │
413 │ │ AmbientCapabilities= will │
414 │ │ be skipped and not be │
415 │ │ applied. On systems │
416 │ │ supporting ambient │
417 │ │ capabilities, "!!" has no │
418 │ │ effect and is redundant. │
419 └───────┴────────────────────────────┘
420 "@", "-", ":", and one of "+"/"!"/"!!" may be used together and
421 they can appear in any order. However, only one of "+", "!", "!!"
422 may be used at a time. Note that these prefixes are also supported
423 for the other command line settings, i.e. ExecStartPre=,
424 ExecStartPost=, ExecReload=, ExecStop= and ExecStopPost=.
425 If more than one command is specified, the commands are invoked
427 sequentially in the order they appear in the unit file. If one of
428 the commands fails (and is not prefixed with "-"), other lines are
429 not executed, and the unit is considered failed.
430 Unless Type=forking is set, the process started via this command
432 line will be considered the main process of the daemon.
433 ExecStartPre=, ExecStartPost=
435 Additional commands that are executed before or after the command
436 in ExecStart=, respectively. Syntax is the same as for ExecStart=,
437 except that multiple command lines are allowed and the commands are
438 executed one after the other, serially.
439 If any of those commands (not prefixed with "-") fail, the rest are
441 not executed and the unit is considered failed.
442 ExecStart= commands are only run after all ExecStartPre= commands
444 that were not prefixed with a "-" exit successfully.
445 ExecStartPost= commands are only run after the commands specified
447 in ExecStart= have been invoked successfully, as determined by
448 Type= (i.e. the process has been started for Type=simple or
449 Type=idle, the last ExecStart= process exited successfully for
450 Type=oneshot, the initial process exited successfully for
451 Type=forking, "READY=1" is sent for Type=notify, or the BusName=
452 has been taken for Type=dbus).
453 Note that ExecStartPre= may not be used to start long-running
455 processes. All processes forked off by processes invoked via
456 ExecStartPre= will be killed before the next service process is
457 run.
458 Note that if any of the commands specified in ExecStartPre=,
460 ExecStart=, or ExecStartPost= fail (and are not prefixed with "-",
461 see above) or time out before the service is fully up, execution
462 continues with commands specified in ExecStopPost=, the commands in
463 ExecStop= are skipped.
464 Note that the execution of ExecStartPost= is taken into account for
466 the purpose of Before=/After= ordering constraints.
467 ExecCondition=
469 Optional commands that are executed before the command(s) in
470 ExecStartPre=. Syntax is the same as for ExecStart=, except that
471 multiple command lines are allowed and the commands are executed
472 one after the other, serially.
473 The behavior is like an ExecStartPre= and condition check hybrid:
475 when an ExecCondition= command exits with exit code 1 through 254
476 (inclusive), the remaining commands are skipped and the unit is not
477 marked as failed. However, if an ExecCondition= command exits with
478 255 or abnormally (e.g. timeout, killed by a signal, etc.), the
479 unit will be considered failed (and remaining commands will be
480 skipped). Exit code of 0 or those matching SuccessExitStatus= will
481 continue execution to the next command(s).
482 The same recommendations about not running long-running processes
484 in ExecStartPre= also applies to ExecCondition=. ExecCondition=
485 will also run the commands in ExecStopPost=, as part of stopping
486 the service, in the case of any non-zero or abnormal exits, like
487 the ones described above.
488 ExecReload=
490 Commands to execute to trigger a configuration reload in the
491 service. This argument takes multiple command lines, following the
492 same scheme as described for ExecStart= above. Use of this setting
493 is optional. Specifier and environment variable substitution is
494 supported here following the same scheme as for ExecStart=.
495 One additional, special environment variable is set: if known,
497 $MAINPID is set to the main process of the daemon, and may be used
498 for command lines like the following:
499 ExecReload=kill -HUP $MAINPID
501 Note however that reloading a daemon by sending a signal (as with
503 the example line above) is usually not a good choice, because this
504 is an asynchronous operation and hence not suitable to order
505 reloads of multiple services against each other. It is strongly
506 recommended to set ExecReload= to a command that not only triggers
507 a configuration reload of the daemon, but also synchronously waits
508 for it to complete. For example, dbus-broker(1) uses the following:
509 ExecReload=busctl call org.freedesktop.DBus \
511 /org/freedesktop/DBus org.freedesktop.DBus \
512 ReloadConfig
513 ExecStop=
515 Commands to execute to stop the service started via ExecStart=.
516 This argument takes multiple command lines, following the same
517 scheme as described for ExecStart= above. Use of this setting is
518 optional. After the commands configured in this option are run, it
519 is implied that the service is stopped, and any processes remaining
520 for it are terminated according to the KillMode= setting (see
521 systemd.kill(5)). If this option is not specified, the process is
522 terminated by sending the signal specified in KillSignal= or
523 RestartKillSignal= when service stop is requested. Specifier and
524 environment variable substitution is supported (including $MAINPID,
525 see above).
526 Note that it is usually not sufficient to specify a command for
528 this setting that only asks the service to terminate (for example,
529 by sending some form of termination signal to it), but does not
530 wait for it to do so. Since the remaining processes of the services
531 are killed according to KillMode= and KillSignal= or
532 RestartKillSignal= as described above immediately after the command
533 exited, this may not result in a clean stop. The specified command
534 should hence be a synchronous operation, not an asynchronous one.
535 Note that the commands specified in ExecStop= are only executed
537 when the service started successfully first. They are not invoked
538 if the service was never started at all, or in case its start-up
539 failed, for example because any of the commands specified in
540 ExecStart=, ExecStartPre= or ExecStartPost= failed (and weren't
541 prefixed with "-", see above) or timed out. Use ExecStopPost= to
542 invoke commands when a service failed to start up correctly and is
543 shut down again. Also note that the stop operation is always
544 performed if the service started successfully, even if the
545 processes in the service terminated on their own or were killed.
546 The stop commands must be prepared to deal with that case.
547 $MAINPID will be unset if systemd knows that the main process
548 exited by the time the stop commands are called.
549 Service restart requests are implemented as stop operations
551 followed by start operations. This means that ExecStop= and
552 ExecStopPost= are executed during a service restart operation.
553 It is recommended to use this setting for commands that communicate
555 with the service requesting clean termination. For post-mortem
556 clean-up steps use ExecStopPost= instead.
557 ExecStopPost=
559 Additional commands that are executed after the service is stopped.
560 This includes cases where the commands configured in ExecStop= were
561 used, where the service does not have any ExecStop= defined, or
562 where the service exited unexpectedly. This argument takes multiple
563 command lines, following the same scheme as described for
564 ExecStart=. Use of these settings is optional. Specifier and
565 environment variable substitution is supported. Note that – unlike
566 ExecStop= – commands specified with this setting are invoked when a
567 service failed to start up correctly and is shut down again.
568 It is recommended to use this setting for clean-up operations that
570 shall be executed even when the service failed to start up
571 correctly. Commands configured with this setting need to be able to
572 operate even if the service failed starting up half-way and left
573 incompletely initialized data around. As the service's processes
574 have been terminated already when the commands specified with this
575 setting are executed they should not attempt to communicate with
576 them.
577 Note that all commands that are configured with this setting are
579 invoked with the result code of the service, as well as the main
580 process' exit code and status, set in the $SERVICE_RESULT,
581 $EXIT_CODE and $EXIT_STATUS environment variables, see
582 systemd.exec(5) for details.
583 Note that the execution of ExecStopPost= is taken into account for
585 the purpose of Before=/After= ordering constraints.
586 RestartSec=
588 Configures the time to sleep before restarting a service (as
589 configured with Restart=). Takes a unit-less value in seconds, or a
590 time span value such as "5min 20s". Defaults to 100ms.
591 TimeoutStartSec=
593 Configures the time to wait for start-up. If a daemon service does
594 not signal start-up completion within the configured time, the
595 service will be considered failed and will be shut down again. The
596 precise action depends on the TimeoutStartFailureMode= option.
597 Takes a unit-less value in seconds, or a time span value such as
598 "5min 20s". Pass "infinity" to disable the timeout logic. Defaults
599 to DefaultTimeoutStartSec= from the manager configuration file,
600 except when Type=oneshot is used, in which case the timeout is
601 disabled by default (see systemd-system.conf(5)).
602 If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this
604 may cause the start time to be extended beyond TimeoutStartSec=.
605 The first receipt of this message must occur before
606 TimeoutStartSec= is exceeded, and once the start time has extended
607 beyond TimeoutStartSec=, the service manager will allow the service
608 to continue to start, provided the service repeats
609 "EXTEND_TIMEOUT_USEC=..." within the interval specified until the
610 service startup status is finished by "READY=1". (see
611 sd_notify(3)).
612 TimeoutStopSec=
614 This option serves two purposes. First, it configures the time to
615 wait for each ExecStop= command. If any of them times out,
616 subsequent ExecStop= commands are skipped and the service will be
617 terminated by SIGTERM. If no ExecStop= commands are specified, the
618 service gets the SIGTERM immediately. This default behavior can be
619 changed by the TimeoutStopFailureMode= option. Second, it
620 configures the time to wait for the service itself to stop. If it
621 doesn't terminate in the specified time, it will be forcibly
622 terminated by SIGKILL (see KillMode= in systemd.kill(5)). Takes a
623 unit-less value in seconds, or a time span value such as "5min
624 20s". Pass "infinity" to disable the timeout logic. Defaults to
625 DefaultTimeoutStopSec= from the manager configuration file (see
626 systemd-system.conf(5)).
627 If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this
629 may cause the stop time to be extended beyond TimeoutStopSec=. The
630 first receipt of this message must occur before TimeoutStopSec= is
631 exceeded, and once the stop time has extended beyond
632 TimeoutStopSec=, the service manager will allow the service to
633 continue to stop, provided the service repeats
634 "EXTEND_TIMEOUT_USEC=..." within the interval specified, or
635 terminates itself (see sd_notify(3)).
636 TimeoutAbortSec=
638 This option configures the time to wait for the service to
639 terminate when it was aborted due to a watchdog timeout (see
640 WatchdogSec=). If the service has a short TimeoutStopSec= this
641 option can be used to give the system more time to write a core
642 dump of the service. Upon expiration the service will be forcibly
643 terminated by SIGKILL (see KillMode= in systemd.kill(5)). The core
644 file will be truncated in this case. Use TimeoutAbortSec= to set a
645 sensible timeout for the core dumping per service that is large
646 enough to write all expected data while also being short enough to
647 handle the service failure in due time.
648 Takes a unit-less value in seconds, or a time span value such as
650 "5min 20s". Pass an empty value to skip the dedicated watchdog
651 abort timeout handling and fall back TimeoutStopSec=. Pass
652 "infinity" to disable the timeout logic. Defaults to
653 DefaultTimeoutAbortSec= from the manager configuration file (see
654 systemd-system.conf(5)).
655 If a service of Type=notify handles SIGABRT itself (instead of
657 relying on the kernel to write a core dump) it can send
658 "EXTEND_TIMEOUT_USEC=..." to extended the abort time beyond
659 TimeoutAbortSec=. The first receipt of this message must occur
660 before TimeoutAbortSec= is exceeded, and once the abort time has
661 extended beyond TimeoutAbortSec=, the service manager will allow
662 the service to continue to abort, provided the service repeats
663 "EXTEND_TIMEOUT_USEC=..." within the interval specified, or
664 terminates itself (see sd_notify(3)).
665 TimeoutSec=
667 A shorthand for configuring both TimeoutStartSec= and
668 TimeoutStopSec= to the specified value.
669 TimeoutStartFailureMode=, TimeoutStopFailureMode=
671 These options configure the action that is taken in case a daemon
672 service does not signal start-up within its configured
673 TimeoutStartSec=, respectively if it does not stop within
674 TimeoutStopSec=. Takes one of terminate, abort and kill. Both
675 options default to terminate.
676 If terminate is set the service will be gracefully terminated by
678 sending the signal specified in KillSignal= (defaults to SIGTERM,
679 see systemd.kill(5)). If the service does not terminate the
680 FinalKillSignal= is sent after TimeoutStopSec=. If abort is set,
681 WatchdogSignal= is sent instead and TimeoutAbortSec= applies before
682 sending FinalKillSignal=. This setting may be used to analyze
683 services that fail to start-up or shut-down intermittently. By
684 using kill the service is immediately terminated by sending
685 FinalKillSignal= without any further timeout. This setting can be
686 used to expedite the shutdown of failing services.
687 RuntimeMaxSec=
689 Configures a maximum time for the service to run. If this is used
690 and the service has been active for longer than the specified time
691 it is terminated and put into a failure state. Note that this
692 setting does not have any effect on Type=oneshot services, as they
693 terminate immediately after activation completed. Pass "infinity"
694 (the default) to configure no runtime limit.
695 If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this
697 may cause the runtime to be extended beyond RuntimeMaxSec=. The
698 first receipt of this message must occur before RuntimeMaxSec= is
699 exceeded, and once the runtime has extended beyond RuntimeMaxSec=,
700 the service manager will allow the service to continue to run,
701 provided the service repeats "EXTEND_TIMEOUT_USEC=..." within the
702 interval specified until the service shutdown is achieved by
703 "STOPPING=1" (or termination). (see sd_notify(3)).
704 RuntimeRandomizedExtraSec=
706 This option modifies RuntimeMaxSec= by increasing the maximum
707 runtime by an evenly distributed duration between 0 and the
708 specified value (in seconds). If RuntimeMaxSec= is unspecified,
709 then this feature will be disabled.
710 WatchdogSec=
712 Configures the watchdog timeout for a service. The watchdog is
713 activated when the start-up is completed. The service must call
714 sd_notify(3) regularly with "WATCHDOG=1" (i.e. the "keep-alive
715 ping"). If the time between two such calls is larger than the
716 configured time, then the service is placed in a failed state and
717 it will be terminated with SIGABRT (or the signal specified by
718 WatchdogSignal=). By setting Restart= to on-failure, on-watchdog,
719 on-abnormal or always, the service will be automatically restarted.
720 The time configured here will be passed to the executed service
721 process in the WATCHDOG_USEC= environment variable. This allows
722 daemons to automatically enable the keep-alive pinging logic if
723 watchdog support is enabled for the service. If this option is
724 used, NotifyAccess= (see below) should be set to open access to the
725 notification socket provided by systemd. If NotifyAccess= is not
726 set, it will be implicitly set to main. Defaults to 0, which
727 disables this feature. The service can check whether the service
728 manager expects watchdog keep-alive notifications. See
729 sd_watchdog_enabled(3) for details. sd_event_set_watchdog(3) may
730 be used to enable automatic watchdog notification support.
731 Restart=
733 Configures whether the service shall be restarted when the service
734 process exits, is killed, or a timeout is reached. The service
735 process may be the main service process, but it may also be one of
736 the processes specified with ExecStartPre=, ExecStartPost=,
737 ExecStop=, ExecStopPost=, or ExecReload=. When the death of the
738 process is a result of systemd operation (e.g. service stop or
739 restart), the service will not be restarted. Timeouts include
740 missing the watchdog "keep-alive ping" deadline and a service
741 start, reload, and stop operation timeouts.
742 Takes one of no, on-success, on-failure, on-abnormal, on-watchdog,
744 on-abort, or always. If set to no (the default), the service will
745 not be restarted. If set to on-success, it will be restarted only
746 when the service process exits cleanly. In this context, a clean
747 exit means any of the following:
748 • exit code of 0;
750 • for types other than Type=oneshot, one of the signals SIGHUP,
752 SIGINT, SIGTERM, or SIGPIPE;
753 • exit statuses and signals specified in SuccessExitStatus=.
755 If set to on-failure, the service will be restarted when the
757 process exits with a non-zero exit code, is terminated by a signal
758 (including on core dump, but excluding the aforementioned four
759 signals), when an operation (such as service reload) times out, and
760 when the configured watchdog timeout is triggered. If set to
761 on-abnormal, the service will be restarted when the process is
762 terminated by a signal (including on core dump, excluding the
763 aforementioned four signals), when an operation times out, or when
764 the watchdog timeout is triggered. If set to on-abort, the service
765 will be restarted only if the service process exits due to an
766 uncaught signal not specified as a clean exit status. If set to
767 on-watchdog, the service will be restarted only if the watchdog
768 timeout for the service expires. If set to always, the service will
769 be restarted regardless of whether it exited cleanly or not, got
770 terminated abnormally by a signal, or hit a timeout.
771 Table 2. Exit causes and the effect of the Restart= settings
773 ┌──────────────┬────┬────────┬────────────┬────────────┬─────────────┬──────────┬─────────────┐
774 │Restart │ no │ always │ on-success │ on-failure │ on-abnormal │ on-abort │ on-watchdog │
775 │settings/Exit │ │ │ │ │ │ │ │
776 │causes │ │ │ │ │ │ │ │
777 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
778 │Clean exit │ │ X │ X │ │ │ │ │
779 │code or │ │ │ │ │ │ │ │
780 │signal │ │ │ │ │ │ │ │
781 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
782 │Unclean exit │ │ X │ │ X │ │ │ │
783 │code │ │ │ │ │ │ │ │
784 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
785 │Unclean │ │ X │ │ X │ X │ X │ │
786 │signal │ │ │ │ │ │ │ │
787 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
788 │Timeout │ │ X │ │ X │ X │ │ │
789 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
790 │Watchdog │ │ X │ │ X │ X │ │ X │
791 └──────────────┴────┴────────┴────────────┴────────────┴─────────────┴──────────┴─────────────┘
792 As exceptions to the setting above, the service will not be
793 restarted if the exit code or signal is specified in
794 RestartPreventExitStatus= (see below) or the service is stopped
795 with systemctl stop or an equivalent operation. Also, the services
796 will always be restarted if the exit code or signal is specified in
797 RestartForceExitStatus= (see below).
798 Note that service restart is subject to unit start rate limiting
800 configured with StartLimitIntervalSec= and StartLimitBurst=, see
801 systemd.unit(5) for details. A restarted service enters the failed
802 state only after the start limits are reached.
803 Setting this to on-failure is the recommended choice for
805 long-running services, in order to increase reliability by
806 attempting automatic recovery from errors. For services that shall
807 be able to terminate on their own choice (and avoid immediate
808 restarting), on-abnormal is an alternative choice.
809 SuccessExitStatus=
811 Takes a list of exit status definitions that, when returned by the
812 main service process, will be considered successful termination, in
813 addition to the normal successful exit status 0 and, except for
814 Type=oneshot, the signals SIGHUP, SIGINT, SIGTERM, and SIGPIPE.
815 Exit status definitions can be numeric termination statuses,
816 termination status names, or termination signal names, separated by
817 spaces. See the Process Exit Codes section in systemd.exec(5) for a
818 list of termination status names (for this setting only the part
819 without the "EXIT_" or "EX_" prefix should be used). See signal(7)
820 for a list of signal names.
821 Note that this setting does not change the mapping between numeric
823 exit statuses and their names, i.e. regardless how this setting is
824 used 0 will still be mapped to "SUCCESS" (and thus typically shown
825 as "0/SUCCESS" in tool outputs) and 1 to "FAILURE" (and thus
826 typically shown as "1/FAILURE"), and so on. It only controls what
827 happens as effect of these exit statuses, and how it propagates to
828 the state of the service as a whole.
829 This option may appear more than once, in which case the list of
831 successful exit statuses is merged. If the empty string is assigned
832 to this option, the list is reset, all prior assignments of this
833 option will have no effect.
834 Example 1. A service with the SuccessExitStatus= setting
836 SuccessExitStatus=TEMPFAIL 250 SIGKILL
838 Exit status 75 (TEMPFAIL), 250, and the termination signal SIGKILL
840 are considered clean service terminations.
841 Note: systemd-analyze exit-status may be used to list exit statuses
843 and translate between numerical status values and names.
844 RestartPreventExitStatus=
846 Takes a list of exit status definitions that, when returned by the
847 main service process, will prevent automatic service restarts,
848 regardless of the restart setting configured with Restart=. Exit
849 status definitions can either be numeric exit codes or termination
850 signal names, and are separated by spaces. Defaults to the empty
851 list, so that, by default, no exit status is excluded from the
852 configured restart logic. For example:
853 RestartPreventExitStatus=1 6 SIGABRT
855 ensures that exit codes 1 and 6 and the termination signal SIGABRT
857 will not result in automatic service restarting. This option may
858 appear more than once, in which case the list of restart-preventing
859 statuses is merged. If the empty string is assigned to this option,
860 the list is reset and all prior assignments of this option will
861 have no effect.
862 Note that this setting has no effect on processes configured via
864 ExecStartPre=, ExecStartPost=, ExecStop=, ExecStopPost= or
865 ExecReload=, but only on the main service process, i.e. either the
866 one invoked by ExecStart= or (depending on Type=, PIDFile=, ...)
867 the otherwise configured main process.
868 RestartForceExitStatus=
870 Takes a list of exit status definitions that, when returned by the
871 main service process, will force automatic service restarts,
872 regardless of the restart setting configured with Restart=. The
873 argument format is similar to RestartPreventExitStatus=.
874 RootDirectoryStartOnly=
876 Takes a boolean argument. If true, the root directory, as
877 configured with the RootDirectory= option (see systemd.exec(5) for
878 more information), is only applied to the process started with
879 ExecStart=, and not to the various other ExecStartPre=,
880 ExecStartPost=, ExecReload=, ExecStop=, and ExecStopPost= commands.
881 If false, the setting is applied to all configured commands the
882 same way. Defaults to false.
883 NonBlocking=
885 Set the O_NONBLOCK flag for all file descriptors passed via
886 socket-based activation. If true, all file descriptors >= 3 (i.e.
887 all except stdin, stdout, stderr), excluding those passed in via
888 the file descriptor storage logic (see FileDescriptorStoreMax= for
889 details), will have the O_NONBLOCK flag set and hence are in
890 non-blocking mode. This option is only useful in conjunction with a
891 socket unit, as described in systemd.socket(5) and has no effect on
892 file descriptors which were previously saved in the file-descriptor
893 store for example. Defaults to false.
894 NotifyAccess=
896 Controls access to the service status notification socket, as
897 accessible via the sd_notify(3) call. Takes one of none (the
898 default), main, exec or all. If none, no daemon status updates are
899 accepted from the service processes, all status update messages are
900 ignored. If main, only service updates sent from the main process
901 of the service are accepted. If exec, only service updates sent
902 from any of the main or control processes originating from one of
903 the Exec*= commands are accepted. If all, all services updates from
904 all members of the service's control group are accepted. This
905 option should be set to open access to the notification socket when
906 using Type=notify or WatchdogSec= (see above). If those options are
907 used but NotifyAccess= is not configured, it will be implicitly set
908 to main.
909 Note that sd_notify() notifications may be attributed to units
911 correctly only if either the sending process is still around at the
912 time PID 1 processes the message, or if the sending process is
913 explicitly runtime-tracked by the service manager. The latter is
914 the case if the service manager originally forked off the process,
915 i.e. on all processes that match main or exec. Conversely, if an
916 auxiliary process of the unit sends an sd_notify() message and
917 immediately exits, the service manager might not be able to
918 properly attribute the message to the unit, and thus will ignore
919 it, even if NotifyAccess=all is set for it.
920 Hence, to eliminate all race conditions involving lookup of the
922 client's unit and attribution of notifications to units correctly,
923 sd_notify_barrier() may be used. This call acts as a
924 synchronization point and ensures all notifications sent before
925 this call have been picked up by the service manager when it
926 returns successfully. Use of sd_notify_barrier() is needed for
927 clients which are not invoked by the service manager, otherwise
928 this synchronization mechanism is unnecessary for attribution of
929 notifications to the unit.
930 Sockets=
932 Specifies the name of the socket units this service shall inherit
933 socket file descriptors from when the service is started. Normally,
934 it should not be necessary to use this setting, as all socket file
935 descriptors whose unit shares the same name as the service (subject
936 to the different unit name suffix of course) are passed to the
937 spawned process.
938 Note that the same socket file descriptors may be passed to
940 multiple processes simultaneously. Also note that a different
941 service may be activated on incoming socket traffic than the one
942 which is ultimately configured to inherit the socket file
943 descriptors. Or, in other words: the Service= setting of .socket
944 units does not have to match the inverse of the Sockets= setting of
945 the .service it refers to.
946 This option may appear more than once, in which case the list of
948 socket units is merged. Note that once set, clearing the list of
949 sockets again (for example, by assigning the empty string to this
950 option) is not supported.
951 FileDescriptorStoreMax=
953 Configure how many file descriptors may be stored in the service
954 manager for the service using sd_pid_notify_with_fds(3)'s
955 "FDSTORE=1" messages. This is useful for implementing services that
956 can restart after an explicit request or a crash without losing
957 state. Any open sockets and other file descriptors which should not
958 be closed during the restart may be stored this way. Application
959 state can either be serialized to a file in /run/, or better,
960 stored in a memfd_create(2) memory file descriptor. Defaults to 0,
961 i.e. no file descriptors may be stored in the service manager. All
962 file descriptors passed to the service manager from a specific
963 service are passed back to the service's main process on the next
964 service restart (see sd_listen_fds(3) for details about the precise
965 protocol used and the order in which the file descriptors are
966 passed). Any file descriptors passed to the service manager are
967 automatically closed when POLLHUP or POLLERR is seen on them, or
968 when the service is fully stopped and no job is queued or being
969 executed for it. If this option is used, NotifyAccess= (see above)
970 should be set to open access to the notification socket provided by
971 systemd. If NotifyAccess= is not set, it will be implicitly set to
972 main.
973 USBFunctionDescriptors=
975 Configure the location of a file containing USB FunctionFS[1]
976 descriptors, for implementation of USB gadget functions. This is
977 used only in conjunction with a socket unit with ListenUSBFunction=
978 configured. The contents of this file are written to the ep0 file
979 after it is opened.
980 USBFunctionStrings=
982 Configure the location of a file containing USB FunctionFS strings.
983 Behavior is similar to USBFunctionDescriptors= above.
984 OOMPolicy=
986 Configure the out-of-memory (OOM) kernel killer policy. Note that
987 the userspace OOM killer systemd-oomd.service(8) is a more flexible
988 solution that aims to prevent out-of-memory situations for the
989 userspace, not just the kernel.
990 On Linux, when memory becomes scarce to the point that the kernel
992 has trouble allocating memory for itself, it might decide to kill a
993 running process in order to free up memory and reduce memory
994 pressure. This setting takes one of continue, stop or kill. If set
995 to continue and a process of the service is killed by the kernel's
996 OOM killer this is logged but the service continues running. If set
997 to stop the event is logged but the service is terminated cleanly
998 by the service manager. If set to kill and one of the service's
999 processes is killed by the OOM killer the kernel is instructed to
1000 kill all remaining processes of the service too, by setting the
1001 memory.oom.group attribute to 1; also see kernel documentation[2].
1002 Defaults to the setting DefaultOOMPolicy= in systemd-system.conf(5)
1004 is set to, except for services where Delegate= is turned on, where
1005 it defaults to continue.
1006 Use the OOMScoreAdjust= setting to configure whether processes of
1008 the unit shall be considered preferred or less preferred candidates
1009 for process termination by the Linux OOM killer logic. See
1010 systemd.exec(5) for details.
1011 This setting also applies to systemd-oomd, similar to the kernel
1013 OOM kills this setting determines the state of the service after
1014 systemd-oomd kills a cgroup associated with the service.
1015 Check systemd.unit(5), systemd.exec(5), and systemd.kill(5) for more
1017 settings.
1018
1020 This section describes command line parsing and variable and specifier
1021 substitutions for ExecStart=, ExecStartPre=, ExecStartPost=,
1022 ExecReload=, ExecStop=, and ExecStopPost= options.
1023 Multiple command lines may be concatenated in a single directive by
1025 separating them with semicolons (these semicolons must be passed as
1026 separate words). Lone semicolons may be escaped as "\;".
1027 Each command line is unquoted using the rules described in "Quoting"
1029 section in systemd.syntax(7). The first item becomes the command to
1030 execute, and the subsequent items the arguments.
1031 This syntax is inspired by shell syntax, but only the meta-characters
1033 and expansions described in the following paragraphs are understood,
1034 and the expansion of variables is different. Specifically, redirection
1035 using "<", "<<", ">", and ">>", pipes using "|", running programs in
1036 the background using "&", and other elements of shell syntax are not
1037 supported.
1038 The command to execute may contain spaces, but control characters are
1040 not allowed.
1041 The command line accepts "%" specifiers as described in
1043 systemd.unit(5).
1044 Basic environment variable substitution is supported. Use "${FOO}" as
1046 part of a word, or as a word of its own, on the command line, in which
1047 case it will be erased and replaced by the exact value of the
1048 environment variable (if any) including all whitespace it contains,
1049 always resulting in exactly a single argument. Use "$FOO" as a separate
1050 word on the command line, in which case it will be replaced by the
1051 value of the environment variable split at whitespace, resulting in
1052 zero or more arguments. For this type of expansion, quotes are
1053 respected when splitting into words, and afterwards removed.
1054 If the command is not a full (absolute) path, it will be resolved to a
1056 full path using a fixed search path determined at compilation time.
1057 Searched directories include /usr/local/bin/, /usr/bin/, /bin/ on
1058 systems using split /usr/bin/ and /bin/ directories, and their sbin/
1059 counterparts on systems using split bin/ and sbin/. It is thus safe to
1060 use just the executable name in case of executables located in any of
1061 the "standard" directories, and an absolute path must be used in other
1062 cases. Using an absolute path is recommended to avoid ambiguity. Hint:
1063 this search path may be queried using systemd-path
1064 search-binaries-default.
1065 Example:
1067 Environment="ONE=one" 'TWO=two two'
1069 ExecStart=echo $ONE $TWO ${TWO}
1070 This will execute /bin/echo with four arguments: "one", "two", "two",
1072 and "two two".
1073 Example:
1075 Environment=ONE='one' "TWO='two two' too" THREE=
1077 ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
1078 ExecStart=/bin/echo $ONE $TWO $THREE
1079 This results in /bin/echo being called twice, the first time with
1081 arguments "'one'", "'two two' too", "", and the second time with
1082 arguments "one", "two two", "too".
1083 To pass a literal dollar sign, use "$$". Variables whose value is not
1085 known at expansion time are treated as empty strings. Note that the
1086 first argument (i.e. the program to execute) may not be a variable.
1087 Variables to be used in this fashion may be defined through
1089 Environment= and EnvironmentFile=. In addition, variables listed in the
1090 section "Environment variables in spawned processes" in
1091 systemd.exec(5), which are considered "static configuration", may be
1092 used (this includes e.g. $USER, but not $TERM).
1093 Note that shell command lines are not directly supported. If shell
1095 command lines are to be used, they need to be passed explicitly to a
1096 shell implementation of some kind. Example:
1097 ExecStart=sh -c 'dmesg | tac'
1099 Example:
1101 ExecStart=echo one ; echo "two two"
1103 This will execute echo two times, each time with one argument: "one"
1105 and "two two", respectively. Because two commands are specified,
1106 Type=oneshot must be used.
1107 Example:
1109 ExecStart=echo / >/dev/null & \; \
1111 ls
1112 This will execute echo with five arguments: "/", ">/dev/null", "&",
1114 ";", and "ls".
1115
1117 Example 2. Simple service
1118 The following unit file creates a service that will execute
1120 /usr/sbin/foo-daemon. Since no Type= is specified, the default
1121 Type=simple will be assumed. systemd will assume the unit to be started
1122 immediately after the program has begun executing.
1123 [Unit]
1125 Description=Foo
1126 [Service]
1128 ExecStart=/usr/sbin/foo-daemon
1129 [Install]
1131 WantedBy=multi-user.target
1132 Note that systemd assumes here that the process started by systemd will
1134 continue running until the service terminates. If the program
1135 daemonizes itself (i.e. forks), please use Type=forking instead.
1136 Since no ExecStop= was specified, systemd will send SIGTERM to all
1138 processes started from this service, and after a timeout also SIGKILL.
1139 This behavior can be modified, see systemd.kill(5) for details.
1140 Note that this unit type does not include any type of notification when
1142 a service has completed initialization. For this, you should use other
1143 unit types, such as Type=notify if the service understands systemd's
1144 notification protocol, Type=forking if the service can background
1145 itself or Type=dbus if the unit acquires a DBus name once
1146 initialization is complete. See below.
1147 Example 3. Oneshot service
1149 Sometimes, units should just execute an action without keeping active
1151 processes, such as a filesystem check or a cleanup action on boot. For
1152 this, Type=oneshot exists. Units of this type will wait until the
1153 process specified terminates and then fall back to being inactive. The
1154 following unit will perform a cleanup action:
1155 [Unit]
1157 Description=Cleanup old Foo data
1158 [Service]
1160 Type=oneshot
1161 ExecStart=/usr/sbin/foo-cleanup
1162 [Install]
1164 WantedBy=multi-user.target
1165 Note that systemd will consider the unit to be in the state "starting"
1167 until the program has terminated, so ordered dependencies will wait for
1168 the program to finish before starting themselves. The unit will revert
1169 to the "inactive" state after the execution is done, never reaching the
1170 "active" state. That means another request to start the unit will
1171 perform the action again.
1172 Type=oneshot are the only service units that may have more than one
1174 ExecStart= specified. For units with multiple commands (Type=oneshot),
1175 all commands will be run again.
1176 For Type=oneshot, Restart=always and Restart=on-success are not
1178 allowed.
1179 Example 4. Stoppable oneshot service
1181 Similarly to the oneshot services, there are sometimes units that need
1183 to execute a program to set up something and then execute another to
1184 shut it down, but no process remains active while they are considered
1185 "started". Network configuration can sometimes fall into this category.
1186 Another use case is if a oneshot service shall not be executed each
1187 time when they are pulled in as a dependency, but only the first time.
1188 For this, systemd knows the setting RemainAfterExit=yes, which causes
1190 systemd to consider the unit to be active if the start action exited
1191 successfully. This directive can be used with all types, but is most
1192 useful with Type=oneshot and Type=simple. With Type=oneshot, systemd
1193 waits until the start action has completed before it considers the unit
1194 to be active, so dependencies start only after the start action has
1195 succeeded. With Type=simple, dependencies will start immediately after
1196 the start action has been dispatched. The following unit provides an
1197 example for a simple static firewall.
1198 [Unit]
1200 Description=Simple firewall
1201 [Service]
1203 Type=oneshot
1204 RemainAfterExit=yes
1205 ExecStart=/usr/local/sbin/simple-firewall-start
1206 ExecStop=/usr/local/sbin/simple-firewall-stop
1207 [Install]
1209 WantedBy=multi-user.target
1210 Since the unit is considered to be running after the start action has
1212 exited, invoking systemctl start on that unit again will cause no
1213 action to be taken.
1214 Example 5. Traditional forking services
1216 Many traditional daemons/services background (i.e. fork, daemonize)
1218 themselves when starting. Set Type=forking in the service's unit file
1219 to support this mode of operation. systemd will consider the service to
1220 be in the process of initialization while the original program is still
1221 running. Once it exits successfully and at least a process remains (and
1222 RemainAfterExit=no), the service is considered started.
1223 Often, a traditional daemon only consists of one process. Therefore, if
1225 only one process is left after the original process terminates, systemd
1226 will consider that process the main process of the service. In that
1227 case, the $MAINPID variable will be available in ExecReload=,
1228 ExecStop=, etc.
1229 In case more than one process remains, systemd will be unable to
1231 determine the main process, so it will not assume there is one. In that
1232 case, $MAINPID will not expand to anything. However, if the process
1233 decides to write a traditional PID file, systemd will be able to read
1234 the main PID from there. Please set PIDFile= accordingly. Note that the
1235 daemon should write that file before finishing with its initialization.
1236 Otherwise, systemd might try to read the file before it exists.
1237 The following example shows a simple daemon that forks and just starts
1239 one process in the background:
1240 [Unit]
1242 Description=Some simple daemon
1243 [Service]
1245 Type=forking
1246 ExecStart=/usr/sbin/my-simple-daemon -d
1247 [Install]
1249 WantedBy=multi-user.target
1250 Please see systemd.kill(5) for details on how you can influence the way
1252 systemd terminates the service.
1253 Example 6. DBus services
1255 For services that acquire a name on the DBus system bus, use Type=dbus
1257 and set BusName= accordingly. The service should not fork (daemonize).
1258 systemd will consider the service to be initialized once the name has
1259 been acquired on the system bus. The following example shows a typical
1260 DBus service:
1261 [Unit]
1263 Description=Simple DBus service
1264 [Service]
1266 Type=dbus
1267 BusName=org.example.simple-dbus-service
1268 ExecStart=/usr/sbin/simple-dbus-service
1269 [Install]
1271 WantedBy=multi-user.target
1272 For bus-activatable services, do not include a [Install] section in the
1274 systemd service file, but use the SystemdService= option in the
1275 corresponding DBus service file, for example
1276 (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service):
1277 [D-BUS Service]
1279 Name=org.example.simple-dbus-service
1280 Exec=/usr/sbin/simple-dbus-service
1281 User=root
1282 SystemdService=simple-dbus-service.service
1283 Please see systemd.kill(5) for details on how you can influence the way
1285 systemd terminates the service.
1286 Example 7. Services that notify systemd about their initialization
1288 Type=simple services are really easy to write, but have the major
1290 disadvantage of systemd not being able to tell when initialization of
1291 the given service is complete. For this reason, systemd supports a
1292 simple notification protocol that allows daemons to make systemd aware
1293 that they are done initializing. Use Type=notify for this. A typical
1294 service file for such a daemon would look like this:
1295 [Unit]
1297 Description=Simple notifying service
1298 [Service]
1300 Type=notify
1301 ExecStart=/usr/sbin/simple-notifying-service
1302 [Install]
1304 WantedBy=multi-user.target
1305 Note that the daemon has to support systemd's notification protocol,
1307 else systemd will think the service has not started yet and kill it
1308 after a timeout. For an example of how to update daemons to support
1309 this protocol transparently, take a look at sd_notify(3). systemd will
1310 consider the unit to be in the 'starting' state until a readiness
1311 notification has arrived.
1312 Please see systemd.kill(5) for details on how you can influence the way
1314 systemd terminates the service.
1315
1317 systemd(1), systemctl(1), systemd-system.conf(5), systemd.unit(5),
1318 systemd.exec(5), systemd.resource-control(5), systemd.kill(5),
1319 systemd.directives(7), systemd-run(1)
1320
1322 1. USB FunctionFS
1323 https://www.kernel.org/doc/Documentation/usb/functionfs.txt
1324 2. kernel documentation
1326 https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html
1327systemd 251 SYSTEMD.SERVICE(5)