X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=d316ab5d2ef3e465a99425e7dc6f30fba93260cf;hb=a4cd87e9dce6d38846f23d44df9e21f322f946df;hp=59ecf810fb82bebeb1497848df55ba27fe6a52b1;hpb=97ae63e2a9c07ee64ab9f226b9b6121114f1d732;p=elogind.git
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 59ecf810f..d316ab5d2 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -48,7 +48,7 @@
- systemd.service
+ service.service
@@ -73,9 +73,12 @@
systemd.exec5,
which define the execution environment the commands
are executed in, and in
- systemd.kill5
+ systemd.kill5,
which define the way the processes of the service are
- terminated.
+ terminated, and in
+ systemd.resource-control5,
+ which configure resource control settings for the
+ processes of the service.
Unless DefaultDependencies=
is set to , service units will
@@ -100,7 +103,7 @@
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.
@@ -121,7 +124,7 @@
options specific to the [Service]
section of service units are the following:
-
+ Type=
@@ -136,14 +139,16 @@
If set to
(the default
- value if BusName=
- is not specified) it is expected that
- the process configured with
+ value if neither
+ Type= nor
+ BusName= are
+ specified), it is expected that the
+ process configured with
ExecStart= is the
main process of the service. In this
mode, if the process offers
functionality to other processes on
- the system its communication channels
+ 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
@@ -151,14 +156,14 @@
starting follow-up units.If set to
- it is
+ , it is
expected that the process configured
with ExecStart=
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
+ channels are set up. The child continues
to run as the main daemon
process. This is the behavior of
traditional UNIX daemons. If this
@@ -207,19 +212,23 @@
starting up. systemd will proceed
starting follow-up units after this
notification message has been sent. If
- this option is used
+ 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
- .
+ . Note that
+ currently
+ Type=
+ will not work if used in combination with
+ PrivateNetwork=.
Behavior of
is very similar
to , however
- actual execution of a the service
+ actual execution of the service
binary is delayed until all jobs are
dispatched. This may be used to avoid
interleaving of output of shell
@@ -245,7 +254,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
@@ -255,7 +264,7 @@
guessing algorithm might come to
incorrect conclusions if a daemon
consists of more than one process. If
- the main PID cannot be determined
+ the main PID cannot be determined,
failure detection and automatic
restarting of a service will not work
reliably. Defaults to
@@ -283,7 +292,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
@@ -296,21 +305,119 @@
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. For each of the
+ specified commands, the first argument
+ must be an absolute and literal path
+ to an executable.
+
+ 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.
+ 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.
+ 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.
+
+ Each command line is split on
+ whitespace, with the first item being
+ the command to execute, and the
+ subsequent items being the arguments.
+ Double quotes ("...") and single
+ quotes ('...') may be used, in which
+ case everything until the next
+ matching quote becomes part of the
+ same argument. Quotes themselves are
+ removed after parsing. In addition, a
+ trailing backslash
+ (\) may be used to
+ merge lines. This syntax is intended
+ to be very similar to shell syntax,
+ but only the meta-characters and
+ expansions described in the following
+ paragraphs are understood.
+ Specifically, redirection using
+ <,
+ <<,
+ >, and
+ >>, pipes
+ using |, and
+ running programs in the background
+ using &
+ and other elements of shell
+ syntax are not supported.
+
+
+ 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
+ described in
+ systemd.unit5.
+ Note that the first argument of the
+ command line (i.e. the program to
+ execute) may not include
+ specifiers.
+
+ Basic environment variable
+ substitution is supported. Use
+ ${FOO} as part of a
+ 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
+ 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 at
+ whitespace, resulting in zero or more
+ arguments. To pass a literal dollar
+ sign, use $$.
+ Variables whose value is not known at
+ expansion time are treated as empty
+ strings. Note that the first argument
+ (i.e. the program to execute) may not
+ be a variable.
+
+ Variables to be used in this
+ fashion may be defined through
+ Environment= and
+ EnvironmentFile=.
+ In addition, variables listed in
+ section "Environment variables in
+ spawned processes" in
+ systemd.exec5
+ which are considered "static
+ configuration" may used (this includes
+ e.g. $USER, but not
+ $TERM).Optionally, if the absolute file
name is prefixed with
@@ -319,60 +426,61 @@
argv[0] to the
executed process, followed by the
further arguments specified. If the
- first token is prefixed with
- - an exit code of
+ 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 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.
+ @ 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
+ 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.
-
+ of some kind. Example:
+ ExecStart=/bin/sh -c 'dmesg | tac'
+
+
+ Example:
+ ExecStart=/bin/echo one ; /bin/echo "two two"
+
+ This will execute
+ /bin/echo two
+ times, each time with one argument,
+ one and
+ two two,
+ respectively. Since two commands are
+ specified,
+ Type=oneshot must
+ be used.
+
+ Example:
+ ExecStart=/bin/echo / >/dev/null & \; \
+/bin/ls
+
+ This will execute
+ /bin/echo with five
+ arguments: /,
+ >/dev/null,
+ &,
+ ;, and
+ /bin/ls.
+
+ Example:
+ Environment="ONE=one" 'TWO=two two'
+ExecStart=/bin/echo $ONE $TWO ${TWO}
+
+ This will execute
+ /bin/echo with four
+ arguments: one,
+ two,
+ two, and
+ two two.
+
@@ -381,24 +489,18 @@
Additional commands
that are executed before or after
the command in
- ExecStart=, respectively. 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.
+
@@ -407,20 +509,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
- additional special environment
- variables is set: if known
- $MAINPID is set to
+ 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.
+ following:
+
+ /bin/kill -HUP $MAINPID
+
@@ -429,9 +534,8 @@
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
@@ -440,12 +544,12 @@
KillMode= setting
(see
systemd.kill5). If
- this option is not specified the
+ 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
+ $MAINPID, see
above).
@@ -453,13 +557,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 does not 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
@@ -490,9 +596,10 @@
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
+ logic. Defaults to TimeoutStartSec= from the
+ manager configuration file, except when
Type=oneshot is
- used in which case the timeout
+ used, in which case the timeout
is disabled by default.
@@ -503,15 +610,16 @@
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
+ forcibly via SIGTERM, and after
another delay of this time with
- SIGKILL (See
+ 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 90s.
+ logic. Defaults to TimeoutStartSec= from the
+ manager configuration file.
@@ -527,18 +635,18 @@
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" (i.e. the
"keep-alive ping"). If the time
between two such calls is larger than
- the configured time then the service
+ the configured time, then the service
is placed in a failure state. By
setting Restart= to
or
- the service
+ , the service
will be automatically restarted. The
time configured here will be passed to
the executed service process in the
@@ -547,7 +655,7 @@
daemons to automatically enable the
keep-alive pinging logic if watchdog
support is enabled for the service. If
- this option is used
+ this option is used,
NotifyAccess= (see
below) should be set to open access to
the notification socket provided by
@@ -562,37 +670,71 @@
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
- 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
+ (the default), the
+ service will not be restarted. If set to
+ , it will be
+ 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 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
+ 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 only if the watchdog
+ timeout for the service expires.
+ If set to
+ , the service
+ will be restarted regardless of whether
it exited cleanly or not, got
terminated abnormally by a signal or
- hit a timeout.
+ 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).
@@ -602,17 +744,34 @@
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
+ 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 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.
+ codes or termination signal names,
+ separated by spaces. For example:
+ SuccessExitStatus=1 2 8 SIGKILL
+ ensures that exit codes 1, 2, 8 and
+ the termination signal
+ SIGKILL are
+ considered clean service terminations.
+
+
+ Note that if a process has a
+ signal handler installed and exits by
+ calling
+ _exit2
+ in response to a signal, the
+ information about the signal is lost.
+ Programs should instead perform cleanup and kill themselves with the same signal instead. See
+ Proper handling of SIGINT/SIGQUIT â How to be a proper program.
+
+ 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.
@@ -631,11 +790,18 @@
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.
+ 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.
@@ -710,23 +876,23 @@
(the default),
or
. If
- no daemon status
+ , no daemon status
updates are accepted from the service
processes, all status update messages
- are ignored. If
+ are ignored. If ,
only service updates sent from the
main process of the service are
- accepted. If all
+ accepted. If , all
services updates from all members of
the service's control group are
accepted. This option should be set to
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
+ NotifyAccess= is not
+ configured, it will be implicitly set
to
.
@@ -749,13 +915,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.
+ does not 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.
@@ -763,20 +938,23 @@
StartLimitBurst=Configure service
- start rate limiting. By default
+ 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
+ these two options, this rate limiting
may be modified. Use
StartLimitInterval=
- to configure the checking interval
- (defaults to 10s, set to 0 to disable
+ to configure the checking interval (defaults to
+ DefaultStartLimitInterval= in
+ manager configuration file, 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
+ are allowed (defaults to
+ DefaultStartLimitBurst= in
+ manager configuration file). These
configuration options are particularly
useful in conjunction with
Restart=, however
@@ -856,7 +1034,7 @@
for compatibility reasons and should not be used in
newly written service files.
-
+ SysVStartPriority=Set the SysV start
@@ -880,33 +1058,6 @@
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.
-
-
@@ -917,7 +1068,9 @@
systemctl8,
systemd.unit5,
systemd.exec5,
- systemd.kill5
+ systemd.resource-control5,
+ systemd.kill5,
+ systemd.directives7