X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=238a49a2512c610910b27b6c01369b487839f5f9;hb=21bf2ab082b42f03df5b4685df2fddc4d6e0d572;hp=837a992ba4fa1f17f419e86ad73115699facd7df;hpb=19c5f19d69bb5f520fa7213239490c55de06d99d;p=elogind.git
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 837a992ba..238a49a25 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,11 +44,11 @@
systemd.service
- systemd service configuration files
+ Service unit configuration
- systemd.service
+ service.service
@@ -72,7 +72,13 @@
Additional options are listed in
systemd.exec5,
which define the execution environment the commands
- are executed in.
+ are executed in, and in
+ systemd.kill5,
+ which define the way the processes of the service are
+ terminated, and in
+ systemd.cgroup5,
+ which configure control group settings for the
+ processes of the service.
Unless DefaultDependencies=
is set to , service units will
@@ -95,7 +101,12 @@
.service suffix removed) and
dynamically creates a service unit from that
script. This is useful for compatibility with
- SysV.
+ SysV. Note that this compatibility is quite
+ comprehensive but not 100%. For details about the
+ incompatibilities see the Incompatibilities
+ with SysV document.
+
@@ -107,11 +118,13 @@
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
+ systemd.exec5
+ and
+ systemd.kill5. The
options specific to the [Service]
section of service units are the following:
-
+ Type=
@@ -121,12 +134,14 @@
,
,
,
- .
+ 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, if the process offers
@@ -148,7 +163,7 @@
complete and all communication
channels set up. The child continues
to run as the main daemon
- process. This is the behaviour of
+ process. This is the behavior of
traditional UNIX daemons. If this
setting is used, it is recommended to
also use the
@@ -159,7 +174,7 @@
soon as the parent process
exits.
- Behaviour of
+ Behavior of
is similar
to , however
it is expected that the process has to
@@ -168,7 +183,7 @@
is particularly useful for this type
of service.
- Behaviour of
+ Behavior of
is similar to
, however it is
expected that the daemon acquires a
@@ -181,9 +196,11 @@
option configured implicitly gain
dependencies on the
dbus.socket
- unit.
+ unit. This type is the default if
+ BusName= is
+ specified.
- Behaviour of
+ Behavior of
is similar to
, however it is
expected that the daemon sends a
@@ -201,6 +218,16 @@
NotifyAccess= is
not set, it will be implicitly set to
.
+
+ Behavior of
+ is very similar
+ to , however
+ actual execution of 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.
@@ -221,7 +248,7 @@
Takes a boolean value
that specifies whether systemd should
try to guess the main PID of a service
- should if it cannot be determined
+ if it cannot be determined
reliably. This option is ignored
unless
is set and
@@ -259,7 +286,7 @@
BusName=Takes a D-Bus bus
- name, where this service is reachable
+ name, that this service is reachable
as. This option is mandatory for
services where
Type= is set to
@@ -272,52 +299,62 @@
ExecStart=
- Takes a command line
- that is executed when this service
- shall be started up. The first token
- of the command line must be an
- absolute file name, then followed by
- arguments for the process. It is
- mandatory to set this option for all
- services. This option may not be
- specified more than once, except when
+ Commands with their
+ arguments that are executed when this
+ service is started. The first
+ argument must be an absolute path
+ name.
+
+ When Type is
+ not , only one
+ command may be given. 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
+ used, more than one command may be
+ specified. Multiple command lines may
+ be concatenated in a single directive,
+ by separating them with semicolons
+ (these semicolons must be passed as
+ separate words). Alternatively, this
+ directive 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.
+ Lone semicolons may be escaped as
+ \;. If the empty
+ string is assigned to this option the
+ list of commands to start is reset,
+ prior assignments of this option will
+ have no effect.
+
+ If more than one command is
+ specified, the commands are invoked
+ one by one sequentially in the order
+ they appear in the unit file. If one
+ of the commands fails (and is not
+ prefixed with -),
+ other lines are not executed and the
+ unit is considered failed.
+
+ 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
+ main process of the daemon.
+
+ The command line accepts
+ % specifiers as
described in
- systemd.unit5.
+ systemd.unit5. Note
+ that the first argument of the command
+ line (i.e. the program to execute) may
+ not include specifiers.
- On top of that basic environment
- variable substitution is
- supported. Use
+ Basic environment variable
+ substitution is supported. Use
${FOO} as part of a
- word, or as word of its own on the
+ word, or as a word of its own on the
command line, in which case it will be
replaced by the value of the
environment variable including all
@@ -327,38 +364,66 @@
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
+ at whitespace, resulting in zero 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.
+ may not be a variable, since it must
+ be a literal and absolute path
+ name.
+
+ 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
+ absolute filename 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 they
+ can appear in either order.
+
+ Note that this setting does not
+ directly support shell command
+ lines. If shell command lines are to
+ be used they need to be passed
+ explicitly to a shell implementation
+ of some kind. Example:
+ ExecStart=/bin/sh -c 'dmesg | tac'
+
+
+ For services run by a user
+ instance of systemd the special
+ environment variable
+ $MANAGERPID is set
+ to the PID of the systemd
+ instance.
+ ExecStartPre=ExecStartPost=Additional commands
- that are executed before (resp. after)
+ that are executed before or after
the command in
- 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.
+ ExecStart=, respectively.
+ Syntax is the same as for
+ ExecStart=, except
+ that multiple command lines are allowed
+ and the commands are executed one
+ after the other, serially.
+
+ If any of those commands (not
+ prefixed with -)
+ fail, the rest are not executed and
+ the unit is considered failed.
+
@@ -367,20 +432,23 @@
trigger a configuration reload in the
service. This argument takes multiple
command lines, following the same
- scheme as pointed out for
- ExecStartPre=
+ scheme as described for
+ ExecStart=
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.
+ ExecStart=.
+
+ One additional special
+ environment variables 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
+
@@ -389,22 +457,22 @@
stop the service started via
ExecStart=. This
argument takes multiple command lines,
- following the same scheme as pointed
- out for
- ExecStartPre=
+ following the same scheme as described
+ for ExecStart=
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. Specifier and environment
- variable substitution is supported
- (including
- $MAINPID, see
+ (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).
@@ -412,13 +480,15 @@
ExecStopPost=Additional commands
that are executed after the service
- was stopped using the commands
- configured in
- ExecStop=. This
+ was stopped. This includes cases where
+ the commands configured in
+ ExecStop= were used,
+ where the service doesn't have any
+ ExecStop= defined, or
+ where the service exited unexpectedly. This
argument takes multiple command lines,
- following the same scheme as pointed
- out for
- ExecStartPre. Use
+ following the same scheme as described
+ for ExecStart. Use
of these settings is
optional. Specifier and environment
variable substitution is
@@ -438,54 +508,81 @@
- 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
- forcibly via SIGTERM, and after
+ 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
+ SIGKILL (See
KillMode=
- below.) Takes a unit-less value in seconds, or a
+ 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
- 90s.
+ 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
+ watchdog timeout for a service. The
+ watchdog is activated when the start-up is
completed. The service must call
sd_notify3
- regularly with "WATCHDOG=1". 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
+ 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. If
+ 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
+ NotifyAccess= is
+ not set, it will be implicitly set to
. Defaults to 0,
which disables this
feature.
@@ -494,35 +591,122 @@
Restart=Configures whether the
- main service process shall be
- restarted when it exits. Takes one of
+ service shall be restarted when the
+ service process exits, is killed,
+ or a timeout is reached. The service
+ process may be the main service
+ process, but also one of the processes
+ specified with
+ ExecStartPre=,
+ ExecStartPost=,
+ ExecStopPre=,
+ ExecStopPost=, or
+ ExecReload=.
+ When the death of the process is a
+ result of systemd operation (e.g. service
+ stop or restart), the service will not be
+ restarted. Timeouts include missing
+ the watchdog "keep-alive ping"
+ deadline and a service start, reload,
+ and stop operation timeouts.
+
+ Takes one of
,
,
,
- or
+ , or
. If set to
(the default) the
- service will not be restarted when it
- exits. If set to
+ service will not be restarted. 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, when an
- operation 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. 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.
+ restarted only when the service process
+ exits cleanly.
+ In this context, a clean exit means
+ an exit code of 0, or one of the signals
+ SIGHUP, SIGINT, SIGTERM, or SIGPIPE, and
+ additionally, exit statuses and signals
+ specified in SuccessExitStatus=.
+ If set to
+ the service will be restarted when the
+ process exits with an nonzero exit code,
+ is terminated by a signal (including on
+ core dump), when an operation (such as
+ service reload) times out, and when the
+ configured watchdog timeout is triggered.
+ If set to
+ the service
+ will be restarted only if the service
+ process exits due to an uncaught
+ signal not specified as a clean exit
+ status.
+ 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.
+
+ In addition to the above settings,
+ the service will not be restarted if the
+ exit code or signal is specified in
+ RestartPreventExitStatus=
+ (see below).
+
+
+
+ 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,
+ 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. This option may
+ appear more than once in which case
+ the list of successful exit statuses
+ is merged. If the empty string is
+ assigned to this option the list is
+ reset, all prior assignments of this
+ option will have no
+ effect.
+
+
+
+ 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. This
+ option may appear more than once in
+ which case the list of restart preventing
+ statuses is merged. If the empty
+ string is assigned to this option the
+ list is reset, all prior assignments
+ of this option will have no
+ effect.
@@ -572,95 +756,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 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 (unless the
- signal to send is changed via
- KillSignal=). If
- then after a delay (configured via the
- TimeoutSec= option)
- processes still remain, the
- termination request is repeated with
- the SIGKILL signal (unless this is
- disabled via the
- SendSIGKILL=
- option). See
- kill2
- for more
- information.
-
-
-
- KillSignal=
- Specifies which signal
- to use when killing a
- service. Defaults to SIGTERM.
-
-
-
-
- SendSIGKILL=
- Specifies whether to
- send SIGKILL to remaining processes
- after a timeout, if the normal
- shutdown procedure left processes of
- the service around. Takes a boolean
- value. Defaults to "yes".
-
-
-
NonBlocking=Set O_NONBLOCK flag
@@ -699,7 +794,7 @@
open access to the notification socket
when using
Type=notify or
- WatchdogUsec= (see
+ WatchdogSec= (see
above). If those options are used but
NotifyAccess= not
configured it will be implicitly set
@@ -725,40 +820,22 @@
same time. Also note that a different
service may be activated on incoming
traffic than inherits the sockets. Or
- in other words: The
+ 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.
-
-
-
- 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.
+ doesn't have to match the inverse of
+ the Sockets=
+ setting of the
+ .service it
+ refers to.
+
+ This option may appear more than
+ once, in which case the list of socket
+ units is merged. If the empty string
+ is assigned to this option the list of
+ sockets is reset, all prior uses of
+ this setting will have no
+ effect.
@@ -782,7 +859,27 @@
are allowed (defaults to 5). These
configuration options are particularly
useful in conjunction with
- Restart=.
+ 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.
@@ -822,6 +919,75 @@
+
+ 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.
+
+
+
@@ -830,7 +996,10 @@
systemd1,
systemctl8,
systemd.unit5,
- systemd.exec5
+ systemd.exec5,
+ systemd.cgroup5,
+ systemd.kill5,
+ systemd.directives7