X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=af32ccb87816b73810b1ce3c23aef32ecd53d76d;hb=3eb94c9e9e25586fa8ac93545810b87ce9241363;hp=94e72df9b47a48cbc09ceb18e78317b311e79bd4;hpb=494a66821815e8109afa136bd42818b85da38c09;p=elogind.git
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 94e72df9b..af32ccb87 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -103,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
- incompatibilities see the Incompatibilities
with SysV document.
@@ -139,9 +139,11 @@
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
@@ -170,13 +172,13 @@
PIDFile= option, so
that systemd can identify the main
process of the daemon. systemd will
- proceed starting follow-up units as
- soon as the parent process
+ proceed with starting follow-up units
+ as soon as the parent process
exits.Behavior of
is similar
- to , however
+ to ; however,
it is expected that the process has to
exit before systemd starts follow-up
units. RemainAfterExit=
@@ -185,13 +187,13 @@
Behavior of
is similar to
- , however it is
+ ; 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
+ will proceed with starting follow-up
+ units after the D-Bus bus name has been
acquired. Service units with this
option configured implicitly gain
dependencies on the
@@ -202,12 +204,12 @@
Behavior of
is similar to
- , however it is
+ ; however, it is
expected that the daemon sends a
notification message via
sd_notify3
- or an equivalent call when it finished
- starting up. systemd will proceed
+ or an equivalent call when it has finished
+ starting up. systemd will proceed with
starting follow-up units after this
notification message has been sent. If
this option is used,
@@ -225,7 +227,7 @@
Behavior of
is very similar
- to , however
+ to ; however,
actual execution of the service
binary is delayed until all jobs are
dispatched. This may be used to avoid
@@ -258,7 +260,7 @@
is set and
is unset because for the other types
or with an explicitly configured PID
- file the main PID is always known. The
+ 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
@@ -290,14 +292,13 @@
BusName=Takes a D-Bus bus
- name, that this service is reachable
+ name that this service is reachable
as. This option is mandatory for
services where
Type= is set to
, but its use
- is otherwise recommended as well if
- the process takes a name on the D-Bus
- bus.
+ is otherwise recommended if the process
+ takes a name on the D-Bus bus.
@@ -316,7 +317,7 @@
Type=oneshot is
used, more than one command may be
specified. Multiple command lines may
- be concatenated in a single directive,
+ be concatenated in a single directive
by separating them with semicolons
(these semicolons must be passed as
separate words). Alternatively, this
@@ -360,12 +361,12 @@
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.
+ 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
@@ -385,21 +386,37 @@
Basic environment variable
substitution is supported. Use
${FOO} as part of a
- word, or as a 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
whitespace it contains, resulting in a
- single argument. Use
+ 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 zero or
- more arguments. To pass a literal dollar sign,
- use $$. Note that the first
- argument (i.e. the program to execute)
- may not be a variable.
+ 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 the
+ section "Environment variables in
+ spawned processes" in
+ systemd.exec5,
+ which are considered "static
+ configuration", may be used (this includes
+ e.g. $USER, but not
+ $TERM).Optionally, if the absolute file
name is prefixed with
@@ -424,31 +441,22 @@
be used, they need to be passed
explicitly to a shell implementation
of some kind. Example:
- ExecStart=/bin/sh -c 'dmesg | tac'
-
-
- Only select environment variables
- are set for executed commands. See
- systemd.exec5.
-
-
+ ExecStart=/bin/sh -c 'dmesg | tac'Example:
- ExecStart=/bin/echo one ; /bin/echo "two two"
-
+ ExecStart=/bin/echo one ; /bin/echo "two two"This will execute
/bin/echo two
- times, each time with one argument,
+ times, each time with one argument:
one and
two two,
- respectively. Since two commands are
- specified
+ respectively. Because two commands are
+ specified,
Type=oneshot must
be used.Example:ExecStart=/bin/echo / >/dev/null & \; \
-/bin/ls
-
+/bin/ls
This will execute
/bin/echo with five
arguments: /,
@@ -459,8 +467,7 @@
Example:Environment="ONE=one" 'TWO=two two'
-ExecStart=/bin/echo $ONE $TWO ${TWO}
-
+ExecStart=/bin/echo $ONE $TWO ${TWO}
This will execute
/bin/echo with four
arguments: one,
@@ -504,8 +511,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
here following the same scheme as for
ExecStart=.
- One additional special
- environment variables is set: if known
+ One additional, 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
@@ -524,15 +531,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
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
+ optional. After the commands configured
+ in this option are run, all processes
+ remaining for a service are
terminated according to the
KillMode= setting
(see
systemd.kill5). If
this option is not specified, the
- process is terminated right-away when
+ process is terminated immediately when
service stop is requested. Specifier
and environment variable substitution
is supported (including
@@ -578,14 +585,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
daemon service does not signal
start-up completion within the
configured time, the service will be
- considered failed and be shut down
- again.
+ considered failed and will be shut
+ down 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 TimeoutStartSec= from the
- manager configuration file, except when
- Type=oneshot is
+ 20s". Pass 0 to
+ disable the timeout logic. Defaults to
+ TimeoutStartSec= from
+ the manager configuration file, except
+ when Type=oneshot is
used, in which case the timeout
is disabled by default.
@@ -595,17 +603,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
TimeoutStopSec=Configures the time to
wait for stop. If a service is asked
- to stop but does not terminate in the
+ 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
+ forcibly via SIGTERM,
+ and after another timeout of equal duration
+ with 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 TimeoutStartSec= from the
+ 20s". Pass 0 to disable
+ the timeout logic. Defaults to
+ TimeoutStartSec= from the
manager configuration file.
@@ -626,11 +635,11 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
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
+ 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
+ is placed in a failed state. By
setting Restart= to
or
, the service
@@ -661,11 +670,11 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
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
+ process, but it may also be one of the
+ processes specified with
ExecStartPre=,
ExecStartPost=,
- ExecStopPre=,
+ ExecStop=,
ExecStopPost=, or
ExecReload=.
When the death of the process is a
@@ -690,12 +699,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
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
+ 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,
+ process exits with a non-zero exit code,
is terminated by a signal (including on
core dump), when an operation (such as
service reload) times out, and when the
@@ -714,7 +726,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
, the service
will be restarted regardless of whether
it exited cleanly or not, got
- terminated abnormally by a signal or
+ terminated abnormally by a signal, or
hit a timeout.In addition to the above settings,
@@ -732,21 +744,32 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
considered successful termination, in
addition to the normal successful exit
code 0 and the signals SIGHUP, SIGINT,
- SIGTERM and SIGPIPE. Exit status
+ 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
+ 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.
@@ -755,7 +778,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
Takes a list of exit
status definitions that when returned
by the main service process will
- prevent automatic service restarts
+ prevent automatic service restarts,
regardless of the restart setting
configured with
Restart=. Exit
@@ -763,19 +786,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
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
+ 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
+ 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
+ list is reset and all prior assignments
of this option will have no
effect.
@@ -783,20 +807,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
PermissionsStartOnly=Takes a boolean
- argument. If true, the permission
- related execution options as
+ argument. If true, the permission-related
+ execution options, as
configured with
User= and similar
options (see
systemd.exec5
- for more information) are only applied
+ for more information), are only applied
to the process started with
ExecStart=, and not
to the various other
ExecStartPre=,
ExecStartPost=,
ExecReload=,
- ExecStop=,
+ ExecStop=, and
ExecStopPost=
commands. If false, the setting is
applied to all configured commands the
@@ -807,19 +831,19 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
RootDirectoryStartOnly=Takes a boolean
- argument. If true, the root directory
+ argument. If true, the root directory,
as configured with the
RootDirectory=
option (see
systemd.exec5
- for more information) is only applied
+ for more information), is only applied
to the process started with
ExecStart=, and not
to the various other
ExecStartPre=,
ExecStartPost=,
ExecReload=,
- ExecStop=,
+ ExecStop=, and
ExecStopPost=
commands. If false, the setting is
applied to all configured commands the
@@ -829,12 +853,14 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
NonBlocking=
- Set O_NONBLOCK flag
+ Set the
+ O_NONBLOCK flag
for all file descriptors passed via
socket-based activation. If true, all
file descriptors >= 3 (i.e. all except
- STDIN/STDOUT/STDERR) will have
- the O_NONBLOCK flag set and hence are in
+ stdin, stdout, and stderr) will have
+ the O_NONBLOCK flag
+ set and hence are in
non-blocking mode. This option is only
useful in conjunction with a socket
unit, as described in
@@ -890,8 +916,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
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
+ traffic than that which inherits the
+ sockets. Or in other words: the
Service= setting of
.socket units
does not have to match the inverse of
@@ -904,7 +930,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
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
+ sockets is reset, and all prior uses of
this setting will have no
effect.
@@ -915,10 +941,10 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
Configure service
start rate limiting. By default,
- services which are started more often
- than 5 times within 10s are not
+ services which are started more
+ than 5 times within 10 seconds are not
permitted to start any more times
- until the 10s interval ends. With
+ until the 10 second interval ends. With
these two options, this rate limiting
may be modified. Use
StartLimitInterval=
@@ -933,18 +959,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
manager configuration file). These
configuration options are particularly
useful in conjunction with
- Restart=, however
- apply to all kinds of starts
+ Restart=; however,
+ they 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
+ 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
@@ -968,18 +994,17 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
hit. Takes one of
,
,
- or
+ , or
. If
is set,
hitting the rate limit will trigger no
action besides that the start will not
- be
- permitted.
+ be permitted.
causes a reboot following the normal
shutdown procedure (i.e. equivalent to
- systemctl reboot),
+ systemctl reboot).
causes
- an forced reboot which will terminate
+ a forced reboot which will terminate
all processes forcibly but should
cause no dirty file systems on reboot
(i.e. equivalent to systemctl
@@ -988,10 +1013,34 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
causes immediate execution of the
reboot2
system call, which might result in
- data loss. Defaults to
+ data loss. Defaults to
.
+
+ RebootArgument=
+ Configure the optional
+ argument for the
+ reboot2
+ system call if
+ StartLimitAction=
+ is a reboot action. This works just
+ like the optional argument to
+ systemctl reboot
+ command.
+
+
+
+ FailureAction=
+ Configure the action
+ to take when the service enters a failed
+ state. Takes the same values as
+ StartLimitAction=
+ and executes the same actions.
+ Defaults to .
+
+
+
Check
@@ -1018,22 +1067,21 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}
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
+ 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
+ script headers. As such, it should only
+ be used as a temporary compatibility
+ option and should 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
+ instead. For more details, see
+ systemd.unit5.
+ If used, pass an integer value in the
range 0-99.
-