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 Unless DefaultDependencies= is set to false, service units will
28 implicitly have dependencies of type Requires= and After= on
29 basic.target as well as dependencies of type Conflicts= and Before= on
30 shutdown.target. These ensure that normal service units pull in basic
31 system initialization, and are terminated cleanly prior to system
32 shutdown. Only services involved with early boot or late system
33 shutdown should disable this option.
34 If a service is requested under a certain name but no unit
36 configuration file is found, systemd looks for a SysV init script by
37 the same name (with the .service suffix removed) and dynamically
38 creates a service unit from that script. This is useful for
39 compatibility with SysV. Note that this compatibility is quite
40 comprehensive but not 100%. For details about the incompatibilities,
41 see the Incompatibilities with SysV[1] document.
42
44 Service files must include a "[Service]" section, which carries
45 information about the service and the process it supervises. A number
46 of options that may be used in this section are shared with other unit
47 types. These options are documented in systemd.exec(5) and
48 systemd.kill(5). The options specific to the "[Service]" section of
49 service units are the following:
50 Type=
52 Configures the process start-up type for this service unit. One of
53 simple, forking, oneshot, dbus, notify or idle.
54 If set to simple (the default if neither Type= nor BusName=, but
56 ExecStart= are specified), it is expected that the process
57 configured with ExecStart= is the main process of the service. In
58 this mode, if the process offers functionality to other processes
59 on the system, its communication channels should be installed
60 before the daemon is started up (e.g. sockets set up by systemd,
61 via socket activation), as systemd will immediately proceed
62 starting follow-up units.
63 If set to forking, it is expected that the process configured with
65 ExecStart= will call fork() as part of its start-up. The parent
66 process is expected to exit when start-up is complete and all
67 communication channels are set up. The child continues to run as
68 the main daemon process. This is the behavior of traditional UNIX
69 daemons. If this setting is used, it is recommended to also use the
70 PIDFile= option, so that systemd can identify the main process of
71 the daemon. systemd will proceed with starting follow-up units as
72 soon as the parent process exits.
73 Behavior of oneshot is similar to simple; however, it is expected
75 that the process has to exit before systemd starts follow-up units.
76 RemainAfterExit= is particularly useful for this type of service.
77 This is the implied default if neither Type= or ExecStart= are
78 specified.
79 Behavior of dbus is similar to simple; however, it is expected that
81 the daemon acquires a name on the D-Bus bus, as configured by
82 BusName=. systemd will proceed with starting follow-up units after
83 the D-Bus bus name has been acquired. Service units with this
84 option configured implicitly gain dependencies on the dbus.socket
85 unit. This type is the default if BusName= is specified.
86 Behavior of notify is similar to simple; however, it is expected
88 that the daemon sends a notification message via sd_notify(3) or an
89 equivalent call when it has finished starting up. systemd will
90 proceed with starting follow-up units after this notification
91 message has been sent. If this option is used, NotifyAccess= (see
92 below) should be set to open access to the notification socket
93 provided by systemd. If NotifyAccess= is not set, it will be
94 implicitly set to main. Note that currently Type=notify will not
95 work if used in combination with PrivateNetwork=yes.
96 Behavior of idle is very similar to simple; however, actual
98 execution of the service binary is delayed until all jobs are
99 dispatched. This may be used to avoid interleaving of output of
100 shell services with the status output on the console.
101 RemainAfterExit=
103 Takes a boolean value that specifies whether the service shall be
104 considered active even when all its processes exited. Defaults to
105 no.
106 GuessMainPID=
108 Takes a boolean value that specifies whether systemd should try to
109 guess the main PID of a service if it cannot be determined
110 reliably. This option is ignored unless Type=forking is set and
111 PIDFile= is unset because for the other types or with an explicitly
112 configured PID file, the main PID is always known. The guessing
113 algorithm might come to incorrect conclusions if a daemon consists
114 of more than one process. If the main PID cannot be determined,
115 failure detection and automatic restarting of a service will not
116 work reliably. Defaults to yes.
117 PIDFile=
119 Takes an absolute file name pointing to the PID file of this
120 daemon. Use of this option is recommended for services where Type=
121 is set to forking. systemd will read the PID of the main process of
122 the daemon after start-up of the service. systemd will not write to
123 the file configured here, although it will remove the file after
124 the service has shut down if it still exists.
125 BusName=
127 Takes a D-Bus bus name that this service is reachable as. This
128 option is mandatory for services where Type= is set to dbus.
129 BusPolicy=
131 If specified, a custom kdbus[2] endpoint will be created and
132 installed as the default bus node for the service. Such a custom
133 endpoint can hold an own set of policy rules that are enforced on
134 top of the bus-wide ones. The custom endpoint is named after the
135 service it was created for, and its node will be bind-mounted over
136 the default bus node location, so the service can only access the
137 bus through its own endpoint. Note that custom bus endpoints
138 default to a 'deny all' policy. Hence, if at least one BusPolicy=
139 directive is given, you have to make sure to add explicit rules for
140 everything the service should be able to do.
141 The value of this directive is comprised of two parts; the bus
143 name, and a verb to specify to granted access, which is one of see,
144 talk, or own. talk implies see, and own implies both talk and see.
145 If multiple access levels are specified for the same bus name, the
146 most powerful one takes effect.
147 Examples:
149 BusPolicy=org.freedesktop.systemd1 talk
151 BusPolicy=org.foo.bar see
153 This option is only available on kdbus enabled systems.
155 ExecStart=
157 Commands with their arguments that are executed when this service
158 is started. The value is split into zero or more command lines is
159 according to the rules described below (see section "Command Lines"
160 below).
161 When Type is not oneshot, only one command may and must be given.
163 When Type=oneshot is used, zero or more commands may be specified.
164 This can be specified by providing multiple command lines in the
165 same directive, or alternatively, this directive may be specified
166 more than once with the same effect. If the empty string is
167 assigned to this option, the list of commands to start is reset,
168 prior assignments of this option will have no effect. If no
169 ExecStart= is specified, then the service must have
170 RemainAfterExit=yes set.
171 For each of the specified commands, the first argument must be an
173 absolute path to an executable. Optionally, if this file name is
174 prefixed with "@", the second token will be passed as "argv[0]" to
175 the executed process, followed by the further arguments specified.
176 If the absolute filename is prefixed with "-", an exit code of the
177 command normally considered a failure (i.e. non-zero exit status or
178 abnormal exit due to signal) is ignored and considered success. If
179 both "-" and "@" are used, they can appear in either order.
180 If more than one command is specified, the commands are invoked
182 sequentially in the order they appear in the unit file. If one of
183 the commands fails (and is not prefixed with "-"), other lines are
184 not executed, and the unit is considered failed.
185 Unless Type=forking is set, the process started via this command
187 line will be considered the main process of the daemon.
188 ExecStartPre=, ExecStartPost=
190 Additional commands that are executed before or after the command
191 in ExecStart=, respectively. Syntax is the same as for ExecStart=,
192 except that multiple command lines are allowed and the commands are
193 executed one after the other, serially.
194 If any of those commands (not prefixed with "-") fail, the rest are
196 not executed and the unit is considered failed.
197 Note that ExecStartPre= may not be used to start long-running
199 processes. All processes forked off by processes invoked via
200 ExecStartPre= will be killed before the next service process is
201 run.
202 ExecReload=
204 Commands to execute to trigger a configuration reload in the
205 service. This argument takes multiple command lines, following the
206 same scheme as described for ExecStart= above. Use of this setting
207 is optional. Specifier and environment variable substitution is
208 supported here following the same scheme as for ExecStart=.
209 One additional, special environment variable is set: if known,
211 $MAINPID is set to the main process of the daemon, and may be used
212 for command lines like the following:
213 /bin/kill -HUP $MAINPID
215 Note however that reloading a daemon by sending a signal (as with
217 the example line above) is usually not a good choice, because this
218 is an asynchronous operation and hence not suitable to order
219 reloads of multiple services against each other. It is strongly
220 recommended to set ExecReload= to a command that not only triggers
221 a configuration reload of the daemon, but also synchronously waits
222 for it to complete.
223 ExecStop=
225 Commands to execute to stop the service started via ExecStart=.
226 This argument takes multiple command lines, following the same
227 scheme as described for ExecStart= above. Use of this setting is
228 optional. After the commands configured in this option are run, all
229 processes remaining for a service are terminated according to the
230 KillMode= setting (see systemd.kill(5)). If this option is not
231 specified, the process is terminated immediately when service stop
232 is requested. Specifier and environment variable substitution is
233 supported (including $MAINPID, see above).
234 ExecStopPost=
236 Additional commands that are executed after the service was
237 stopped. This includes cases where the commands configured in
238 ExecStop= were used, where the service does not have any ExecStop=
239 defined, or where the service exited unexpectedly. This argument
240 takes multiple command lines, following the same scheme as
241 described for ExecStart. Use of these settings is optional.
242 Specifier and environment variable substitution is supported.
243 RestartSec=
245 Configures the time to sleep before restarting a service (as
246 configured with Restart=). Takes a unit-less value in seconds, or a
247 time span value such as "5min 20s". Defaults to 100ms.
248 TimeoutStartSec=
250 Configures the time to wait for start-up. If a daemon service does
251 not signal start-up completion within the configured time, the
252 service will be considered failed and will be shut down again.
253 Takes a unit-less value in seconds, or a time span value such as
254 "5min 20s". Pass "0" to disable the timeout logic. Defaults to
255 DefaultTimeoutStartSec= from the manager configuration file, except
256 when Type=oneshot is used, in which case the timeout is disabled by
257 default (see systemd-system.conf(5)).
258 TimeoutStopSec=
260 This option serves two purposes. First, it configures the time to
261 wait for each ExecStop= command. If any of them times out,
262 subsequent ExecStop= commands are skipped and the service will be
263 terminated by SIGTERM. If no ExecStop= commands are specified, the
264 service gets the SIGTERM immediately. Second, it configures the
265 time to wait for the service itself to stop. If it doesn't
266 terminate in the specified time, it will be forcibly terminated by
267 SIGKILL (see KillMode= in systemd.kill(5)). Takes a unit-less value
268 in seconds, or a time span value such as "5min 20s". Pass "0" to
269 disable the timeout logic. Defaults to DefaultTimeoutStopSec= from
270 the manager configuration file (see systemd-system.conf(5)).
271 TimeoutSec=
273 A shorthand for configuring both TimeoutStartSec= and
274 TimeoutStopSec= to the specified value.
275 WatchdogSec=
277 Configures the watchdog timeout for a service. The watchdog is
278 activated when the start-up is completed. The service must call
279 sd_notify(3) regularly with "WATCHDOG=1" (i.e. the "keep-alive
280 ping"). If the time between two such calls is larger than the
281 configured time, then the service is placed in a failed state and
282 it will be terminated with SIGABRT. By setting Restart= to
283 on-failure or always, the service will be automatically restarted.
284 The time configured here will be passed to the executed service
285 process in the WATCHDOG_USEC= environment variable. This allows
286 daemons to automatically enable the keep-alive pinging logic if
287 watchdog support is enabled for the service. If this option is
288 used, NotifyAccess= (see below) should be set to open access to the
289 notification socket provided by systemd. If NotifyAccess= is not
290 set, it will be implicitly set to main. Defaults to 0, which
291 disables this feature.
292 Restart=
294 Configures whether the service shall be restarted when the service
295 process exits, is killed, or a timeout is reached. The service
296 process may be the main service process, but it may also be one of
297 the processes specified with ExecStartPre=, ExecStartPost=,
298 ExecStop=, ExecStopPost=, or ExecReload=. When the death of the
299 process is a result of systemd operation (e.g. service stop or
300 restart), the service will not be restarted. Timeouts include
301 missing the watchdog "keep-alive ping" deadline and a service
302 start, reload, and stop operation timeouts.
303 Takes one of no, on-success, on-failure, on-abnormal, on-watchdog,
305 on-abort, or always. If set to no (the default), the service will
306 not be restarted. If set to on-success, it will be restarted only
307 when the service process exits cleanly. In this context, a clean
308 exit means an exit code of 0, or one of the signals SIGHUP, SIGINT,
309 SIGTERM or SIGPIPE, and additionally, exit statuses and signals
310 specified in SuccessExitStatus=. If set to on-failure, the service
311 will be restarted when the process exits with a non-zero exit code,
312 is terminated by a signal (including on core dump, but excluding
313 the aforementiond four signals), when an operation (such as service
314 reload) times out, and when the configured watchdog timeout is
315 triggered. If set to on-abnormal, the service will be restarted
316 when the process is terminated by a signal (including on core dump,
317 excluding the aforementioned four signals), when an operation times
318 out, or when the watchdog timeout is triggered. If set to on-abort,
319 the service will be restarted only if the service process exits due
320 to an uncaught signal not specified as a clean exit status. If set
321 to on-watchdog, the service will be restarted only if the watchdog
322 timeout for the service expires. If set to always, the service will
323 be restarted regardless of whether it exited cleanly or not, got
324 terminated abnormally by a signal, or hit a timeout.
325 Table 1. Exit causes and the effect of the Restart= settings on
327 them
328 ┌──────────────┬────┬────────┬────────────┬────────────┬─────────────┬──────────┬─────────────┐
329 │Restart │ no │ always │ on-success │ on-failure │ on-abnormal │ on-abort │ on-watchdog │
330 │settings/Exit │ │ │ │ │ │ │ │
331 │causes │ │ │ │ │ │ │ │
332 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
333 │Clean exit │ │ X │ X │ │ │ │ │
334 │code or │ │ │ │ │ │ │ │
335 │signal │ │ │ │ │ │ │ │
336 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
337 │Unclean exit │ │ X │ │ X │ │ │ │
338 │code │ │ │ │ │ │ │ │
339 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
340 │Unclean │ │ X │ │ X │ X │ X │ │
341 │signal │ │ │ │ │ │ │ │
342 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
343 │Timeout │ │ X │ │ X │ X │ │ │
344 ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
345 │Watchdog │ │ X │ │ X │ X │ │ X │
346 └──────────────┴────┴────────┴────────────┴────────────┴─────────────┴──────────┴─────────────┘
347 As exceptions to the setting above the service will not be
348 restarted if the exit code or signal is specified in
349 RestartPreventExitStatus= (see below). Also, the services will
350 always be restarted if the exit code or signal is specified in
351 RestartForceExitStatus= (see below).
352 Setting this to on-failure is the recommended choice for
354 long-running services, in order to increase reliability by
355 attempting automatic recovery from errors. For services that shall
356 be able to terminate on their own choice (and avoid immediate
357 restarting), on-abnormal is an alternative choice.
358 SuccessExitStatus=
360 Takes a list of exit status definitions that when returned by the
361 main service process will be considered successful termination, in
362 addition to the normal successful exit code 0 and the signals
363 SIGHUP, SIGINT, SIGTERM, and SIGPIPE. Exit status definitions can
364 either be numeric exit codes or termination signal names, separated
365 by spaces. For example:
366 SuccessExitStatus=1 2 8
368 SIGKILL
369 ensures that exit codes 1, 2, 8 and the termination signal SIGKILL
371 are considered clean service terminations.
372 Note that if a process has a signal handler installed and exits by
374 calling _exit(2) in response to a signal, the information about the
375 signal is lost. Programs should instead perform cleanup and kill
376 themselves with the same signal instead. See Proper handling of
377 SIGINT/SIGQUIT — How to be a proper program[3].
378 This option may appear more than once, in which case the list of
380 successful exit statuses is merged. If the empty string is assigned
381 to this option, the list is reset, all prior assignments of this
382 option will have no effect.
383 RestartPreventExitStatus=
385 Takes a list of exit status definitions that when returned by the
386 main service process will prevent automatic service restarts,
387 regardless of the restart setting configured with Restart=. Exit
388 status definitions can either be numeric exit codes or termination
389 signal names, and are separated by spaces. Defaults to the empty
390 list, so that, by default, no exit status is excluded from the
391 configured restart logic. For example:
392 RestartPreventExitStatus=1 6
394 SIGABRT
395 ensures that exit codes 1 and 6 and the termination signal SIGABRT
397 will not result in automatic service restarting. This option may
398 appear more than once, in which case the list of restart-preventing
399 statuses is merged. If the empty string is assigned to this option,
400 the list is reset and all prior assignments of this option will
401 have no effect.
402 RestartForceExitStatus=
404 Takes a list of exit status definitions that when returned by the
405 main service process will force automatic service restarts,
406 regardless of the restart setting configured with Restart=. The
407 argument format is similar to RestartPreventExitStatus=.
408 PermissionsStartOnly=
410 Takes a boolean argument. If true, the permission-related execution
411 options, as configured with User= and similar options (see
412 systemd.exec(5) for more information), are only applied to the
413 process started with ExecStart=, and not to the various other
414 ExecStartPre=, ExecStartPost=, ExecReload=, ExecStop=, and
415 ExecStopPost= commands. If false, the setting is applied to all
416 configured commands the same way. Defaults to false.
417 RootDirectoryStartOnly=
419 Takes a boolean argument. If true, the root directory, as
420 configured with the RootDirectory= option (see systemd.exec(5) for
421 more information), is only applied to the process started with
422 ExecStart=, and not to the various other ExecStartPre=,
423 ExecStartPost=, ExecReload=, ExecStop=, and ExecStopPost= commands.
424 If false, the setting is applied to all configured commands the
425 same way. Defaults to false.
426 NonBlocking=
428 Set the O_NONBLOCK flag for all file descriptors passed via
429 socket-based activation. If true, all file descriptors >= 3 (i.e.
430 all except stdin, stdout, and stderr) will have the O_NONBLOCK flag
431 set and hence are in non-blocking mode. This option is only useful
432 in conjunction with a socket unit, as described in
433 systemd.socket(5). Defaults to false.
434 NotifyAccess=
436 Controls access to the service status notification socket, as
437 accessible via the sd_notify(3) call. Takes one of none (the
438 default), main or all. If none, no daemon status updates are
439 accepted from the service processes, all status update messages are
440 ignored. If main, only service updates sent from the main process
441 of the service are accepted. If all, all services updates from all
442 members of the service's control group are accepted. This option
443 should be set to open access to the notification socket when using
444 Type=notify or WatchdogSec= (see above). If those options are used
445 but NotifyAccess= is not configured, it will be implicitly set to
446 main.
447 Sockets=
449 Specifies the name of the socket units this service shall inherit
450 socket file descriptors from when the service is started. Normally
451 it should not be necessary to use this setting as all socket file
452 descriptors whose unit shares the same name as the service (subject
453 to the different unit name suffix of course) are passed to the
454 spawned process.
455 Note that the same socket file descriptors may be passed to
457 multiple processes simultaneously. Also note that a different
458 service may be activated on incoming socket traffic than the one
459 which is ultimately configured to inherit the socket file
460 descriptors. Or in other words: the Service= setting of .socket
461 units does not have to match the inverse of the Sockets= setting of
462 the .service it refers to.
463 This option may appear more than once, in which case the list of
465 socket units is merged. If the empty string is assigned to this
466 option, the list of sockets is reset, and all prior uses of this
467 setting will have no effect.
468 StartLimitInterval=, StartLimitBurst=
470 Configure service start rate limiting. By default, services which
471 are started more than 5 times within 10 seconds are not permitted
472 to start any more times until the 10 second interval ends. With
473 these two options, this rate limiting may be modified. Use
474 StartLimitInterval= to configure the checking interval (defaults to
475 DefaultStartLimitInterval= in manager configuration file, set to 0
476 to disable any kind of rate limiting). Use StartLimitBurst= to
477 configure how many starts per interval are allowed (defaults to
478 DefaultStartLimitBurst= in manager configuration file). These
479 configuration options are particularly useful in conjunction with
480 Restart=; however, they apply to all kinds of starts (including
481 manual), not just those triggered by the Restart= logic. Note that
482 units which are configured for Restart= and which reach the start
483 limit are not attempted to be restarted anymore; however, they may
484 still be restarted manually at a later point, from which point on,
485 the restart logic is again activated. Note that systemctl
486 reset-failed will cause the restart rate counter for a service to
487 be flushed, which is useful if the administrator wants to manually
488 start a service and the start limit interferes with that.
489 StartLimitAction=
491 Configure the action to take if the rate limit configured with
492 StartLimitInterval= and StartLimitBurst= is hit. Takes one of none,
493 reboot, reboot-force, reboot-immediate, poweroff, poweroff-force or
494 poweroff-immediate. If none is set, hitting the rate limit will
495 trigger no action besides that the start will not be permitted.
496 reboot causes a reboot following the normal shutdown procedure
497 (i.e. equivalent to systemctl reboot). reboot-force causes a
498 forced reboot which will terminate all processes forcibly but
499 should cause no dirty file systems on reboot (i.e. equivalent to
500 systemctl reboot -f) and reboot-immediate causes immediate
501 execution of the reboot(2) system call, which might result in data
502 loss. Similar, poweroff, poweroff-force, poweroff-immediate have
503 the effect of powering down the system with similar semantics.
504 Defaults to none.
505 FailureAction=
507 Configure the action to take when the service enters a failed
508 state. Takes the same values as StartLimitAction= and executes the
509 same actions. Defaults to none.
510 RebootArgument=
512 Configure the optional argument for the reboot(2) system call if
513 StartLimitAction= or FailureAction= is a reboot action. This works
514 just like the optional argument to systemctl reboot command.
515 FileDescriptorStoreMax=
517 Configure how many file descriptors may be stored in the service
518 manager for the service using sd_pid_notify_with_fds(3)'s
519 "FDSTORE=1" messages. This is useful for implementing service
520 restart schemes where the state is serialized to /run and the file
521 descriptors passed to the service manager, to allow restarts
522 without losing state. Defaults to 0, i.e. no file descriptors may
523 be stored in the service manager by default. All file descriptors
524 passed to the service manager from a specific service are passed
525 back to the service's main process on the next service restart. Any
526 file descriptors passed to the service manager are automatically
527 closed when POLLHUP or POLLERR is seen on them, or when the service
528 is fully stopped and no job queued or being executed for it.
529 Check systemd.exec(5) and systemd.kill(5) for more settings.
531
533 This section describes command line parsing and variable and specifier
534 substitions for ExecStart=, ExecStartPre=, ExecStartPost=, ExecReload=,
535 ExecStop=, and ExecStopPost= options.
536 Multiple command lines may be concatenated in a single directive by
538 separating them with semicolons (these semicolons must be passed as
539 separate words). Lone semicolons may be escaped as "\;".
540 Each command line is split on whitespace, with the first item being the
542 command to execute, and the subsequent items being the arguments.
543 Double quotes ("...") and single quotes ('...') may be used, in which
544 case everything until the next matching quote becomes part of the same
545 argument. C-style escapes are also supported, see table below. Quotes
546 themselves are removed after parsing and escape sequences substituted.
547 In addition, a trailing backslash ("\") may be used to merge lines.
548 This syntax is intended to be very similar to shell syntax, but only
550 the meta-characters and expansions described in the following
551 paragraphs are understood. Specifically, redirection using "<", "<<",
552 ">", and ">>", pipes using "|", running programs in the background
553 using "&", and other elements of shell syntax are not supported.
554 The command to execute must an absolute path name. It may contain
556 spaces, but control characters are not allowed.
557 The command line accepts "%" specifiers as described in
559 systemd.unit(5). Note that the first argument of the command line (i.e.
560 the program to execute) may not include specifiers.
561 Basic environment variable substitution is supported. Use "${FOO}" as
563 part of a word, or as a word of its own, on the command line, in which
564 case it will be replaced by the value of the environment variable
565 including all whitespace it contains, resulting in a single argument.
566 Use "$FOO" as a separate word on the command line, in which case it
567 will be replaced by the value of the environment variable split at
568 whitespace resulting in zero or more arguments. For this type of
569 expansion, quotes and respected when splitting into words, and
570 afterwards removed.
571 Example:
573 Environment="ONE=one" 'TWO=two two'
575 ExecStart=/bin/echo $ONE $TWO ${TWO}
576 This will execute /bin/echo with four arguments: "one", "two", "two",
578 and "two two".
579 Example:
581 Environment=ONE='one' "TWO='two two' too" THREE=
583 ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
584 ExecStart=/bin/echo $ONE $TWO $THREE
585 This results in echo being called twice, the first time with arguments
587 "'one'", "'two two' too", "", and the second time with arguments "one",
588 "two two", "too".
589 To pass a literal dollar sign, use "$$". Variables whose value is not
591 known at expansion time are treated as empty strings. Note that the
592 first argument (i.e. the program to execute) may not be a variable.
593 Variables to be used in this fashion may be defined through
595 Environment= and EnvironmentFile=. In addition, variables listed in the
596 section "Environment variables in spawned processes" in
597 systemd.exec(5), which are considered "static configuration", may be
598 used (this includes e.g. $USER, but not $TERM).
599 Note that shell command lines are not directly supported. If shell
601 command lines are to be used, they need to be passed explicitly to a
602 shell implementation of some kind. Example:
603 ExecStart=/bin/sh -c 'dmesg | tac'
605 Example:
607 ExecStart=/bin/echo one ; /bin/echo "two two"
609 This will execute /bin/echo two times, each time with one argument:
611 "one" and "two two", respectively. Because two commands are specified,
612 Type=oneshot must be used.
613 Example:
615 ExecStart=/bin/echo / >/dev/null & \; \
617 /bin/ls
618 This will execute /bin/echo with five arguments: "/", ">/dev/null",
620 "&", ";", and "/bin/ls".
621 Table 2. C escapes supported in command lines and environment variables
623 ┌────────┬─────────────────────────┐
624 │Literal │ Actual value │
625 ├────────┼─────────────────────────┤
626 │"\a" │ bell │
627 ├────────┼─────────────────────────┤
628 │"\b" │ backspace │
629 ├────────┼─────────────────────────┤
630 │"\f" │ form feed │
631 ├────────┼─────────────────────────┤
632 │"\n" │ newline │
633 ├────────┼─────────────────────────┤
634 │"\r" │ carriage return │
635 ├────────┼─────────────────────────┤
636 │"\t" │ tab │
637 ├────────┼─────────────────────────┤
638 │"\v" │ vertical tab │
639 ├────────┼─────────────────────────┤
640 │"\\" │ backslash │
641 ├────────┼─────────────────────────┤
642 │"\"" │ double quotation mark │
643 ├────────┼─────────────────────────┤
644 │"\'" │ single quotation mark │
645 ├────────┼─────────────────────────┤
646 │"\s" │ space │
647 ├────────┼─────────────────────────┤
648 │"\xxx" │ character number xx in │
649 │ │ hexadecimal encoding │
650 ├────────┼─────────────────────────┤
651 │"\nnn" │ character number nnn in │
652 │ │ octal encoding │
653 └────────┴─────────────────────────┘
654
656 Example 1. Simple service
657 The following unit file creates a service that will execute
659 /usr/sbin/foo-daemon. Since no Type= is specified, the default
660 Type=simple will be assumed. systemd will assume the unit to be started
661 immediately after the program has begun executing.
662 [Unit]
664 Description=Foo
665 [Service]
667 ExecStart=/usr/sbin/foo-daemon
668 [Install]
670 WantedBy=multi-user.target
671 Note that systemd assumes here that the process started by systemd will
673 continue running until the service terminates. If the program
674 daemonizes itself (i.e. forks), please use Type=forking instead.
675 Since no ExecStop= was specified, systemd will send SIGTERM to all
677 processes started from this service, and after a timeout also SIGKILL.
678 This behavior can be modified, see systemd.kill(5) for details.
679 Note that this unit type does not include any type of notification when
681 a service has completed initialization. For this, you should use other
682 unit types, such as Type=notify if the service understands systemd's
683 notification protocol, Type=forking if the service can background
684 itself or Type=dbus if the unit acquires a DBus name once
685 initialization is complete. See below.
686 Example 2. Oneshot service
688 Sometimes units should just execute an action without keeping active
690 processes, such as a filesystem check or a cleanup action on boot. For
691 this, Type=oneshot exists. Units of this type will wait until the
692 process specified terminates and then fall back to being inactive. The
693 following unit will perform a clenaup action:
694 [Unit]
696 Description=Cleanup old Foo data
697 [Service]
699 Type=oneshot
700 ExecStart=/usr/sbin/foo-cleanup
701 [Install]
703 WantedBy=multi-user.target
704 Note that systemd will consider the unit to be in the state 'starting'
706 until the program has terminated, so ordered dependencies will wait for
707 the program to finish before starting themselves. The unit will revert
708 to the 'inactive' state after the execution is done, never reaching the
709 'active' state. That means another request to start the unit will
710 perform the action again.
711 Type=oneshot are the only service units that may have more than one
713 ExecStart= specified. They will be executed in order until either they
714 are all successful or one of them fails.
715 Example 3. Stoppable oneshot service
717 Similarly to the oneshot services, there are sometimes units that need
719 to execute a program to set up something and then execute another to
720 shut it down, but no process remains active while they are considered
721 'started'. Network configuration can sometimes fall into this category.
722 Another use case is if a oneshot service shall not be executed a each
723 time when they are pulled in as a dependency, but only the first time.
724 For this, systemd knows the setting RemainAfterExit=yes, which causes
726 systemd to consider the unit to be active if the start action exited
727 successfully. This directive can be used with all types, but is most
728 useful with Type=oneshot and Type=simple. With Type=oneshot systemd
729 waits until the start action has completed before it considers the unit
730 to be active, so dependencies start only after the start action has
731 succeeded. With Type=simple dependencies will start immediately after
732 the start action has been dispatched. The following unit provides an
733 example for a simple static firewall.
734 [Unit]
736 Description=Simple firewall
737 [Service]
739 Type=oneshot
740 RemainAfterExit=yes
741 ExecStart=/usr/local/sbin/simple-firewall-start
742 ExecStop=/usr/local/sbin/simple-firewall-stop
743 [Install]
745 WantedBy=multi-user.target
746 Since the unit is considered to be running after the start action has
748 exited, invoking systemctl start on that unit again will cause no
749 action to be taken.
750 Example 4. Traditional forking services
752 Many traditional daemons/services background (i.e. fork, daemonize)
754 themselves when starting. Set Type=forking in the service's unit file
755 to support this mode of operation. systemd will consider the service to
756 be in the process of initialization while the original program is still
757 running. Once it exits successfully and at least a process remains (and
758 RemainAfterExit=no), the service is considered started.
759 Often a traditional daemon only consists of one process. Therefore, if
761 only one process is left after the original process terminates, systemd
762 will consider that process the main process of the service. In that
763 case, the $MAINPID variable will be available in ExecReload=,
764 ExecStop=, etc.
765 In case more than one process remains, systemd will be unable to
767 determine the main process, so it will not assume there is one. In that
768 case, $MAINPID will not expand to anything. However, if the process
769 decides to write a traditional PID file, systemd will be able to read
770 the main PID from there. Please set PIDFile= accordingly. Note that the
771 daemon should write that file before finishing with its initialization,
772 otherwise systemd might try to read the file before it exists.
773 The following example shows a simple daemon that forks and just starts
775 one process in the background:
776 [Unit]
778 Description=Some simple daemon
779 [Service]
781 Type=forking
782 ExecStart=/usr/sbin/my-simple-daemon -d
783 [Install]
785 WantedBy=multi-user.target
786 Please see systemd.kill(5) for details on how you can influence the way
788 systemd terminates the service.
789 Example 5. DBus services
791 For services that acquire a name on the DBus system bus, use Type=dbus
793 and set BusName= accordingly. The service should not fork (daemonize).
794 systemd will consider the service to be initialized once the name has
795 been acquired on the system bus. The following example shows a typical
796 DBus service:
797 [Unit]
799 Description=Simple DBus service
800 [Service]
802 Type=dbus
803 BusName=org.example.simple-dbus-service
804 ExecStart=/usr/sbin/simple-dbus-service
805 [Install]
807 WantedBy=multi-user.target
808 For bus-activatable services, don't include a "[Install]" section in
810 the systemd service file, but use the SystemdService= option in the
811 corresponding DBus service file, for example
812 (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service):
813 [D-BUS Service]
815 Name=org.example.simple-dbus-service
816 Exec=/usr/sbin/simple-dbus-service
817 User=root
818 SystemdService=simple-dbus-service.service
819 Please see systemd.kill(5) for details on how you can influence the way
821 systemd terminates the service.
822 Example 6. Services that notify systemd about their initialization
824 Type=simple services are really easy to write, but have the major
826 disadvantage of systemd not being able to tell when initialization of
827 the given service is complete. For this reason, systemd supports a
828 simple notification protocol that allows daemons to make systemd aware
829 that they are done initializing. Use Type=notify for this. A typical
830 service file for such a daemon would look like this:
831 [Unit]
833 Description=Simple notifying service
834 [Service]
836 Type=notify
837 ExecStart=/usr/sbin/simple-notifying-service
838 [Install]
840 WantedBy=multi-user.target
841 Note that the daemon has to support systemd's notification protocol,
843 else systemd will think the service hasn't started yet and kill it
844 after a timeout. For an example of how to update daemons to support
845 this protocol transparently, take a look at sd_notify(3). systemd will
846 consider the unit to be in the 'starting' state until a readiness
847 notification has arrived.
848 Please see systemd.kill(5) for details on how you can influence the way
850 systemd terminates the service.
851
853 systemd(1), systemctl(1), systemd.unit(5), systemd.exec(5),
854 systemd.resource-control(5), systemd.kill(5), systemd.directives(7)
855
857 1. Incompatibilities with SysV
858 http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities
859 2. kdbus
861 https://code.google.com/p/d-bus/
862 3. Proper handling of SIGINT/SIGQUIT — How to be a proper program
864 http://www.cons.org/cracauer/sigint.html
865systemd 219 SYSTEMD.SERVICE(5)