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

COMMAND LINES

1009       This section describes command line parsing and variable and specifier
1010       substitutions for ExecStart=, ExecStartPre=, ExecStartPost=,
1011       ExecReload=, ExecStop=, and ExecStopPost= options.
1012
1013       Multiple command lines may be concatenated in a single directive by
1014       separating them with semicolons (these semicolons must be passed as
1015       separate words). Lone semicolons may be escaped as "\;".
1016
1017       Each command line is unquoted using the rules described in "Quoting"
1018       section in systemd.syntax(7). The first item becomes the command to
1019       execute, and the subsequent items the arguments.
1020
1021       This syntax is inspired by shell syntax, but only the meta-characters
1022       and expansions described in the following paragraphs are understood,
1023       and the expansion of variables is different. Specifically, redirection
1024       using "<", "<<", ">", and ">>", pipes using "|", running programs in
1025       the background using "&", and other elements of shell syntax are not
1026       supported.
1027
1028       The command to execute may contain spaces, but control characters are
1029       not allowed.
1030
1031       The command line accepts "%" specifiers as described in
1032       systemd.unit(5).
1033
1034       Basic environment variable substitution is supported. Use "${FOO}" as
1035       part of a word, or as a word of its own, on the command line, in which
1036       case it will be erased and replaced by the exact value of the
1037       environment variable (if any) including all whitespace it contains,
1038       always resulting in exactly a single argument. Use "$FOO" as a separate
1039       word on the command line, in which case it will be replaced by the
1040       value of the environment variable split at whitespace, resulting in
1041       zero or more arguments. For this type of expansion, quotes are
1042       respected when splitting into words, and afterwards removed.
1043
1044       If the command is not a full (absolute) path, it will be resolved to a
1045       full path using a fixed search path determined at compilation time.
1046       Searched directories include /usr/local/bin/, /usr/bin/, /bin/ on
1047       systems using split /usr/bin/ and /bin/ directories, and their sbin/
1048       counterparts on systems using split bin/ and sbin/. It is thus safe to
1049       use just the executable name in case of executables located in any of
1050       the "standard" directories, and an absolute path must be used in other
1051       cases. Using an absolute path is recommended to avoid ambiguity. Hint:
1052       this search path may be queried using systemd-path
1053       search-binaries-default.
1054
1055       Example:
1056
1057           Environment="ONE=one" 'TWO=two two'
1058           ExecStart=echo $ONE $TWO ${TWO}
1059
1060       This will execute /bin/echo with four arguments: "one", "two", "two",
1061       and "two two".
1062
1063       Example:
1064
1065           Environment=ONE='one' "TWO='two two' too" THREE=
1066           ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
1067           ExecStart=/bin/echo $ONE $TWO $THREE
1068
1069       This results in /bin/echo being called twice, the first time with
1070       arguments "'one'", "'two two' too", "", and the second time with
1071       arguments "one", "two two", "too".
1072
1073       To pass a literal dollar sign, use "$$". Variables whose value is not
1074       known at expansion time are treated as empty strings. Note that the
1075       first argument (i.e. the program to execute) may not be a variable.
1076
1077       Variables to be used in this fashion may be defined through
1078       Environment= and EnvironmentFile=. In addition, variables listed in the
1079       section "Environment variables in spawned processes" in
1080       systemd.exec(5), which are considered "static configuration", may be
1081       used (this includes e.g.  $USER, but not $TERM).
1082
1083       Note that shell command lines are not directly supported. If shell
1084       command lines are to be used, they need to be passed explicitly to a
1085       shell implementation of some kind. Example:
1086
1087           ExecStart=sh -c 'dmesg | tac'
1088
1089       Example:
1090
1091           ExecStart=echo one ; echo "two two"
1092
1093       This will execute echo two times, each time with one argument: "one"
1094       and "two two", respectively. Because two commands are specified,
1095       Type=oneshot must be used.
1096
1097       Example:
1098
1099           ExecStart=echo / >/dev/null & \; \
1100           ls
1101
1102       This will execute echo with five arguments: "/", ">/dev/null", "&",
1103       ";", and "ls".
1104

EXAMPLES

1106       Example 2. Simple service
1107
1108       The following unit file creates a service that will execute
1109       /usr/sbin/foo-daemon. Since no Type= is specified, the default
1110       Type=simple will be assumed. systemd will assume the unit to be started
1111       immediately after the program has begun executing.
1112
1113           [Unit]
1114           Description=Foo
1115
1116           [Service]
1117           ExecStart=/usr/sbin/foo-daemon
1118
1119           [Install]
1120           WantedBy=multi-user.target
1121
1122       Note that systemd assumes here that the process started by systemd will
1123       continue running until the service terminates. If the program
1124       daemonizes itself (i.e. forks), please use Type=forking instead.
1125
1126       Since no ExecStop= was specified, systemd will send SIGTERM to all
1127       processes started from this service, and after a timeout also SIGKILL.
1128       This behavior can be modified, see systemd.kill(5) for details.
1129
1130       Note that this unit type does not include any type of notification when
1131       a service has completed initialization. For this, you should use other
1132       unit types, such as Type=notify if the service understands systemd's
1133       notification protocol, Type=forking if the service can background
1134       itself or Type=dbus if the unit acquires a DBus name once
1135       initialization is complete. See below.
1136
1137       Example 3. Oneshot service
1138
1139       Sometimes, units should just execute an action without keeping active
1140       processes, such as a filesystem check or a cleanup action on boot. For
1141       this, Type=oneshot exists. Units of this type will wait until the
1142       process specified terminates and then fall back to being inactive. The
1143       following unit will perform a cleanup action:
1144
1145           [Unit]
1146           Description=Cleanup old Foo data
1147
1148           [Service]
1149           Type=oneshot
1150           ExecStart=/usr/sbin/foo-cleanup
1151
1152           [Install]
1153           WantedBy=multi-user.target
1154
1155       Note that systemd will consider the unit to be in the state "starting"
1156       until the program has terminated, so ordered dependencies will wait for
1157       the program to finish before starting themselves. The unit will revert
1158       to the "inactive" state after the execution is done, never reaching the
1159       "active" state. That means another request to start the unit will
1160       perform the action again.
1161
1162       Type=oneshot are the only service units that may have more than one
1163       ExecStart= specified. For units with multiple commands (Type=oneshot),
1164       all commands will be run again.
1165
1166       For Type=oneshot, Restart=always and Restart=on-success are not
1167       allowed.
1168
1169       Example 4. Stoppable oneshot service
1170
1171       Similarly to the oneshot services, there are sometimes units that need
1172       to execute a program to set up something and then execute another to
1173       shut it down, but no process remains active while they are considered
1174       "started". Network configuration can sometimes fall into this category.
1175       Another use case is if a oneshot service shall not be executed each
1176       time when they are pulled in as a dependency, but only the first time.
1177
1178       For this, systemd knows the setting RemainAfterExit=yes, which causes
1179       systemd to consider the unit to be active if the start action exited
1180       successfully. This directive can be used with all types, but is most
1181       useful with Type=oneshot and Type=simple. With Type=oneshot, systemd
1182       waits until the start action has completed before it considers the unit
1183       to be active, so dependencies start only after the start action has
1184       succeeded. With Type=simple, dependencies will start immediately after
1185       the start action has been dispatched. The following unit provides an
1186       example for a simple static firewall.
1187
1188           [Unit]
1189           Description=Simple firewall
1190
1191           [Service]
1192           Type=oneshot
1193           RemainAfterExit=yes
1194           ExecStart=/usr/local/sbin/simple-firewall-start
1195           ExecStop=/usr/local/sbin/simple-firewall-stop
1196
1197           [Install]
1198           WantedBy=multi-user.target
1199
1200       Since the unit is considered to be running after the start action has
1201       exited, invoking systemctl start on that unit again will cause no
1202       action to be taken.
1203
1204       Example 5. Traditional forking services
1205
1206       Many traditional daemons/services background (i.e. fork, daemonize)
1207       themselves when starting. Set Type=forking in the service's unit file
1208       to support this mode of operation. systemd will consider the service to
1209       be in the process of initialization while the original program is still
1210       running. Once it exits successfully and at least a process remains (and
1211       RemainAfterExit=no), the service is considered started.
1212
1213       Often, a traditional daemon only consists of one process. Therefore, if
1214       only one process is left after the original process terminates, systemd
1215       will consider that process the main process of the service. In that
1216       case, the $MAINPID variable will be available in ExecReload=,
1217       ExecStop=, etc.
1218
1219       In case more than one process remains, systemd will be unable to
1220       determine the main process, so it will not assume there is one. In that
1221       case, $MAINPID will not expand to anything. However, if the process
1222       decides to write a traditional PID file, systemd will be able to read
1223       the main PID from there. Please set PIDFile= accordingly. Note that the
1224       daemon should write that file before finishing with its initialization.
1225       Otherwise, systemd might try to read the file before it exists.
1226
1227       The following example shows a simple daemon that forks and just starts
1228       one process in the background:
1229
1230           [Unit]
1231           Description=Some simple daemon
1232
1233           [Service]
1234           Type=forking
1235           ExecStart=/usr/sbin/my-simple-daemon -d
1236
1237           [Install]
1238           WantedBy=multi-user.target
1239
1240       Please see systemd.kill(5) for details on how you can influence the way
1241       systemd terminates the service.
1242
1243       Example 6. DBus services
1244
1245       For services that acquire a name on the DBus system bus, use Type=dbus
1246       and set BusName= accordingly. The service should not fork (daemonize).
1247       systemd will consider the service to be initialized once the name has
1248       been acquired on the system bus. The following example shows a typical
1249       DBus service:
1250
1251           [Unit]
1252           Description=Simple DBus service
1253
1254           [Service]
1255           Type=dbus
1256           BusName=org.example.simple-dbus-service
1257           ExecStart=/usr/sbin/simple-dbus-service
1258
1259           [Install]
1260           WantedBy=multi-user.target
1261
1262       For bus-activatable services, do not include a [Install] section in the
1263       systemd service file, but use the SystemdService= option in the
1264       corresponding DBus service file, for example
1265       (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service):
1266
1267           [D-BUS Service]
1268           Name=org.example.simple-dbus-service
1269           Exec=/usr/sbin/simple-dbus-service
1270           User=root
1271           SystemdService=simple-dbus-service.service
1272
1273       Please see systemd.kill(5) for details on how you can influence the way
1274       systemd terminates the service.
1275
1276       Example 7. Services that notify systemd about their initialization
1277
1278       Type=simple services are really easy to write, but have the major
1279       disadvantage of systemd not being able to tell when initialization of
1280       the given service is complete. For this reason, systemd supports a
1281       simple notification protocol that allows daemons to make systemd aware
1282       that they are done initializing. Use Type=notify for this. A typical
1283       service file for such a daemon would look like this:
1284
1285           [Unit]
1286           Description=Simple notifying service
1287
1288           [Service]
1289           Type=notify
1290           ExecStart=/usr/sbin/simple-notifying-service
1291
1292           [Install]
1293           WantedBy=multi-user.target
1294
1295       Note that the daemon has to support systemd's notification protocol,
1296       else systemd will think the service has not started yet and kill it
1297       after a timeout. For an example of how to update daemons to support
1298       this protocol transparently, take a look at sd_notify(3). systemd will
1299       consider the unit to be in the 'starting' state until a readiness
1300       notification has arrived.
1301
1302       Please see systemd.kill(5) for details on how you can influence the way
1303       systemd terminates the service.
1304

SEE ALSO

1306       systemd(1), systemctl(1), systemd-system.conf(5), systemd.unit(5),
1307       systemd.exec(5), systemd.resource-control(5), systemd.kill(5),
1308       systemd.directives(7), systemd-run(1)
1309

NOTES

1311        1. USB FunctionFS
1312           https://www.kernel.org/doc/Documentation/usb/functionfs.txt
1313
1314
1315
1316systemd 250                                                 SYSTEMD.SERVICE(5)
Impressum