SystemD - Understanding the Unit File Structure (part 5)
We need understand the unite file structure. A unit configuration file encodes information about a service, a socket, a device, a mount point and more. Each unit file is a simple text file describing a unit, what it does, what needs to run before or afterward, and other details.
A unit configuration file encodes information about a service, a socket, a device, a mount point, an automount point, a swap file or partition, a start-up target, a watched file system path, a timer controlled and supervised by systemd(1), a resource management slice or a group of externally created processes.
The files that define how systemd will handle a unit can be found in many different locations, each of which have different priorities and implications.
/lib/systemd/system- The system's copy of unit files are generally kept in this directory. When software installs unit files on the system, this is the location where they are placed by default.
/run/systemd/system- Systemd unit files created at run time. This directory takes precedence over the directory with installed service unit files.
/etc/systemd/system/- If you wish to modify the way that a unit functions, the best location to do so is within this directory. Unit files found in this directory location take precedence over any of the other locations on the filesystem. If you need to modify the system's copy of a unit file, putting a replacement in this directory is the safest and most flexible way to do this.
Example of postfix.service unit file in debian stretch from
Description=Postfix Mail Transport Agent (instance %i)
ExecStart=/usr/sbin/postmulti -i %i -p start
ExecStop=/usr/sbin/postmulti -i %i -p stop
ExecReload=/usr/sbin/postmulti -i %i -p reload
Unit files typically consist of three section:
[Unit]— contains generic options that are not dependent on the type of the unit. These options provide unit description, specify the unit's behavior, and set dependencies to other units. For a list of most frequently used [Unit] options, see Important [Unit] section Options
[unit type]— if a unit has type-specific directives, these are grouped under a section named after the unit type. For example,
service unit files contain the [Service] section. See Important [Service] Section Options for most frequently used
[Install]— contains information about unit installation used by systemctl enable and disable commands. See Important [Install] Section Options for a list of
Description- A meaningful description of the unit. This text is displayed for example in the output of the systemctl status command.
Documentation- Provides a list of URIs referencing documentation for the unit.
Requires- Configures dependencies on other units. The units listed in
Requiresare activated together with the unit. If any of the required units fail to start, the unit is not activated. These units are started in parallel with the current unit by default.
Wants- Configures weaker dependencies than
Requires. If any of the listed units does not start successfully, it has no impact on the unit activation. This is the recommended way to establish custom unit dependencies.
Conflicts- Configures negative dependencies, an opposite to
Requires. This can be used to list units that cannot be run at the same time as the current unit. Starting a unit with this relationship will cause the other units to be stopped.
Before- The units listed in this directive will not be started until the current unit is marked as started if they are activated at the same time. This does not imply a dependency relationship and must be used in conjunction with one of the above directives if this is desired.
After(B) - Defines the order in which units are started. The unit starts only after the units specified in
Afterare active. Unlike
Afterdoes not explicitly activate the specified units. The
Beforeoption has the opposite functionality to
Condition- There are a number of directives that start with Condition which allow the administrator to test certain conditions prior to starting the unit. This can be used to provide a generic unit file that will only be run when on appropriate systems. If the condition is not met, the unit is gracefully skipped.
Asert- Similar to the directives that start with
Condition, these directives check for different aspects of the running environment to decide whether the unit should activate. However, unlike the
Conditiondirectives, a negative result causes a failure with this directive.
Type- Configures the unit process startup type that affects the functionality of
ExecStartand related options. One of:
simple– The default value. The process started with
ExecStartis the main process of the service.
forking– The process started with
ExecStartspawns a child process that becomes the main process of the service. The parent process exits when the startup is complete.
oneshot– This type is similar to
simple, but the process exits before starting consequent units.
dbus– This type is similar to
simple, but consequent units are started only after the main process gains a D-Bus name.
notify– This type is similar to
simple, but consequent units are started only after a notification message is sent via the
idle– similar to
simple, the actual execution of the service binary is delayed until all jobs are finished, which avoids mixing the status output with shell output of services.
ExecStart- Specifies commands or scripts to be executed when the unit is started.
ExecStartPostspecify custom commands to be executed before and after
Type=oneshotenables specifying multiple custom commands that are then executed sequentially.
ExecStop- Specifies commands or scripts to be executed when the unit is stopped.
ExecReload- Specifies commands or scripts to be executed when the unit is reloaded.
Restart- With this option enabled, the service is restarted after its process exits, with the exception of a clean stop by the
RemainAfterExit- If set to True, the service is considered active even when all its processes exited. Default value is False. This option is especially useful if
[Service] section, see the systemd.service(5)
Alias- Provides a space-separated list of additional names for the unit. Most systemctl commands, excluding systemctl enable , can use aliases instead of the actual unit name.
RequiredBy- A list of units that depend on the unit. When this unit is enabled, the units listed in
Requiredependency on the unit.
WantedBy- A list of units that weakly depend on the unit. When this unit is enabled, the units listed in
Wantdependency on the unit.
Also- Specifies a list of units to be installed or uninstalled along with the unit.
DefaultInstance- Limited to instantiated units, this option specifies the default instance for which the unit is enabled. See
Systemd has an
Environment directive which sets environment variables for executed processes. It takes a space-separated list of variable assignments. This option may be specified more than once in which case all listed variables will be set. If the same variable is set twice, the later setting will override the earlier setting. If the empty string is assigned to this option, the list of environment variables is reset, all prior assignments have no effect.
# Client Env Vars
# Peer Env Vars
EnvironmentFile similar to
Environment directive but reads the environment variables from a text file. The text file should contain new-line-separated variable assignments.
For example, in Container Linux, the coreos-metadata.service service creates /run/metadata/coreos. This environment file can be included by other services in order to inject dynamic configuration. Here's an example of the environment file when run on DigitalOcean (the IP addresses have been removed):
This environment file can then be sourced and its variables used. Here is an example drop-in for
etcd-member.service which starts
coreos-metadata.service and then uses the generated results:
Configures the time to sleep before restarting a service (as configured with
Restart below). Takes a unit-less value in seconds, or a time span value such as "5min 20s". Defaults to 100ms.
Configures whether the 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
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.
Restart directive one of this arguments:
no- If set to no (the default), the service will not be restarted.
on-sucess- If set to on-success, 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
on-failure- If set to on-failure, 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 aforementioned four signals), when an operation (such as service reload) times out, and when the configured watchdog timeout is triggered.
on-abnormal- If set to on-abnormal, 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.
on-abort- If set to on-abort, 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 on-watchdog, the service will be restarted only if the watchdog timeout for the service expires.
always- If set to always, 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
|Unclean exit code
As exceptions to the setting above, the service will not be restarted if the exit code or signal is specified in
RestartPreventExitStatus directive (see below) or the service is stopped with systemctl stop
or an equivalent operation. Also, the services will always be restarted if the exit code or signal is specified in
Note that service restart is subject to unit start rate limiting configured with
StartLimitBurst directives, see systemd.unit(5)
for details. A restarted service enters the failed state only after the start limits are reached.
on-failure 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),
on-abnormal is an alternative choice.
We have a
tsm.service unit file, that start and manage tivoli storage manager service.
Description=IBM Tivoli Storage Manager Client dsmcad systemd-style sample service description