X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=4c890dfb7bbff42672a66f4a00fbcf7f2baa2268;hb=d9000fd3b3ad0728832007f56e9cafacfbbe54e7;hp=233807d2b3313f6dc2a027051d96a964350a32b6;hpb=98709151f3e782eb508ba15e2a12c0b46003f061;p=elogind.git
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 233807d2b..4c890dfb7 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -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.resource-control5,
+ which configure resource control 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=
@@ -126,14 +139,17 @@
If set to
(the default
- value if BusName=
- is not specified) it is expected that
- the process configured with
+ if neither
+ Type= nor
+ BusName=, but
+ ExecStart= 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
@@ -141,44 +157,48 @@
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 behaviour of
+ process. This is the behavior of
traditional UNIX daemons. If this
setting is used, it is recommended to
also use the
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.
- Behaviour of
- is similar
- to , however
- it is expected that the process has to
+ Behavior of
+ is similar to
+ ; however, it
+ is expected that the process has to
exit before systemd starts follow-up
units. RemainAfterExit=
is particularly useful for this type
- of service.
+ of service. This is the implied
+ default if neither
+ Type= or
+ ExecStart= are
+ specified.
- Behaviour of
+ 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
@@ -187,29 +207,33 @@
BusName= is
specified.
- Behaviour of
+ 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
+ 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=.
- Behaviour of
+ Behavior of
is very similar
- to , however
- actual execution of a the service
+ 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
@@ -235,17 +259,17 @@
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
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
- 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
@@ -273,106 +297,139 @@
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
- , but its use
- is otherwise recommended as well if
- the process takes a name on the D-Bus
- bus.
+ .
+
+
+
+
+ BusPolicy=
+
+ If specified, a custom
+ kdbus
+ endpoint will be created and installed as the
+ default bus node for the service. Such a custom
+ endpoint can hold an own set of policy rules
+ that are enforced on top of the bus-wide ones.
+ The custom endpoint is named after the service
+ it was created for, and its node will be
+ bind-mounted over the default bus node
+ location, so the service can only access the
+ bus through its own endpoint. Note that custom
+ bus endpoints default to a 'deny all' policy.
+ Hence, if at least one
+ BusPolicy= directive is
+ given, you have to make sure to add explicit
+ rules for everything the service should be able
+ to do.
+ The value of this directive is comprised
+ of two parts; the bus name, and a verb to
+ specify to granted access, which is one of
+ ,
+ , or
+ .
+ implies
+ , and
+ implies both and
+ .
+ If multiple access levels are specified for the
+ same bus name, the most powerful one takes
+ effect.
+
+ Examples:
+ BusPolicy=org.freedesktop.systemd1 talk
+ BusPolicy=org.foo.bar see
+ This option is only available on kdbus enabled systems.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 value is split
+ into zero or more command lines is
+ according to the rules described below
+ (see section "Command Lines" below).
+
+
+ When Type is
+ not , only one
+ command may and must 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
+ used, zero or more commands may be
+ specified. This can be specified by
+ providing multiple command lines in
+ the same directive, or alternatively,
+ this directive may be specified more
+ than once with the same effect. 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 no
+ ExecStart= is
+ specified, then the service must have
+ RemainAfterExit=yes
+ set.
+
+ For each of the specified
+ commands, the first argument must be
+ an absolute path to an executable.
+ Optionally, if this 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
+ 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
+ abnormal exit due to signal) is
+ ignored and considered success. If
+ both - and
+ @ are used, they
+ can appear in either order.
+
+ If more than one command is
+ specified, the commands are invoked
+ 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.
+ main process of the daemon.
- 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.
+
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.
+
@@ -381,20 +438,37 @@
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 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
+
+ Note however that reloading a
+ daemon by sending a signal (as with
+ the example line above) is usually not
+ a good choice, because this is an
+ asynchronous operation and hence not
+ suitable to order reloads of multiple
+ services against each other. It is
+ strongly recommended to set
+ ExecReload= to a
+ command that not only triggers a
+ configuration reload of the daemon,
+ but also synchronously waits for it to
+ complete.
+
@@ -403,22 +477,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
+ optional. After the commands configured
+ in this option are run, all processes
+ remaining for a service 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 immediately when
+ service stop is requested. Specifier
+ and environment variable substitution
+ is supported (including
+ $MAINPID, see
above).
@@ -426,13 +500,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
@@ -452,56 +528,88 @@
- 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
- 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
- another delay of this time with
- SIGKILL. (See
+ configured time, the service will be
+ 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
+ DefaultTimeoutStartSec= from
+ the manager configuration file, except
+ when Type=oneshot is
+ used, in which case the timeout
+ is disabled by default
+ (see systemd-system.conf5).
+
+
+
+
+ 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 timeout of equal duration
+ with 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, except when Type=oneshot is
- used in which case the timeout
- is disabled by default.
+ 20s". Pass 0 to disable
+ the timeout logic. Defaults to
+ DefaultTimeoutStopSec= from the
+ manager configuration file
+ (see systemd-system.conf5).
+
+
+
+
+ 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
- the service
+ 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 failed state and it will
+ be terminated with SIGABRT.
+ 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
- this option is used
+ 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.
@@ -510,54 +618,272 @@
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 it may also be one of the
+ processes specified with
+ ExecStartPre=,
+ ExecStartPost=,
+ ExecStop=,
+ 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, 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.
+ (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 a non-zero exit
+ code, is terminated by a signal
+ (including on core dump, but excluding
+ the aforementiond four signals), 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 when the
+ process is terminated by a signal
+ (including on core dump, excluding the
+ aforementioned four signals), when an
+ operation times out, or when the
+ 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.
+
+
+ Exit causes and the effect of the Restart= settings on them
+
+
+
+
+
+
+ Restart settings/Exit causes
+
+
+
+
+
+
+
+
+
+
+
+ Clean exit code or signal
+
+ X
+ X
+
+
+
+
+
+
+ Unclean exit code
+
+ X
+
+ X
+
+
+
+
+
+ Unclean signal
+
+ X
+
+ X
+ X
+ X
+
+
+
+ Timeout
+
+ X
+
+ X
+ X
+
+
+
+
+ Watchdog
+
+ X
+
+ X
+ X
+
+ X
+
+
+
+
+
+ As exceptions to the setting
+ above the service will not be
+ restarted if the exit code or signal
+ is specified in
+ RestartPreventExitStatus=
+ (see below). Also, the services will
+ always be restarted if the exit code
+ or signal is specified in
+ RestartForceExitStatus=
+ (see below).
+
+ Setting this to
+ is the
+ recommended choice for long-running
+ services, in order to increase
+ reliability by attempting automatic
+ recovery from errors. For services
+ that shall be able to terminate on
+ their own choice (and avoid
+ immediate restarting),
+ is an
+ alternative choice.
+
+
+
+
+ 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. 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.
+
+
+
+ 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. For 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 and all prior assignments
+ of this option will have no
+ effect.
+
+
+
+ RestartForceExitStatus=
+ Takes a list of exit
+ status definitions that when returned
+ by the main service process will force
+ automatic service restarts, regardless
+ of the restart setting configured with
+ Restart=. The
+ argument format is similar to
+ RestartPreventExitStatus=.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
@@ -568,19 +894,19 @@
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
@@ -588,80 +914,16 @@
false.
-
- 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
+ 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
@@ -679,23 +941,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
.
@@ -704,27 +966,39 @@
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
+ inherit socket file descriptors
+ from when the service is
+ started. Normally it should not be
+ necessary to use this setting as all
+ socket file descriptors 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
+ (subject to the different unit name
+ suffix of course) are passed to the
+ spawned process.
+
+ Note that the same socket file
+ descriptors may be passed to multiple
+ processes simultaneously. Also note
+ that a different service may be
+ activated on incoming socket traffic
+ than the one which is ultimately
+ configured to inherit the socket file
+ descriptors. 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.
+ 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, and all prior uses of
+ this setting will have no
+ effect.
@@ -732,23 +1006,46 @@
StartLimitBurst=Configure service
- start rate limiting. By default
- services which are started more often
- than 5 times within 10s are not
+ start rate limiting. By default,
+ 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
- these two options this rate limiting
+ until the 10 second 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
+ 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=.
+ 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
+ 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.
@@ -763,102 +1060,313 @@
hit. Takes one of
,
,
- or
- . If
- is set,
- hitting the rate limit will trigger no
- action besides that the start will not
- be
+ ,
+ ,
+ ,
+ 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
+ systemctl reboot).
+ causes a
+ 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
+ data loss. Similar,
+ ,
+ ,
+
+ have the effect of powering down the
+ system with similar
+ semantics. Defaults to
.
-
-
-
-
- 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.
+
+ 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 .
+
+
-
- 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.
+ RebootArgument=
+ Configure the optional
+ argument for the
+ reboot2
+ system call if
+ StartLimitAction=
+ or FailureAction=
+ is a reboot action. This works just
+ like the optional argument to
+ systemctl reboot
+ command.
- 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.
+ FileDescriptorStoreMax=
+ Configure how many
+ file descriptors may be stored in the
+ service manager for the service using
+ sd_pid_notify_with_fds3's
+ FDSTORE=1
+ messages. This is useful for
+ implementing service restart schemes
+ where the state is serialized to
+ /run and the file
+ descriptors passed to the service
+ manager, to allow restarts without
+ losing state. Defaults to 0, i.e. no
+ file descriptors may be stored in the
+ service manager by default. All file
+ descriptors passed to the service
+ manager from a specific service are
+ passed back to the service's main
+ process on the next service
+ restart. Any file descriptors passed
+ to the service manager are
+ automatically closed when POLLHUP or
+ POLLERR is seen on them, or when the
+ service is fully stopped and no job
+ queued or being executed for
+ it.
+
+ Check
+ systemd.exec5
+ and
+ systemd.kill5
+ for more settings.
+
+
+
+
+ Command lines
+
+ This section describes command line parsing and
+ variable and specifier substitions for
+ ExecStart=,
+ ExecStartPre=,
+ ExecStartPost=,
+ ExecReload=,
+ ExecStop=, and
+ ExecStopPost= options.
+
+ Multiple command lines may be concatenated in a
+ single directive by separating them with semicolons
+ (these semicolons must be passed as separate words).
+ Lone semicolons may be escaped as
+ \;.
+
+ 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. C-style escapes are
+ also supported, see table below. Quotes themselves are
+ removed after parsing and escape sequences
+ substituted. 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
+ |, running programs in the
+ background using &, and
+ other elements of shell syntax are not
+ supported.
+
+ The command to execute must an absolute path
+ name. It may contain spaces, but control characters
+ are not allowed.
+
+ 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. For this type of
+ expansion, quotes and respected when splitting into
+ words, and afterwards removed.
+
+ 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.
+
+ Example:
+ Environment=ONE='one' "TWO='two two' too" THREE=
+ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
+ExecStart=/bin/echo $ONE $TWO $THREE
+ This results in echo being
+ called twice, the first time with arguments
+ 'one',
+ 'two two' too, ,
+ and the second time with arguments
+ one, two two,
+ too.
+
+
+ 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).
+
+ Note that shell command lines are not directly
+ supported. 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'
+
+ 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. Because 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.
+
+
+ C escapes supported in command lines and environment variables
+
+
+
+
+
+ Literal
+ Actual value
+
+
+
+
+ \a
+ bell
+
+
+ \b
+ backspace
+
+
+ \f
+ form feed
+
+
+ \n
+ newline
+
+
+ \r
+ carriage return
+
+
+ \t
+ tab
+
+
+ \v
+ vertical tab
+
+
+ \\
+ backslash
+
+
+ \"
+ double quotation mark
+
+
+ \'
+ single quotation mark
+
+
+ \s
+ space
+
+
+ \xxx
+ character number xx in hexadecimal encoding
+
+
+ \nnn
+ character number nnn in octal encoding
+
+
+
+