other versions
- wheezy 44-11+deb7u4
- wheezy-backports 204-14~bpo70+1
- jessie 215-17+deb8u7
- jessie-backports 230-7~bpo8+2
- testing 232-25
- unstable 232-25
- experimental 233-8
SYSTEMD.SERVICE(5) | systemd.service | SYSTEMD.SERVICE(5) |
NAME¶
systemd.service - systemd service configuration filesSYNOPSIS¶
systemd.serviceDESCRIPTION¶
A unit configuration file whose name ends in .service encodes information about a process controlled and supervised by systemd. This man page lists the configuration options specific to this unit type. See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. The service specific configuration options are configured in the [Service] section. Additional options are listed in systemd.exec(5), which define the execution environment the commands are executed in. Unless DefaultDependencies= is set to false, service units will implicitly have dependencies of type Requires= and After= on basic.target as well as dependencies of type Conflicts= and Before= on shutdown.target. These ensure that normal service units pull in basic system initialization, and are terminated cleanly prior to system shutdown. Only services involved with early boot or late system shutdown should disable this option. If a service is requested under a certain name but no unit configuration file is found, systemd looks for a SysV init script by the same name (with the .service suffix removed) and dynamically creates a service unit from that script. This is useful for compatibility with SysV.OPTIONS¶
Service files must include a [Service] section, which carries information about the service and the process it supervises. A number of options that may be used in this section are shared with other unit types. These options are documented in systemd.exec(5). The options specific to the [Service] section of service units are the following: Type=Configures the process start-up type for this
service unit. One of simple, forking, oneshot,
dbus, notify.
If set to simple (the default value) 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 should be installed before the daemon is started up
(e.g. sockets set up by systemd, via socket activation), as systemd will
immediately proceed starting follow-up units.
If set to forking 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 to run as the main daemon process. This
is the behaviour of traditional UNIX daemons. If this setting is used, it is
recommended to also use the PIDFile= option, so that systemd can
identify the main process of the daemon. systemd will proceed starting
follow-up units as soon as the parent process exits.
Behaviour of oneshot is similar to simple, 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.
Behaviour of dbus is similar to simple, however it is expected
that the daemon acquires a name on the D-Bus bus, as configured by
BusName=. systemd will proceed starting follow-up units after the D-Bus
bus name has been acquired. Service units with this option configured
implicitly gain dependencies on the dbus.socket unit.
Behaviour of notify is similar to simple, however it is expected
that the daemon sends a notification message via sd_notify(3) or an
equivalent call when it finished starting up. systemd will proceed starting
follow-up units after this notification message has been sent. 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 main.
RemainAfterExit=
Takes a boolean value that specifies whether
the service shall be considered active even when all its processes exited.
Defaults to no.
GuessMainPID=
Takes a boolean value that specifies whether
systemd should try to guess the main PID of a service should if it cannot be
determined reliably. This option is ignored unless Type=forking is set
and PIDFile= is unset because for the other types or with an explicitly
configured PID file the main PID is always known. The guessing algorithm might
come to incorrect conclusions if a daemon consists of more than one process.
If the main PID cannot be determined failure detection and automatic
restarting of a service will not work reliably. Defaults to yes.
PIDFile=
Takes an absolute file name pointing to the
PID file of this daemon. Use of this option is recommended for services where
Type= is set to forking. systemd will read the PID of the main
process of the daemon after start-up of the service. systemd will not write to
the file configured here.
BusName=
Takes a D-Bus bus name, where this service is
reachable as. This option is mandatory for services where Type= is set
to dbus, but its use is otherwise recommended as well if the process
takes a name on the D-Bus bus.
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 Type=oneshot is used in which
case more than one ExecStart= line is accepted which are then invoked
one by one, sequentially in the order they appear in the unit file.
Optionally, if the absolute file name is prefixed with @, the second token will
be passed as argv[0] to the executed process, followed by the further
arguments specified. If the first token is prefixed with - an exit code of the
command normally considered a failure (i.e. non-zero exit status or abnormal
exit due to signal) is ignored and considered success. If both - and @ are
used for the same command the former must precede the latter. Unless
Type=forking is set, the process started via this command line will be
considered the main process of the daemon. The command line accepts %
specifiers as described in systemd.unit(5).
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) 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.
ExecReload=
Commands to execute to trigger a configuration
reload in the service. This argument takes multiple command lines, following
the same scheme as pointed out for ExecStartPre= above. Use of this
setting is optional. Specifier and environment variable substitution is
supported here following the same scheme as for ExecStart=. One special
environment variable is set: if known $MAINPID is set to the main process of
the daemon, and may be used for command lines like the following: /bin/kill
-HUP $MAINPID.
ExecStop=
Commands to execute to stop the service
started via ExecStart=. This argument takes multiple command lines,
following the same scheme as pointed out for ExecStartPre= above. Use
of this setting is optional. All processes remaining for a service after the
commands configured in this option are run are terminated according to the
KillMode= setting (see below). If this option is not specified the
process is terminated right-away when service stop is requested. Specifier and
environment variable substitution is supported (including $MAINPID, see
above).
ExecStopPost=
Additional commands that are executed after
the service was stopped using the commands configured in ExecStop=.
This argument takes multiple command lines, following the same scheme as
pointed out for ExecStartPre. Use of these settings is optional.
Specifier and environment variable substitution is supported.
RestartSec=
Configures the time to sleep before restarting
a service (as configured with Restart=). Takes a unit-less value in
seconds, or a time span value such as "5min 20s". Defaults to
100ms.
TimeoutSec=
Configures the time to wait for start-up and
stop. 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 KillMode= below.) 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.
WatchdogSec=
Configures the watchdog timeout for a service.
This is activated when the start-up is completed. The service must call
sd_notify(3) 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 on-failure or
always 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
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 main. Defaults to 0, which disables this
feature.
Restart=
Configures whether the main service process
shall be restarted when it exits. Takes one of no, on-success,
on-failure, on-abort or always. If set to no (the
default) the service will not be restarted when it exits. If set to
on-success it will be restarted only when it exited cleanly, i.e.
terminated with an exit code of 0. If set to on-failure 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 on-abort it will be restarted
only if it exits due to reception of an uncaught signal. If set to
always the service will be restarted regardless whether it exited
cleanly or not, got terminated abnormally by a signal or hit a timeout.
PermissionsStartOnly=
Takes a boolean argument. If true, the
permission related execution options as configured with User= and
similar options (see systemd.exec(5) for more information) are only
applied to the process started with ExecStart=, and not to the various
other ExecStartPre=, ExecStartPost=, ExecReload=,
ExecStop=, ExecStopPost= commands. If false, the setting is
applied to all configured commands the same way. Defaults to false.
RootDirectoryStartOnly=
Takes a boolean argument. If true, the root
directory as configured with the RootDirectory= option (see
systemd.exec(5) for more information) is only applied to the process
started with ExecStart=, and not to the various other
ExecStartPre=, ExecStartPost=, ExecReload=,
ExecStop=, ExecStopPost= commands. If false, the setting is
applied to all configured commands the same way. Defaults to 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.unit(5). If used, pass an integer value in the range
0-99.
KillMode=
Specifies how processes of this service shall
be killed. One of control-group, process, none.
If set to control-group 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 process only
the main process itself is killed. If set to none 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 control-group.
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 kill(2) 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 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 non-blocking mode. This option is only useful in conjunction with
a socket unit, as described in systemd.socket(5). Defaults to
false.
NotifyAccess=
Controls access to the service status
notification socket, as accessible via the sd_notify(3) call. Takes one
of none (the default), main or all. If none no
daemon status updates are accepted from the service processes, all status
update messages are ignored. If main only service updates sent from the
main process of the service are accepted. If all 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 above). If those options are
used but NotifyAccess= not configured it will be implicitly set to
main.
Sockets=
Specifies the name of the socket units this
service shall inherit the sockets from when the service is started. Normally
it should not be necessary to use this setting as all sockets whose unit
shares the same name as the service (ignoring the different suffix of course)
are passed to the spawned process.
Note that the same socket may be passed to multiple processes at the same time.
Also note that a different service may be activated on incoming traffic than
inherits the sockets. Or in other words: The Service= setting of
.socket units doesn't have to match the inverse of the Sockets= setting
of the .service it refers to.
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.unit(5). If used,
pass an integer value in the same range as /etc/fstab's fs_passno column. See
fstab(5) for details.
StartLimitInterval=, StartLimitBurst=
Configure service start rate limiting. By
default services which are started more often than 5 times within 10s are not
permitted to start any more times until the 10s interval ends. With these two
options this rate limiting may be modified. Use StartLimitInterval= to
configure the checking interval (defaults to 10s, set to 0 to disable any kind
of rate limiting). Use StartLimitBurst= to configure how many starts
per interval are allowed (defaults to 5). These configuration options are
particularly useful in conjunction with Restart=.
StartLimitAction=
Configure the action to take if the rate limit
configured with StartLimitInterval= and StartLimitBurst= is hit.
Takes one of none, reboot, reboot-force or
reboot-immediate. If none is set, hitting the rate limit will
trigger no action besides that the start will not be permitted. reboot
causes a reboot following the normal shutdown procedure (i.e. equivalent to
systemctl reboot), reboot-force causes an forced reboot which
will terminate all processes forcibly but should cause no dirty file systems
on reboot (i.e. equivalent to systemctl reboot -f) and
reboot-immediate causes immediate execution of the reboot(2)
system call, which might result in data loss. Defaults to none.
SEE ALSO¶
AUTHOR¶
Lennart Poettering <lennart@poettering.net>Developer
10/07/2013 | systemd |