X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=72b67c698801c2a00b44f8849ea82ee28a43471e;hp=8005a51a472150f8a9fce31f50c21ad7148237f2;hb=abdf7993161a2762df6887fdb5a5f0f4f5da24cf;hpb=65232ea79d8f6b1288c33852f89b575a9200162d
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 8005a51a4..72b67c698 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -9,16 +9,16 @@
Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
+ Lesser General Public License for more details.
- You should have received a copy of the GNU General Public License
+ You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see .
-->
@@ -44,7 +44,7 @@
systemd.service
- systemd service configuration files
+ Service unit configuration
@@ -64,24 +64,62 @@
systemd.unit5
for the common options of all unit configuration
files. The common configuration items are configured
- in the generic [Unit] and [Install] sections. The
- service specific configuration options are configured
- in the [Service] section.
-
- Additional options are listed in systemd.exec5.
+ in the generic [Unit] and
+ [Install] sections. The service
+ specific configuration options are configured in the
+ [Service] section.
+
+ Additional options are listed in
+ systemd.exec5,
+ which define the execution environment the commands
+ are executed in, and in
+ systemd.kill5
+ which define the way the processes of the service are
+ terminated.
+
+ Unless DefaultDependencies=
+ is set to , service units will
+ implicitly have dependencies of type
+ Requires= and
+ After= on
+ basic.target as well as
+ dependencies of type Conflicts= and
+ Before= on
+ shutdown.target. These ensure
+ that normal service units pull in basic system
+ initialization, and are terminated cleanly prior to
+ system shutdown. Only services involved with early
+ boot or late system shutdown should disable this
+ option.
+
+ If a service is requested under a certain name
+ but no unit configuration file is found, systemd looks
+ for a SysV init script by the same name (with the
+ .service suffix removed) and
+ dynamically creates a service unit from that
+ script. This is useful for compatibility with
+ SysV. Note that this compatibility is quite
+ comprehensive but not 100%. For details about the
+ incomptibilities see the Incompatibilities
+ with SysV document.
+ Options
- Service files must include a [Service] section,
- which carries information about the service and the
- process it supervises. A number of options that may be
- used in this section are shared with other unit
- types. These options are documented in
- systemd.exec5. The
- options specific to the [Service] section of service
- units are the following:
+ Service files must include a
+ [Service] section, which carries
+ information about the service and the process it
+ supervises. A number of options that may be used in
+ this section are shared with other unit types. These
+ options are documented in
+ systemd.exec5
+ and
+ systemd.kill5. The
+ options specific to the [Service]
+ section of service units are the following:
@@ -91,35 +129,39 @@
start-up type for this service
unit. One of ,
,
- ,
+ ,
,
- .
+ or
+ .
If set to
(the default
- value) it is expected that the process
- configured with
+ value if BusName=
+ is not specified) it is expected that
+ the process configured with
ExecStart= is the
main process of the service. In this
- mode, communication channels must be
- installed before the daemon is started
- up (e.g. sockets set up by systemd,
- via socket activation), as systemd
- will immediately proceed starting
- follow-up units.
+ mode, if the process offers
+ functionality to other processes on
+ the system its communication channels
+ should be installed before the daemon
+ is started up (e.g. sockets set up by
+ systemd, via socket activation), as
+ systemd will immediately proceed
+ starting follow-up units.
If set to
it is
expected that the process configured
with ExecStart=
- will start up and call
- fork(). The
- parent process is expected to finish
- when start-up is complete and all
- communication channels set up. The
- child continues to run as the main
- daemon process. This is the behaviour
- of traditional UNIX daemons. If this
+ will call fork()
+ as part of its start-up. The parent process is
+ expected to exit when start-up is
+ complete and all communication
+ channels set up. The child continues
+ to run as the main daemon
+ process. This is the behaviour of
+ traditional UNIX daemons. If this
setting is used, it is recommended to
also use the
PIDFile= option, so
@@ -130,24 +172,30 @@
exits.Behaviour of
- is similar
+ is similar
to , however
it is expected that the process has to
exit before systemd starts follow-up
- units. ValidNoProcess=
+ units. RemainAfterExit=
is particularly useful for this type
of service.Behaviour of
is similar to
- , however it
- is expected that the daemon acquires a
+ , however it is
+ expected that the daemon acquires a
name on the D-Bus bus, as configured
by
BusName=. systemd
will proceed starting follow-up units
after the D-Bus bus name has been
- acquired.
+ acquired. Service units with this
+ option configured implicitly gain
+ dependencies on the
+ dbus.socket
+ unit. This type is the default if
+ BusName= is
+ specified.
Behaviour of
is similar to
@@ -160,15 +208,28 @@
starting follow-up units after this
notification message has been sent. If
this option is used
- (see
- below) must be set to open access to
+ NotifyAccess= (see
+ below) should be set to open access to
the notification socket provided by
- systemd.
+ systemd. If
+ NotifyAccess= is
+ not set, it will be implicitly set to
+ .
+
+ Behaviour of
+ is very similar
+ to , however
+ actual execution of a the service
+ binary is delayed until all jobs are
+ dispatched. This may be used to avoid
+ interleaving of output of shell
+ services with the status output on the
+ console.
- ValidNoProcess=
+ RemainAfterExit=Takes a boolean value
that specifies whether the service
@@ -178,6 +239,30 @@
+
+ GuessMainPID=
+
+ Takes a boolean value
+ that specifies whether systemd should
+ try to guess the main PID of a service
+ should if it cannot be determined
+ reliably. This option is ignored
+ unless
+ is set and
+ is unset because for the other types
+ or with an explicitly configured PID
+ file the main PID is always known. The
+ guessing algorithm might come to
+ incorrect conclusions if a daemon
+ consists of more than one process. If
+ the main PID cannot be determined
+ failure detection and automatic
+ restarting of a service will not work
+ reliably. Defaults to
+ .
+
+
+
PIDFile=
@@ -186,7 +271,11 @@
daemon. Use of this option is
recommended for services where
Type= is set to
- .
+ . systemd will
+ read the PID of the main process of
+ the daemon after start-up of the
+ service. systemd will not write to the
+ file configured here.
@@ -215,17 +304,59 @@
arguments for the process. It is
mandatory to set this option for all
services. This option may not be
- specified more than once. Optionally,
- if the absolute file name is prefixed
- with @, the second token will be
- passed as argv[0] to the executed
- process, followed by the further
- arguments specified. Unless
- is set,
- the process started via this command
- line will be considered the main
- process of the
- daemon.
+ specified more than once, except when
+ Type=oneshot is
+ used in which case more than one
+ ExecStart= line is
+ accepted which are then invoked one by
+ one, sequentially in the order they
+ appear in the unit file.
+
+ Optionally, if the absolute file
+ name is prefixed with
+ @, the second token
+ will be passed as
+ argv[0] to the
+ executed process, followed by the
+ further arguments specified. If the
+ first token is prefixed with
+ - an exit code of
+ the command normally considered a
+ failure (i.e. non-zero exit status or
+ abnormal exit due to signal) is ignored
+ and considered success. If both
+ - and
+ @ are used for the
+ same command the former must precede
+ the latter. Unless
+ Type=forking is
+ set, the process started via this
+ command line will be considered the
+ main process of the daemon. The
+ command line accepts % specifiers as
+ described in
+ systemd.unit5.
+
+ On top of that basic environment
+ variable substitution is
+ supported. Use
+ ${FOO} as part of a
+ word, or as word of its own on the
+ command line, in which case it will be
+ replaced by the value of the
+ environment variable including all
+ whitespace it contains, resulting in a
+ single argument. Use
+ $FOO as a separate
+ word on the command line, in which
+ case it will be replaced by the value
+ of the environment variable split up
+ at whitespace, resulting in no or more
+ arguments. Note that the first
+ argument (i.e. the program to execute)
+ may not be a variable, and must be a
+ literal and absolute path
+ name.
@@ -234,40 +365,72 @@
Additional commands
that are executed before (resp. after)
the command in
- ExecStart=. If
- specified more than once, all commands
- are executed one after the other,
- serially. Use of these settings is
- optional.
+ ExecStart=. Multiple
+ command lines may be concatenated in a
+ single directive, by separating them
+ by semicolons (these semicolons must
+ be passed as separate words). In that
+ case, the commands are executed one
+ after the other,
+ serially. Alternatively, these
+ directives may be specified more than
+ once with the same effect. However,
+ the latter syntax is not recommended
+ for compatibility with parsers
+ suitable for XDG
+ .desktop files.
+ Use of these settings is
+ optional. Specifier and environment
+ variable substitution is
+ supported.
ExecReload=Commands to execute to
trigger a configuration reload in the
- service. If used more than once, all
- commands are executed one after the
- other, serially. Use of this setting is optional.
-
+ service. This argument takes multiple
+ command lines, following the same
+ scheme as pointed out for
+ ExecStartPre=
+ above. Use of this setting is
+ optional. Specifier and environment
+ variable substitution is supported
+ here following the same scheme as for
+ ExecStart=. One
+ special environment variable is set:
+ if known $MAINPID is
+ set to the main process of the
+ daemon, and may be used for command
+ lines like the following:
+ /bin/kill -HUP
+ $MAINPID.
ExecStop=Commands to execute to
stop the service started via
- ExecStart=. If used
- more than once, all commands are
- executed one after the other,
- serially. Use of this setting is
+ ExecStart=. This
+ argument takes multiple command lines,
+ following the same scheme as pointed
+ out for
+ ExecStartPre=
+ above. Use of this setting is
optional. All processes remaining for
a service after the commands
configured in this option are run are
terminated according to the
KillMode= setting
- (see below). If this option is not
- specified the process is terminated
- right-away when service stop is
- requested.
+ (see
+ systemd.kill5). If
+ this option is not specified the
+ process is terminated right-away when
+ service stop is requested. Specifier
+ and environment variable substitution
+ is supported (including
+ $MAINPID, see
+ above).
@@ -276,11 +439,15 @@
that are executed after the service
was stopped using the commands
configured in
- ExecStop=. If
- specified more than once, all commands
- are executed one after the other,
- serially. Use of these settings is
- optional.
+ ExecStop=. This
+ argument takes multiple command lines,
+ following the same scheme as pointed
+ out for
+ ExecStartPre. Use
+ of these settings is
+ optional. Specifier and environment
+ variable substitution is
+ supported.
@@ -296,47 +463,163 @@
- TimeoutSec=
+ TimeoutStartSec=Configures the time to
- wait for start-up and stop. If a
+ wait for start-up. If a
daemon service does not signal
start-up completion within the
- configured time the service will be
+ configured time, the service will be
considered failed and be shut down
- again. If a service is asked to stop
- but does not terminate in the
- specified time it will be terminated
+ again.
+ Takes a unit-less value in seconds, or a
+ time span value such as "5min
+ 20s". Pass 0 to disable the timeout
+ logic. Defaults to 90s, except when
+ Type=oneshot is
+ used in which case the timeout
+ is disabled by default.
+
+
+
+
+ TimeoutStopSec=
+ Configures the time to
+ wait for stop. If a service is asked
+ to stop but does not terminate in the
+ specified time, it will be terminated
forcibly via SIGTERM, and after
another delay of this time with
- SIGKILL. (See
-
- below.) Takes a unit-less value in seconds, or a
+ SIGKILL (See
+ KillMode=
+ in systemd.kill5).
+ Takes a unit-less value in seconds, or a
time span value such as "5min
20s". Pass 0 to disable the timeout
- logic. Defaults to
- 60s.
+ logic. Defaults to 90s.
+
+
+
+
+ TimeoutSec=
+ A shorthand for configuring
+ both TimeoutStartSec=
+ and TimeoutStopSec=
+ to the specified value.
+
+
+
+
+ WatchdogSec=
+ Configures the
+ watchdog timeout for a service. This
+ is activated when the start-up is
+ completed. The service must call
+ sd_notify3
+ regularly with "WATCHDOG=1" (i.e. the
+ "keep-alive ping"). If the time
+ between two such calls is larger than
+ the configured time then the service
+ is placed in a failure state. By
+ setting Restart= to
+ or
+ the service
+ will be automatically restarted. The
+ time configured here will be passed to
+ the executed service process in the
+ WATCHDOG_USEC=
+ environment variable. This allows
+ daemons to automatically enable the
+ keep-alive pinging logic if watchdog
+ support is enabled for the service. If
+ this option is used
+ NotifyAccess= (see
+ below) should be set to open access to
+ the notification socket provided by
+ systemd. If
+ NotifyAccess= is
+ not set, it will be implicitly set to
+ . Defaults to 0,
+ which disables this
+ feature.Restart=Configures whether the
- main service process shall be restarted when
- it exists. Takes one of
- ,
- or
- . If
- set to (the
- default) the service will not be
- restarted when it exits. If set to
- it
- will be restarted only when it exited
- cleanly, i.e. terminated with an exit
- code of 0. If set to
- the
- service will be restarted regardless
- whether it exited cleanly or not, or
- got terminated abnormally by a
- signal.
+ main service process shall be
+ restarted when it exits. Takes one of
+ ,
+ ,
+ ,
+ or
+ . If set to
+ (the default) the
+ service will not be restarted when it
+ exits. If set to
+ it will be
+ restarted only when it exited cleanly,
+ i.e. terminated with an exit code of
+ 0. If set to
+ it will be
+ restarted only when it exited with an
+ exit code not equalling 0, when
+ terminated by a signal (including on
+ core dump), when an operation (such as
+ service reload) times out or when the
+ configured watchdog timeout is
+ triggered. If set to
+ it will be
+ restarted only if it exits due to
+ reception of an uncaught signal
+ (including on core dump). If set to
+ the service
+ will be restarted regardless whether
+ it exited cleanly or not, got
+ terminated abnormally by a signal or
+ hit a timeout.
+
+
+
+ SuccessExitStatus=
+ Takes a list of exit
+ status definitions that when returned
+ by the main service process will be
+ considered successful termination, in
+ addition to the normal successful exit
+ code 0 and the signals SIGHUP, SIGINT,
+ SIGTERM and SIGPIPE. Exit status
+ definitions can either be numeric exit
+ codes or termination signal names, and
+ are are separated by spaces. Example:
+ "SuccessExitStatus=1 2 8
+ SIGKILL", ensures that exit
+ codes 1, 2, 8 and the termination
+ signal SIGKILL are considered clean
+ service
+ terminations.
+
+
+
+ RestartPreventExitStatus=
+ Takes a list of exit
+ status definitions that when returned
+ by the main service process will
+ prevent automatic service restarts
+ regardless of the restart setting
+ configured with
+ Restart=. Exit
+ status definitions can either be
+ numeric exit codes or termination
+ signal names, and are separated by
+ spaces. Defaults to the empty list, so
+ that by default no exit status is
+ excluded from the configured restart
+ logic. Example:
+ "RestartPreventExitStatus=1 6
+ SIGABRT", ensures that exit
+ codes 1 and 6 and the termination signal
+ SIGABRT will not result in automatic
+ service restarting.
@@ -386,76 +669,6 @@
false.
-
- SysVStartPriority=
- Set the SysV start
- priority to use to order this service
- in relation to SysV services lacking
- LSB headers. This option is only
- necessary to fix ordering in relation
- to legacy SysV services, that have no
- ordering information encoded in the
- script headers. As such it should only
- be used as temporary compatibility
- option, and not be used in new unit
- files. Almost always it is a better
- choice to add explicit ordering
- directives via
- After= or
- Before=,
- instead. For more details see
- systemd.unit5. If
- used, pass an integer value in the
- range 0-99.
-
-
-
- KillMode=
- Specifies how
- processes of this service shall be
- killed. One of
- ,
- ,
- ,
- .
-
- If set to
- all
- remaining processes in the control
- group of this service will be
- terminated on service stop, after the
- stop command (as configured with
- ExecStop=) is
- executed. If set to
- only
- the members of the process group of
- the main service process are
- killed. If set to
- only the main
- process itself is killed. If set to
- no process is
- killed. In this case only the stop
- command will be executed on service
- stop, but no process be killed
- otherwise. Processes remaining alive
- after stop are left in their control
- group and the control group continues
- to exist after stop unless it is
- empty. Defaults to
- .
-
- Processes will first be
- terminated via SIGTERM. If then after
- a delay (configured via the
- option)
- processes still remain, the
- termination request is repeated with
- the SIGKILL signal. See
- kill2
- for more
- information.
-
-
NonBlocking=Set O_NONBLOCK flag
@@ -482,7 +695,7 @@
or
. If
no daemon status
- updates are accepted by the service
+ updates are accepted from the service
processes, all status update messages
are ignored. If
only service updates sent from the
@@ -490,10 +703,192 @@
accepted. If all
services updates from all members of
the service's control group are
- accepted. This option must be set to
+ accepted. This option should be set to
open access to the notification socket
when using
- Type=notify (see above).
+ Type=notify or
+ WatchdogUsec= (see
+ above). If those options are used but
+ NotifyAccess= not
+ configured it will be implicitly set
+ to
+ .
+
+
+
+ Sockets=
+ Specifies the name of
+ the socket units this service shall
+ inherit the sockets from when the
+ service is started. Normally it
+ should not be necessary to use this
+ setting as all sockets whose unit
+ shares the same name as the service
+ (ignoring the different suffix of course)
+ are passed to the spawned
+ process.
+
+ Note that the same socket may be
+ passed to multiple processes at the
+ same time. Also note that a different
+ service may be activated on incoming
+ traffic than inherits the sockets. Or
+ in other words: The
+ Service= setting of
+ .socket units
+ doesn't have to match the inverse of the
+ Sockets= setting of
+ the .service it
+ refers to.
+
+
+
+ StartLimitInterval=
+ StartLimitBurst=
+
+ Configure service
+ start rate limiting. By default
+ services which are started more often
+ than 5 times within 10s are not
+ permitted to start any more times
+ until the 10s interval ends. With
+ these two options this rate limiting
+ may be modified. Use
+ StartLimitInterval=
+ to configure the checking interval
+ (defaults to 10s, set to 0 to disable
+ any kind of rate limiting). Use
+ StartLimitBurst= to
+ configure how many starts per interval
+ are allowed (defaults to 5). These
+ configuration options are particularly
+ useful in conjunction with
+ Restart=, however
+ apply to all kinds of starts
+ (including manual), not just those
+ triggered by the
+ Restart= logic.
+ Note that units which are configured
+ for Restart= and
+ which reach the start limit are not
+ attempted to be restarted anymore,
+ however they may still be restarted
+ manually at a later point from which
+ point on the restart logic is again
+ activated. Note that
+ systemctl
+ reset-failed will cause the
+ restart rate counter for a service to
+ be flushed, which is useful if the
+ administrator wants to manually start
+ a service and the start limit
+ interferes with
+ that.
+
+
+
+ StartLimitAction=
+
+ Configure the action
+ to take if the rate limit configured
+ with
+ StartLimitInterval=
+ and
+ StartLimitBurst= is
+ hit. Takes one of
+ ,
+ ,
+ or
+ . If
+ is set,
+ hitting the rate limit will trigger no
+ action besides that the start will not
+ be
+ permitted.
+ causes a reboot following the normal
+ shutdown procedure (i.e. equivalent to
+ systemctl reboot),
+ causes
+ an forced reboot which will terminate
+ all processes forcibly but should
+ cause no dirty file systems on reboot
+ (i.e. equivalent to systemctl
+ reboot -f) and
+
+ causes immediate execution of the
+ reboot2
+ system call, which might result in
+ data loss. Defaults to
+ .
+
+
+
+
+ Check
+ systemd.exec5
+ and
+ systemd.kill5
+ for more settings.
+
+
+
+
+ Compatibility Options
+
+ The following options are also available in the
+ [Service] section, but exist purely
+ for compatibility reasons and should not be used in
+ newly written service files.
+
+
+
+ SysVStartPriority=
+ Set the SysV start
+ priority to use to order this service
+ in relation to SysV services lacking
+ LSB headers. This option is only
+ necessary to fix ordering in relation
+ to legacy SysV services, that have no
+ ordering information encoded in the
+ script headers. As such it should only
+ be used as temporary compatibility
+ option, and not be used in new unit
+ files. Almost always it is a better
+ choice to add explicit ordering
+ directives via
+ After= or
+ Before=,
+ instead. For more details see
+ systemd.unit5. If
+ used, pass an integer value in the
+ range 0-99.
+
+
+
+ FsckPassNo=
+ Set the fsck passno
+ priority to use to order this service
+ in relation to other file system
+ checking services. This option is only
+ necessary to fix ordering in relation
+ to fsck jobs automatically created for
+ all /etc/fstab
+ entries with a value in the fs_passno
+ column > 0. As such it should only be
+ used as option for fsck
+ services. Almost always it is a better
+ choice to add explicit ordering
+ directives via
+ After= or
+ Before=,
+ instead. For more details see
+ systemd.unit5. If
+ used, pass an integer value in the
+ same range as
+ /etc/fstab's
+ fs_passno column. See
+ fstab5
+ for details.
@@ -502,10 +897,11 @@
See Also
- systemd8,
+ systemd1,
systemctl8,
systemd.unit5,
- systemd.exec5
+ systemd.exec5,
+ systemd.kill5