1SYSTEMD.SERVICE(5)              systemd.service             SYSTEMD.SERVICE(5)
2
3
4

NAME

6       systemd.service - Service unit configuration
7

SYNOPSIS

9       service.service
10

DESCRIPTION

12       A unit configuration file whose name ends in ".service" encodes
13       information about a process controlled and supervised by systemd.
14
15       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
21       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
27       If a service is requested under a certain name but no unit
28       configuration file is found, systemd looks for a SysV init script by
29       the same name (with the .service suffix removed) and dynamically
30       creates a service unit from that script. This is useful for
31       compatibility with SysV. Note that this compatibility is quite
32       comprehensive but not 100%. For details about the incompatibilities,
33       see the Incompatibilities with SysV[1] document.
34

SERVICE TEMPLATES

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

AUTOMATIC DEPENDENCIES

46   Implicit Dependencies
47       The following dependencies are implicitly added:
48
49       ·   Services with Type=dbus set automatically acquire dependencies of
50           type Requires= and After= on dbus.socket.
51
52       ·   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
57       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
61   Default Dependencies
62       The following dependencies are added unless DefaultDependencies=no is
63       set:
64
65       ·   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
73       ·   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

OPTIONS

85       Service files must include a "[Service]" section, which carries
86       information about the service and the process it supervises. A number
87       of options that may be used in this section are shared with other unit
88       types. These options are documented in systemd.exec(5), systemd.kill(5)
89       and systemd.resource-control(5). The options specific to the
90       "[Service]" section of service units are the following:
91
92       Type=
93           Configures the process start-up type for this service unit. One of
94           simple, exec, forking, oneshot, dbus, notify or idle:
95
96           ·   If set to simple (the default if ExecStart= is specified but
97               neither Type= nor BusName= are), the service manager will
98               consider the unit started immediately after the main service
99               process has been forked off. It is expected that the process
100               configured with ExecStart= is the main process of the service.
101               In this mode, if the process offers functionality to other
102               processes on the system, its communication channels should be
103               installed before the service is started up (e.g. sockets set up
104               by systemd, via socket activation), as the service manager will
105               immediately proceed starting follow-up units, right after
106               creating the main service process, and before executing the
107               service's binary. Note that this means systemctl start command
108               lines for simple services will report success even if the
109               service's binary cannot be invoked successfully (for example
110               because the selected User= doesn't exist, or the service binary
111               is missing).
112
113           ·   The exec type is similar to simple, but the service manager
114               will consider the unit started immediately after the main
115               service binary has been executed. The service manager will
116               delay starting of follow-up units until that point. (Or in
117               other words: simple proceeds with further jobs right after
118               fork() returns, while exec will not proceed before both fork()
119               and execve() in the service process succeeded.) Note that this
120               means systemctl start command lines for exec services will
121               report failure when the service's binary cannot be invoked
122               successfully (for example because the selected User= doesn't
123               exist, or the service binary is missing).
124
125           ·   If set to forking, it is expected that the process configured
126               with ExecStart= will call fork() as part of its start-up. The
127               parent process is expected to exit when start-up is complete
128               and all communication channels are set up. The child continues
129               to run as the main service process, and the service manager
130               will consider the unit started when the parent process exits.
131               This is the behavior of traditional UNIX services. If this
132               setting is used, it is recommended to also use the PIDFile=
133               option, so that systemd can reliably identify the main process
134               of the service. systemd will proceed with starting follow-up
135               units as soon as the parent process exits.
136
137           ·   Behavior of oneshot is similar to simple; however, the service
138               manager will consider the unit started after the main process
139               exits. It will then start follow-up units.  RemainAfterExit= is
140               particularly useful for this type of service.  Type=oneshot is
141               the implied default if neither Type= nor ExecStart= are
142               specified.
143
144           ·   Behavior of dbus is similar to simple; however, it is expected
145               that the service acquires a name on the D-Bus bus, as
146               configured by BusName=. systemd will proceed with starting
147               follow-up units after the D-Bus bus name has been acquired.
148               Service units with this option configured implicitly gain
149               dependencies on the dbus.socket unit. This type is the default
150               if BusName= is specified.
151
152           ·   Behavior of notify is similar to exec; however, it is expected
153               that the service sends a notification message via sd_notify(3)
154               or an equivalent call when it has finished starting up. systemd
155               will proceed with starting follow-up units after this
156               notification message has been sent. If this option is used,
157               NotifyAccess= (see below) should be set to open access to the
158               notification socket provided by systemd. If NotifyAccess= is
159               missing or set to none, it will be forcibly set to main. Note
160               that currently Type=notify will not work if used in combination
161               with PrivateNetwork=yes.
162
163           ·   Behavior of idle is very similar to simple; however, actual
164               execution of the service program is delayed until all active
165               jobs are dispatched. This may be used to avoid interleaving of
166               output of shell services with the status output on the console.
167               Note that this type is useful only to improve console output,
168               it is not useful as a general unit ordering tool, and the
169               effect of this service type is subject to a 5s timeout, after
170               which the service program is invoked anyway.
171
172           It is generally recommended to use Type=simple for long-running
173           services whenever possible, as it is the simplest and fastest
174           option. However, as this service type won't propagate service
175           start-up failures and doesn't allow ordering of other units against
176           completion of initialization of the service (which for example is
177           useful if clients need to connect to the service through some form
178           of IPC, and the IPC channel is only established by the service
179           itself — in contrast to doing this ahead of time through socket or
180           bus activation or similar), it might not be sufficient for many
181           cases. If so, notify or dbus (the latter only in case the service
182           provides a D-Bus interface) are the preferred options as they allow
183           service program code to precisely schedule when to consider the
184           service started up successfully and when to proceed with follow-up
185           units. The notify service type requires explicit support in the
186           service codebase (as sd_notify() or an equivalent API needs to be
187           invoked by the service at the appropriate time) — if it's not
188           supported, then forking is an alternative: it supports the
189           traditional UNIX service start-up protocol. Finally, exec might be
190           an option for cases where it is enough to ensure the service binary
191           is invoked, and where the service binary itself executes no or
192           little initialization on its own (and its initialization is
193           unlikely to fail). Note that using any type other than simple
194           possibly delays the boot process, as the service manager needs to
195           wait for service initialization to complete. It is hence
196           recommended not to needlessly use any types other than simple.
197           (Also note it is generally not recommended to use idle or oneshot
198           for long-running services.)
199
200       RemainAfterExit=
201           Takes a boolean value that specifies whether the service shall be
202           considered active even when all its processes exited. Defaults to
203           no.
204
205       GuessMainPID=
206           Takes a boolean value that specifies whether systemd should try to
207           guess the main PID of a service if it cannot be determined
208           reliably. This option is ignored unless Type=forking is set and
209           PIDFile= is unset because for the other types or with an explicitly
210           configured PID file, the main PID is always known. The guessing
211           algorithm might come to incorrect conclusions if a daemon consists
212           of more than one process. If the main PID cannot be determined,
213           failure detection and automatic restarting of a service will not
214           work reliably. Defaults to yes.
215
216       PIDFile=
217           Takes a path referring to the PID file of the service. Usage of
218           this option is recommended for services where Type= is set to
219           forking. The path specified typically points to a file below /run/.
220           If a relative path is specified it is hence prefixed with /run/.
221           The service manager will read the PID of the main process of the
222           service from this file after start-up of the service. The service
223           manager will not write to the file configured here, although it
224           will remove the file after the service has shut down if it still
225           exists. The PID file does not need to be owned by a privileged
226           user, but if it is owned by an unprivileged user additional safety
227           restrictions are enforced: the file may not be a symlink to a file
228           owned by a different user (neither directly nor indirectly), and
229           the PID file must refer to a process already belonging to the
230           service.
231
232       BusName=
233           Takes a D-Bus bus name that this service is reachable as. This
234           option is mandatory for services where Type= is set to dbus.
235
236       ExecStart=
237           Commands with their arguments that are executed when this service
238           is started. The value is split into zero or more command lines
239           according to the rules described below (see section "Command Lines"
240           below).
241
242           Unless Type= is oneshot, exactly one command must be given. When
243           Type=oneshot is used, zero or more commands may be specified.
244           Commands may be specified by providing multiple command lines in
245           the same directive, or alternatively, this directive may be
246           specified more than once with the same effect. If the empty string
247           is assigned to this option, the list of commands to start is reset,
248           prior assignments of this option will have no effect. If no
249           ExecStart= is specified, then the service must have
250           RemainAfterExit=yes and at least one ExecStop= line set. (Services
251           lacking both ExecStart= and ExecStop= are not valid.)
252
253           For each of the specified commands, the first argument must be
254           either an absolute path to an executable or a simple file name
255           without any slashes. Optionally, this filename may be prefixed with
256           a number of special characters:
257
258           Table 1. Special executable prefixes
259           ┌───────┬────────────────────────────┐
260Prefix Effect                     
261           ├───────┼────────────────────────────┤
262           │"@"    │ If the executable path is  │
263           │       │ prefixed with "@", the     │
264           │       │ second specified token     │
265           │       │ will be passed as          │
266           │       │ "argv[0]" to the executed  │
267           │       │ process (instead of the    │
268           │       │ actual filename), followed │
269           │       │ by the further arguments   │
270           │       │ specified.                 │
271           ├───────┼────────────────────────────┤
272           │"-"    │ If the executable path is  │
273           │       │ prefixed with "-", an exit │
274           │       │ code of the command        │
275           │       │ normally considered a      │
276           │       │ failure (i.e. non-zero     │
277           │       │ exit status or abnormal    │
278           │       │ exit due to signal) is     │
279           │       │ recorded, but has no       │
280           │       │ further effect and is      │
281           │       │ considered equivalent to   │
282           │       │ success.                   │
283           ├───────┼────────────────────────────┤
284           │"+"    │ If the executable path is  │
285           │       │ prefixed with "+" then the │
286           │       │ process is executed with   │
287           │       │ full privileges. In this   │
288           │       │ mode privilege             │
289           │       │ restrictions configured    │
290           │       │ with User=, Group=,        │
291           │       │ CapabilityBoundingSet= or  │
292           │       │ the various file system    │
293           │       │ namespacing options (such  │
294           │       │ as PrivateDevices=,        │
295           │       │ PrivateTmp=) are not       │
296           │       │ applied to the invoked     │
297           │       │ command line (but still    │
298           │       │ affect any other           │
299           │       │ ExecStart=, ExecStop=, ... │
300           │       │ lines).                    │
301           ├───────┼────────────────────────────┤
302           │"!"    │ Similar to the "+"         │
303           │       │ character discussed above  │
304           │       │ this permits invoking      │
305           │       │ command lines with         │
306           │       │ elevated privileges.       │
307           │       │ However, unlike "+" the    │
308           │       │ "!" character exclusively  │
309           │       │ alters the effect of       │
310           │       │ User=, Group= and          │
311           │       │ SupplementaryGroups=, i.e. │
312           │       │ only the stanzas that      │
313           │       │ affect user and group      │
314           │       │ credentials. Note that     │
315           │       │ this setting may be        │
316           │       │ combined with              │
317           │       │ DynamicUser=, in which     │
318           │       │ case a dynamic user/group  │
319           │       │ pair is allocated before   │
320           │       │ the command is invoked,    │
321           │       │ but credential changing is │
322           │       │ left to the executed       │
323           │       │ process itself.            │
324           ├───────┼────────────────────────────┤
325           │"!!"   │ This prefix is very        │
326           │       │ similar to "!", however it │
327           │       │ only has an effect on      │
328           │       │ systems lacking support    │
329           │       │ for ambient process        │
330           │       │ capabilities, i.e. without │
331           │       │ support for                │
332           │       │ AmbientCapabilities=. It's │
333           │       │ intended to be used for    │
334           │       │ unit files that take       │
335           │       │ benefit of ambient         │
336           │       │ capabilities to run        │
337           │       │ processes with minimal     │
338           │       │ privileges wherever        │
339           │       │ possible while remaining   │
340           │       │ compatible with systems    │
341           │       │ that lack ambient          │
342           │       │ capabilities support. Note │
343           │       │ that when "!!" is used,    │
344           │       │ and a system lacking       │
345           │       │ ambient capability support │
346           │       │ is detected any configured │
347           │       │ SystemCallFilter= and      │
348           │       │ CapabilityBoundingSet=
349           │       │ stanzas are implicitly     │
350           │       │ modified, in order to      │
351           │       │ permit spawned processes   │
352           │       │ to drop credentials and    │
353           │       │ capabilities themselves,   │
354           │       │ even if this is configured │
355           │       │ to not be allowed.         │
356           │       │ Moreover, if this prefix   │
357           │       │ is used and a system       │
358           │       │ lacking ambient capability │
359           │       │ support is detected        │
360           │       │ AmbientCapabilities= will  │
361           │       │ be skipped and not be      │
362           │       │ applied. On systems        │
363           │       │ supporting ambient         │
364           │       │ capabilities, "!!" has no  │
365           │       │ effect and is redundant.   │
366           └───────┴────────────────────────────┘
367           "@", "-", and one of "+"/"!"/"!!"  may be used together and they
368           can appear in any order. However, only one of "+", "!", "!!"  may
369           be used at a time. Note that these prefixes are also supported for
370           the other command line settings, i.e.  ExecStartPre=,
371           ExecStartPost=, ExecReload=, ExecStop= and ExecStopPost=.
372
373           If more than one command is specified, the commands are invoked
374           sequentially in the order they appear in the unit file. If one of
375           the commands fails (and is not prefixed with "-"), other lines are
376           not executed, and the unit is considered failed.
377
378           Unless Type=forking is set, the process started via this command
379           line will be considered the main process of the daemon.
380
381       ExecStartPre=, ExecStartPost=
382           Additional commands that are executed before or after the command
383           in ExecStart=, respectively. Syntax is the same as for ExecStart=,
384           except that multiple command lines are allowed and the commands are
385           executed one after the other, serially.
386
387           If any of those commands (not prefixed with "-") fail, the rest are
388           not executed and the unit is considered failed.
389
390           ExecStart= commands are only run after all ExecStartPre= commands
391           that were not prefixed with a "-" exit successfully.
392
393           ExecStartPost= commands are only run after the commands specified
394           in ExecStart= have been invoked successfully, as determined by
395           Type= (i.e. the process has been started for Type=simple or
396           Type=idle, the last ExecStart= process exited successfully for
397           Type=oneshot, the initial process exited successfully for
398           Type=forking, "READY=1" is sent for Type=notify, or the BusName=
399           has been taken for Type=dbus).
400
401           Note that ExecStartPre= may not be used to start long-running
402           processes. All processes forked off by processes invoked via
403           ExecStartPre= will be killed before the next service process is
404           run.
405
406           Note that if any of the commands specified in ExecStartPre=,
407           ExecStart=, or ExecStartPost= fail (and are not prefixed with "-",
408           see above) or time out before the service is fully up, execution
409           continues with commands specified in ExecStopPost=, the commands in
410           ExecStop= are skipped.
411
412       ExecReload=
413           Commands to execute to trigger a configuration reload in the
414           service. This argument takes multiple command lines, following the
415           same scheme as described for ExecStart= above. Use of this setting
416           is optional. Specifier and environment variable substitution is
417           supported here following the same scheme as for ExecStart=.
418
419           One additional, special environment variable is set: if known,
420           $MAINPID is set to the main process of the daemon, and may be used
421           for command lines like the following:
422
423               /bin/kill -HUP $MAINPID
424
425           Note however that reloading a daemon by sending a signal (as with
426           the example line above) is usually not a good choice, because this
427           is an asynchronous operation and hence not suitable to order
428           reloads of multiple services against each other. It is strongly
429           recommended to set ExecReload= to a command that not only triggers
430           a configuration reload of the daemon, but also synchronously waits
431           for it to complete.
432
433       ExecStop=
434           Commands to execute to stop the service started via ExecStart=.
435           This argument takes multiple command lines, following the same
436           scheme as described for ExecStart= above. Use of this setting is
437           optional. After the commands configured in this option are run, it
438           is implied that the service is stopped, and any processes remaining
439           for it are terminated according to the KillMode= setting (see
440           systemd.kill(5)). If this option is not specified, the process is
441           terminated by sending the signal specified in KillSignal= when
442           service stop is requested. Specifier and environment variable
443           substitution is supported (including $MAINPID, see above).
444
445           Note that it is usually not sufficient to specify a command for
446           this setting that only asks the service to terminate (for example,
447           by queuing some form of termination signal for it), but does not
448           wait for it to do so. Since the remaining processes of the services
449           are killed according to KillMode= and KillSignal= as described
450           above immediately after the command exited, this may not result in
451           a clean stop. The specified command should hence be a synchronous
452           operation, not an asynchronous one.
453
454           Note that the commands specified in ExecStop= are only executed
455           when the service started successfully first. They are not invoked
456           if the service was never started at all, or in case its start-up
457           failed, for example because any of the commands specified in
458           ExecStart=, ExecStartPre= or ExecStartPost= failed (and weren't
459           prefixed with "-", see above) or timed out. Use ExecStopPost= to
460           invoke commands when a service failed to start up correctly and is
461           shut down again. Also note that the stop operation is always
462           performed if the service started successfully, even if the
463           processes in the service terminated on their own or were killed.
464           The stop commands must be prepared to deal with that case.
465           $MAINPID will be unset if systemd knows that the main process
466           exited by the time the stop commands are called.
467
468           Service restart requests are implemented as stop operations
469           followed by start operations. This means that ExecStop= and
470           ExecStopPost= are executed during a service restart operation.
471
472           It is recommended to use this setting for commands that communicate
473           with the service requesting clean termination. For post-mortem
474           clean-up steps use ExecStopPost= instead.
475
476       ExecStopPost=
477           Additional commands that are executed after the service is stopped.
478           This includes cases where the commands configured in ExecStop= were
479           used, where the service does not have any ExecStop= defined, or
480           where the service exited unexpectedly. This argument takes multiple
481           command lines, following the same scheme as described for
482           ExecStart=. Use of these settings is optional. Specifier and
483           environment variable substitution is supported. Note that – unlike
484           ExecStop= – commands specified with this setting are invoked when a
485           service failed to start up correctly and is shut down again.
486
487           It is recommended to use this setting for clean-up operations that
488           shall be executed even when the service failed to start up
489           correctly. Commands configured with this setting need to be able to
490           operate even if the service failed starting up half-way and left
491           incompletely initialized data around. As the service's processes
492           have been terminated already when the commands specified with this
493           setting are executed they should not attempt to communicate with
494           them.
495
496           Note that all commands that are configured with this setting are
497           invoked with the result code of the service, as well as the main
498           process' exit code and status, set in the $SERVICE_RESULT,
499           $EXIT_CODE and $EXIT_STATUS environment variables, see
500           systemd.exec(5) for details.
501
502       RestartSec=
503           Configures the time to sleep before restarting a service (as
504           configured with Restart=). Takes a unit-less value in seconds, or a
505           time span value such as "5min 20s". Defaults to 100ms.
506
507       TimeoutStartSec=
508           Configures the time to wait for start-up. If a daemon service does
509           not signal start-up completion within the configured time, the
510           service will be considered failed and will be shut down again.
511           Takes a unit-less value in seconds, or a time span value such as
512           "5min 20s". Pass "infinity" to disable the timeout logic. Defaults
513           to DefaultTimeoutStartSec= from the manager configuration file,
514           except when Type=oneshot is used, in which case the timeout is
515           disabled by default (see systemd-system.conf(5)).
516
517           If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this
518           may cause the start time to be extended beyond TimeoutStartSec=.
519           The first receipt of this message must occur before
520           TimeoutStartSec= is exceeded, and once the start time has exended
521           beyond TimeoutStartSec=, the service manager will allow the service
522           to continue to start, provided the service repeats
523           "EXTEND_TIMEOUT_USEC=..."  within the interval specified until the
524           service startup status is finished by "READY=1". (see
525           sd_notify(3)).
526
527       TimeoutStopSec=
528           This option serves two purposes. First, it configures the time to
529           wait for each ExecStop= command. If any of them times out,
530           subsequent ExecStop= commands are skipped and the service will be
531           terminated by SIGTERM. If no ExecStop= commands are specified, the
532           service gets the SIGTERM immediately. Second, it configures the
533           time to wait for the service itself to stop. If it doesn't
534           terminate in the specified time, it will be forcibly terminated by
535           SIGKILL (see KillMode= in systemd.kill(5)). Takes a unit-less value
536           in seconds, or a time span value such as "5min 20s". Pass
537           "infinity" to disable the timeout logic. Defaults to
538           DefaultTimeoutStopSec= from the manager configuration file (see
539           systemd-system.conf(5)).
540
541           If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this
542           may cause the stop time to be extended beyond TimeoutStopSec=. The
543           first receipt of this message must occur before TimeoutStopSec= is
544           exceeded, and once the stop time has exended beyond
545           TimeoutStopSec=, the service manager will allow the service to
546           continue to stop, provided the service repeats
547           "EXTEND_TIMEOUT_USEC=..."  within the interval specified, or
548           terminates itself (see sd_notify(3)).
549
550       TimeoutSec=
551           A shorthand for configuring both TimeoutStartSec= and
552           TimeoutStopSec= to the specified value.
553
554       RuntimeMaxSec=
555           Configures a maximum time for the service to run. If this is used
556           and the service has been active for longer than the specified time
557           it is terminated and put into a failure state. Note that this
558           setting does not have any effect on Type=oneshot services, as they
559           terminate immediately after activation completed. Pass "infinity"
560           (the default) to configure no runtime limit.
561
562           If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this
563           may cause the runtime to be extended beyond RuntimeMaxSec=. The
564           first receipt of this message must occur before RuntimeMaxSec= is
565           exceeded, and once the runtime has exended beyond RuntimeMaxSec=,
566           the service manager will allow the service to continue to run,
567           provided the service repeats "EXTEND_TIMEOUT_USEC=..."  within the
568           interval specified until the service shutdown is achieved by
569           "STOPPING=1" (or termination). (see sd_notify(3)).
570
571       WatchdogSec=
572           Configures the watchdog timeout for a service. The watchdog is
573           activated when the start-up is completed. The service must call
574           sd_notify(3) regularly with "WATCHDOG=1" (i.e. the "keep-alive
575           ping"). If the time between two such calls is larger than the
576           configured time, then the service is placed in a failed state and
577           it will be terminated with SIGABRT (or the signal specified by
578           WatchdogSignal=). By setting Restart= to on-failure, on-watchdog,
579           on-abnormal or always, the service will be automatically restarted.
580           The time configured here will be passed to the executed service
581           process in the WATCHDOG_USEC= environment variable. This allows
582           daemons to automatically enable the keep-alive pinging logic if
583           watchdog support is enabled for the service. If this option is
584           used, NotifyAccess= (see below) should be set to open access to the
585           notification socket provided by systemd. If NotifyAccess= is not
586           set, it will be implicitly set to main. Defaults to 0, which
587           disables this feature. The service can check whether the service
588           manager expects watchdog keep-alive notifications. See
589           sd_watchdog_enabled(3) for details.  sd_event_set_watchdog(3) may
590           be used to enable automatic watchdog notification support.
591
592       Restart=
593           Configures whether the service shall be restarted when the service
594           process exits, is killed, or a timeout is reached. The service
595           process may be the main service process, but it may also be one of
596           the processes specified with ExecStartPre=, ExecStartPost=,
597           ExecStop=, ExecStopPost=, or ExecReload=. When the death of the
598           process is a result of systemd operation (e.g. service stop or
599           restart), the service will not be restarted. Timeouts include
600           missing the watchdog "keep-alive ping" deadline and a service
601           start, reload, and stop operation timeouts.
602
603           Takes one of no, on-success, on-failure, on-abnormal, on-watchdog,
604           on-abort, or always. If set to no (the default), the service will
605           not be restarted. If set to on-success, it will be restarted only
606           when the service process exits cleanly. In this context, a clean
607           exit means an exit code of 0, or one of the signals SIGHUP, SIGINT,
608           SIGTERM or SIGPIPE, and additionally, exit statuses and signals
609           specified in SuccessExitStatus=. If set to on-failure, the service
610           will be restarted when the process exits with a non-zero exit code,
611           is terminated by a signal (including on core dump, but excluding
612           the aforementioned four signals), when an operation (such as
613           service reload) times out, and when the configured watchdog timeout
614           is triggered. If set to on-abnormal, the service will be restarted
615           when the process is terminated by a signal (including on core dump,
616           excluding the aforementioned four signals), when an operation times
617           out, or when the watchdog timeout is triggered. If set to on-abort,
618           the service will be restarted only if the service process exits due
619           to an uncaught signal not specified as a clean exit status. If set
620           to on-watchdog, the service will be restarted only if the watchdog
621           timeout for the service expires. If set to always, the service will
622           be restarted regardless of whether it exited cleanly or not, got
623           terminated abnormally by a signal, or hit a timeout.
624
625           Table 2. Exit causes and the effect of the Restart= settings on
626           them
627           ┌──────────────┬────┬────────┬────────────┬────────────┬─────────────┬──────────┬─────────────┐
628Restart       no always on-success on-failure on-abnormal on-abort on-watchdog 
629settings/Exit │    │        │            │            │             │          │             │
630causes        │    │        │            │            │             │          │             │
631           ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
632           │Clean exit    │    │ X      │ X          │            │             │          │             │
633           │code or       │    │        │            │            │             │          │             │
634           │signal        │    │        │            │            │             │          │             │
635           ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
636           │Unclean exit  │    │ X      │            │ X          │             │          │             │
637           │code          │    │        │            │            │             │          │             │
638           ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
639           │Unclean       │    │ X      │            │ X          │ X           │ X        │             │
640           │signal        │    │        │            │            │             │          │             │
641           ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
642           │Timeout       │    │ X      │            │ X          │ X           │          │             │
643           ├──────────────┼────┼────────┼────────────┼────────────┼─────────────┼──────────┼─────────────┤
644           │Watchdog      │    │ X      │            │ X          │ X           │          │ X           │
645           └──────────────┴────┴────────┴────────────┴────────────┴─────────────┴──────────┴─────────────┘
646           As exceptions to the setting above, the service will not be
647           restarted if the exit code or signal is specified in
648           RestartPreventExitStatus= (see below) or the service is stopped
649           with systemctl stop or an equivalent operation. Also, the services
650           will always be restarted if the exit code or signal is specified in
651           RestartForceExitStatus= (see below).
652
653           Note that service restart is subject to unit start rate limiting
654           configured with StartLimitIntervalSec= and StartLimitBurst=, see
655           systemd.unit(5) for details. A restarted service enters the failed
656           state only after the start limits are reached.
657
658           Setting this to on-failure is the recommended choice for
659           long-running services, in order to increase reliability by
660           attempting automatic recovery from errors. For services that shall
661           be able to terminate on their own choice (and avoid immediate
662           restarting), on-abnormal is an alternative choice.
663
664       SuccessExitStatus=
665           Takes a list of exit status definitions that, when returned by the
666           main service process, will be considered successful termination, in
667           addition to the normal successful exit code 0 and the signals
668           SIGHUP, SIGINT, SIGTERM, and SIGPIPE. Exit status definitions can
669           either be numeric exit codes or termination signal names, separated
670           by spaces. For example:
671
672               SuccessExitStatus=1 2 8 SIGKILL
673
674           ensures that exit codes 1, 2, 8 and the termination signal SIGKILL
675           are considered clean service terminations.
676
677           This option may appear more than once, in which case the list of
678           successful exit statuses is merged. If the empty string is assigned
679           to this option, the list is reset, all prior assignments of this
680           option will have no effect.
681
682       RestartPreventExitStatus=
683           Takes a list of exit status definitions that, when returned by the
684           main service process, will prevent automatic service restarts,
685           regardless of the restart setting configured with Restart=. Exit
686           status definitions can either be numeric exit codes or termination
687           signal names, and are separated by spaces. Defaults to the empty
688           list, so that, by default, no exit status is excluded from the
689           configured restart logic. For example:
690
691               RestartPreventExitStatus=1 6 SIGABRT
692
693           ensures that exit codes 1 and 6 and the termination signal SIGABRT
694           will not result in automatic service restarting. This option may
695           appear more than once, in which case the list of restart-preventing
696           statuses is merged. If the empty string is assigned to this option,
697           the list is reset and all prior assignments of this option will
698           have no effect.
699
700           Note that this setting has no effect on processes configured via
701           ExecStartPre=, ExecStartPost=, ExecStop=, ExecStopPost= or
702           ExecReload=, but only on the main service process, i.e. either the
703           one invoked by ExecStart= or (depending on Type=, PIDFile=, ...)
704           the otherwise configured main process.
705
706       RestartForceExitStatus=
707           Takes a list of exit status definitions that, when returned by the
708           main service process, will force automatic service restarts,
709           regardless of the restart setting configured with Restart=. The
710           argument format is similar to RestartPreventExitStatus=.
711
712       RootDirectoryStartOnly=
713           Takes a boolean argument. If true, the root directory, as
714           configured with the RootDirectory= option (see systemd.exec(5) for
715           more information), is only applied to the process started with
716           ExecStart=, and not to the various other ExecStartPre=,
717           ExecStartPost=, ExecReload=, ExecStop=, and ExecStopPost= commands.
718           If false, the setting is applied to all configured commands the
719           same way. Defaults to false.
720
721       NonBlocking=
722           Set the O_NONBLOCK flag for all file descriptors passed via
723           socket-based activation. If true, all file descriptors >= 3 (i.e.
724           all except stdin, stdout, stderr), excluding those passed in via
725           the file descriptor storage logic (see FileDescriptorStoreMax= for
726           details), will have the O_NONBLOCK flag set and hence are in
727           non-blocking mode. This option is only useful in conjunction with a
728           socket unit, as described in systemd.socket(5) and has no effect on
729           file descriptors which were previously saved in the file-descriptor
730           store for example. Defaults to false.
731
732       NotifyAccess=
733           Controls access to the service status notification socket, as
734           accessible via the sd_notify(3) call. Takes one of none (the
735           default), main, exec or all. If none, no daemon status updates are
736           accepted from the service processes, all status update messages are
737           ignored. If main, only service updates sent from the main process
738           of the service are accepted. If exec, only service updates sent
739           from any of the main or control processes originating from one of
740           the Exec*= commands are accepted. If all, all services updates from
741           all members of the service's control group are accepted. This
742           option should be set to open access to the notification socket when
743           using Type=notify or WatchdogSec= (see above). If those options are
744           used but NotifyAccess= is not configured, it will be implicitly set
745           to main.
746
747           Note that sd_notify() notifications may be attributed to units
748           correctly only if either the sending process is still around at the
749           time PID 1 processes the message, or if the sending process is
750           explicitly runtime-tracked by the service manager. The latter is
751           the case if the service manager originally forked off the process,
752           i.e. on all processes that match main or exec. Conversely, if an
753           auxiliary process of the unit sends an sd_notify() message and
754           immediately exits, the service manager might not be able to
755           properly attribute the message to the unit, and thus will ignore
756           it, even if NotifyAccess=all is set for it.
757
758       Sockets=
759           Specifies the name of the socket units this service shall inherit
760           socket file descriptors from when the service is started. Normally,
761           it should not be necessary to use this setting, as all socket file
762           descriptors whose unit shares the same name as the service (subject
763           to the different unit name suffix of course) are passed to the
764           spawned process.
765
766           Note that the same socket file descriptors may be passed to
767           multiple processes simultaneously. Also note that a different
768           service may be activated on incoming socket traffic than the one
769           which is ultimately configured to inherit the socket file
770           descriptors. Or, in other words: the Service= setting of .socket
771           units does not have to match the inverse of the Sockets= setting of
772           the .service it refers to.
773
774           This option may appear more than once, in which case the list of
775           socket units is merged. If the empty string is assigned to this
776           option, the list of sockets is reset, and all prior uses of this
777           setting will have no effect.
778
779       FileDescriptorStoreMax=
780           Configure how many file descriptors may be stored in the service
781           manager for the service using sd_pid_notify_with_fds(3)'s
782           "FDSTORE=1" messages. This is useful for implementing services that
783           can restart after an explicit request or a crash without losing
784           state. Any open sockets and other file descriptors which should not
785           be closed during the restart may be stored this way. Application
786           state can either be serialized to a file in /run, or better, stored
787           in a memfd_create(2) memory file descriptor. Defaults to 0, i.e. no
788           file descriptors may be stored in the service manager. All file
789           descriptors passed to the service manager from a specific service
790           are passed back to the service's main process on the next service
791           restart. Any file descriptors passed to the service manager are
792           automatically closed when POLLHUP or POLLERR is seen on them, or
793           when the service is fully stopped and no job is queued or being
794           executed for it. If this option is used, NotifyAccess= (see above)
795           should be set to open access to the notification socket provided by
796           systemd. If NotifyAccess= is not set, it will be implicitly set to
797           main.
798
799       USBFunctionDescriptors=
800           Configure the location of a file containing USB FunctionFS[2]
801           descriptors, for implementation of USB gadget functions. This is
802           used only in conjunction with a socket unit with ListenUSBFunction=
803           configured. The contents of this file are written to the ep0 file
804           after it is opened.
805
806       USBFunctionStrings=
807           Configure the location of a file containing USB FunctionFS strings.
808           Behavior is similar to USBFunctionDescriptors= above.
809
810       Check systemd.exec(5) and systemd.kill(5) for more settings.
811

COMMAND LINES

813       This section describes command line parsing and variable and specifier
814       substitutions for ExecStart=, ExecStartPre=, ExecStartPost=,
815       ExecReload=, ExecStop=, and ExecStopPost= options.
816
817       Multiple command lines may be concatenated in a single directive by
818       separating them with semicolons (these semicolons must be passed as
819       separate words). Lone semicolons may be escaped as "\;".
820
821       Each command line is split on whitespace, with the first item being the
822       command to execute, and the subsequent items being the arguments.
823       Double quotes ("...") and single quotes ('...') may be used to wrap a
824       whole item (the opening quote may appear only at the beginning or after
825       whitespace that is not quoted, and the closing quote must be followed
826       by whitespace or the end of line), in which case everything until the
827       next matching quote becomes part of the same argument. Quotes
828       themselves are removed. C-style escapes are also supported. The table
829       below contains the list of known escape patterns. Only escape patterns
830       which match the syntax in the table are allowed; other patterns may be
831       added in the future and unknown patterns will result in a warning. In
832       particular, any backslashes should be doubled. Finally, a trailing
833       backslash ("\") may be used to merge lines.
834
835       This syntax is inspired by shell syntax, but only the meta-characters
836       and expansions described in the following paragraphs are understood,
837       and the expansion of variables is different. Specifically, redirection
838       using "<", "<<", ">", and ">>", pipes using "|", running programs in
839       the background using "&", and other elements of shell syntax are not
840       supported.
841
842       The command to execute may contain spaces, but control characters are
843       not allowed.
844
845       The command line accepts "%" specifiers as described in
846       systemd.unit(5).
847
848       Basic environment variable substitution is supported. Use "${FOO}" as
849       part of a word, or as a word of its own, on the command line, in which
850       case it will be replaced by the value of the environment variable
851       including all whitespace it contains, resulting in a single argument.
852       Use "$FOO" as a separate word on the command line, in which case it
853       will be replaced by the value of the environment variable split at
854       whitespace, resulting in zero or more arguments. For this type of
855       expansion, quotes are respected when splitting into words, and
856       afterwards removed.
857
858       If the command is not a full (absolute) path, it will be resolved to a
859       full path using a fixed search path determinted at compilation time.
860       Searched directories include /usr/local/bin/, /usr/bin/, /bin/ on
861       systems using split /usr/bin/ and /bin/ directories, and their sbin/
862       counterparts on systems using split bin/ and sbin/. It is thus safe to
863       use just the executable name in case of executables located in any of
864       the "standard" directories, and an absolute path must be used in other
865       cases. Using an absolute path is recommended to avoid ambiguity. Hint:
866       this search path may be queried using systemd-path
867       search-binaries-default.
868
869       Example:
870
871           Environment="ONE=one" 'TWO=two two'
872           ExecStart=echo $ONE $TWO ${TWO}
873
874       This will execute /bin/echo with four arguments: "one", "two", "two",
875       and "two two".
876
877       Example:
878
879           Environment=ONE='one' "TWO='two two' too" THREE=
880           ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
881           ExecStart=/bin/echo $ONE $TWO $THREE
882
883       This results in /bin/echo being called twice, the first time with
884       arguments "'one'", "'two two' too", "", and the second time with
885       arguments "one", "two two", "too".
886
887       To pass a literal dollar sign, use "$$". Variables whose value is not
888       known at expansion time are treated as empty strings. Note that the
889       first argument (i.e. the program to execute) may not be a variable.
890
891       Variables to be used in this fashion may be defined through
892       Environment= and EnvironmentFile=. In addition, variables listed in the
893       section "Environment variables in spawned processes" in
894       systemd.exec(5), which are considered "static configuration", may be
895       used (this includes e.g.  $USER, but not $TERM).
896
897       Note that shell command lines are not directly supported. If shell
898       command lines are to be used, they need to be passed explicitly to a
899       shell implementation of some kind. Example:
900
901           ExecStart=sh -c 'dmesg | tac'
902
903       Example:
904
905           ExecStart=echo one ; echo "two two"
906
907       This will execute echo two times, each time with one argument: "one"
908       and "two two", respectively. Because two commands are specified,
909       Type=oneshot must be used.
910
911       Example:
912
913           ExecStart=echo / >/dev/null & \; \
914           ls
915
916       This will execute echo with five arguments: "/", ">/dev/null", "&",
917       ";", and "ls".
918
919       Table 3. C escapes supported in command lines and environment variables
920       ┌────────┬─────────────────────────┐
921Literal Actual value            
922       ├────────┼─────────────────────────┤
923       │"\a"    │ bell                    │
924       ├────────┼─────────────────────────┤
925       │"\b"    │ backspace               │
926       ├────────┼─────────────────────────┤
927       │"\f"    │ form feed               │
928       ├────────┼─────────────────────────┤
929       │"\n"    │ newline                 │
930       ├────────┼─────────────────────────┤
931       │"\r"    │ carriage return         │
932       ├────────┼─────────────────────────┤
933       │"\t"    │ tab                     │
934       ├────────┼─────────────────────────┤
935       │"\v"    │ vertical tab            │
936       ├────────┼─────────────────────────┤
937       │"\\"    │ backslash               │
938       ├────────┼─────────────────────────┤
939       │"\""    │ double quotation mark   │
940       ├────────┼─────────────────────────┤
941       │"\'"    │ single quotation mark   │
942       ├────────┼─────────────────────────┤
943       │"\s"    │ space                   │
944       ├────────┼─────────────────────────┤
945       │"\xxx"  │ character number xx in  │
946       │        │ hexadecimal encoding    │
947       ├────────┼─────────────────────────┤
948       │"\nnn"  │ character number nnn in │
949       │        │ octal encoding          │
950       └────────┴─────────────────────────┘
951

EXAMPLES

953       Example 1. Simple service
954
955       The following unit file creates a service that will execute
956       /usr/sbin/foo-daemon. Since no Type= is specified, the default
957       Type=simple will be assumed. systemd will assume the unit to be started
958       immediately after the program has begun executing.
959
960           [Unit]
961           Description=Foo
962
963           [Service]
964           ExecStart=/usr/sbin/foo-daemon
965
966           [Install]
967           WantedBy=multi-user.target
968
969       Note that systemd assumes here that the process started by systemd will
970       continue running until the service terminates. If the program
971       daemonizes itself (i.e. forks), please use Type=forking instead.
972
973       Since no ExecStop= was specified, systemd will send SIGTERM to all
974       processes started from this service, and after a timeout also SIGKILL.
975       This behavior can be modified, see systemd.kill(5) for details.
976
977       Note that this unit type does not include any type of notification when
978       a service has completed initialization. For this, you should use other
979       unit types, such as Type=notify if the service understands systemd's
980       notification protocol, Type=forking if the service can background
981       itself or Type=dbus if the unit acquires a DBus name once
982       initialization is complete. See below.
983
984       Example 2. Oneshot service
985
986       Sometimes, units should just execute an action without keeping active
987       processes, such as a filesystem check or a cleanup action on boot. For
988       this, Type=oneshot exists. Units of this type will wait until the
989       process specified terminates and then fall back to being inactive. The
990       following unit will perform a cleanup action:
991
992           [Unit]
993           Description=Cleanup old Foo data
994
995           [Service]
996           Type=oneshot
997           ExecStart=/usr/sbin/foo-cleanup
998
999           [Install]
1000           WantedBy=multi-user.target
1001
1002       Note that systemd will consider the unit to be in the state "starting"
1003       until the program has terminated, so ordered dependencies will wait for
1004       the program to finish before starting themselves. The unit will revert
1005       to the "inactive" state after the execution is done, never reaching the
1006       "active" state. That means another request to start the unit will
1007       perform the action again.
1008
1009       Type=oneshot are the only service units that may have more than one
1010       ExecStart= specified. They will be executed in order until either they
1011       are all successful or one of them fails.
1012
1013       Example 3. Stoppable oneshot service
1014
1015       Similarly to the oneshot services, there are sometimes units that need
1016       to execute a program to set up something and then execute another to
1017       shut it down, but no process remains active while they are considered
1018       "started". Network configuration can sometimes fall into this category.
1019       Another use case is if a oneshot service shall not be executed each
1020       time when they are pulled in as a dependency, but only the first time.
1021
1022       For this, systemd knows the setting RemainAfterExit=yes, which causes
1023       systemd to consider the unit to be active if the start action exited
1024       successfully. This directive can be used with all types, but is most
1025       useful with Type=oneshot and Type=simple. With Type=oneshot, systemd
1026       waits until the start action has completed before it considers the unit
1027       to be active, so dependencies start only after the start action has
1028       succeeded. With Type=simple, dependencies will start immediately after
1029       the start action has been dispatched. The following unit provides an
1030       example for a simple static firewall.
1031
1032           [Unit]
1033           Description=Simple firewall
1034
1035           [Service]
1036           Type=oneshot
1037           RemainAfterExit=yes
1038           ExecStart=/usr/local/sbin/simple-firewall-start
1039           ExecStop=/usr/local/sbin/simple-firewall-stop
1040
1041           [Install]
1042           WantedBy=multi-user.target
1043
1044       Since the unit is considered to be running after the start action has
1045       exited, invoking systemctl start on that unit again will cause no
1046       action to be taken.
1047
1048       Example 4. Traditional forking services
1049
1050       Many traditional daemons/services background (i.e. fork, daemonize)
1051       themselves when starting. Set Type=forking in the service's unit file
1052       to support this mode of operation. systemd will consider the service to
1053       be in the process of initialization while the original program is still
1054       running. Once it exits successfully and at least a process remains (and
1055       RemainAfterExit=no), the service is considered started.
1056
1057       Often, a traditional daemon only consists of one process. Therefore, if
1058       only one process is left after the original process terminates, systemd
1059       will consider that process the main process of the service. In that
1060       case, the $MAINPID variable will be available in ExecReload=,
1061       ExecStop=, etc.
1062
1063       In case more than one process remains, systemd will be unable to
1064       determine the main process, so it will not assume there is one. In that
1065       case, $MAINPID will not expand to anything. However, if the process
1066       decides to write a traditional PID file, systemd will be able to read
1067       the main PID from there. Please set PIDFile= accordingly. Note that the
1068       daemon should write that file before finishing with its initialization.
1069       Otherwise, systemd might try to read the file before it exists.
1070
1071       The following example shows a simple daemon that forks and just starts
1072       one process in the background:
1073
1074           [Unit]
1075           Description=Some simple daemon
1076
1077           [Service]
1078           Type=forking
1079           ExecStart=/usr/sbin/my-simple-daemon -d
1080
1081           [Install]
1082           WantedBy=multi-user.target
1083
1084       Please see systemd.kill(5) for details on how you can influence the way
1085       systemd terminates the service.
1086
1087       Example 5. DBus services
1088
1089       For services that acquire a name on the DBus system bus, use Type=dbus
1090       and set BusName= accordingly. The service should not fork (daemonize).
1091       systemd will consider the service to be initialized once the name has
1092       been acquired on the system bus. The following example shows a typical
1093       DBus service:
1094
1095           [Unit]
1096           Description=Simple DBus service
1097
1098           [Service]
1099           Type=dbus
1100           BusName=org.example.simple-dbus-service
1101           ExecStart=/usr/sbin/simple-dbus-service
1102
1103           [Install]
1104           WantedBy=multi-user.target
1105
1106       For bus-activatable services, do not include a "[Install]" section in
1107       the systemd service file, but use the SystemdService= option in the
1108       corresponding DBus service file, for example
1109       (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service):
1110
1111           [D-BUS Service]
1112           Name=org.example.simple-dbus-service
1113           Exec=/usr/sbin/simple-dbus-service
1114           User=root
1115           SystemdService=simple-dbus-service.service
1116
1117       Please see systemd.kill(5) for details on how you can influence the way
1118       systemd terminates the service.
1119
1120       Example 6. Services that notify systemd about their initialization
1121
1122       Type=simple services are really easy to write, but have the major
1123       disadvantage of systemd not being able to tell when initialization of
1124       the given service is complete. For this reason, systemd supports a
1125       simple notification protocol that allows daemons to make systemd aware
1126       that they are done initializing. Use Type=notify for this. A typical
1127       service file for such a daemon would look like this:
1128
1129           [Unit]
1130           Description=Simple notifying service
1131
1132           [Service]
1133           Type=notify
1134           ExecStart=/usr/sbin/simple-notifying-service
1135
1136           [Install]
1137           WantedBy=multi-user.target
1138
1139       Note that the daemon has to support systemd's notification protocol,
1140       else systemd will think the service has not started yet and kill it
1141       after a timeout. For an example of how to update daemons to support
1142       this protocol transparently, take a look at sd_notify(3). systemd will
1143       consider the unit to be in the 'starting' state until a readiness
1144       notification has arrived.
1145
1146       Please see systemd.kill(5) for details on how you can influence the way
1147       systemd terminates the service.
1148

SEE ALSO

1150       systemd(1), systemctl(1), systemd-system.conf(5), systemd.unit(5),
1151       systemd.exec(5), systemd.resource-control(5), systemd.kill(5),
1152       systemd.directives(7)
1153

NOTES

1155        1. Incompatibilities with SysV
1156           https://www.freedesktop.org/wiki/Software/systemd/Incompatibilities
1157
1158        2. USB FunctionFS
1159           https://www.kernel.org/doc/Documentation/usb/functionfs.txt
1160
1161
1162
1163systemd 241                                                 SYSTEMD.SERVICE(5)
Impressum