Chapter 1. Working with systemd unit files

To manage units and their resources, you can use unit files. Several systemctl commands work with unit files in the background. A unit file is the .service or .target file on your hard drive that has configuration directives to describe the unit and define its properties.

The basic object that systemd manages is a systemd unit, a representation of system resources and services. A systemd unit consists of a name, type and a configuration file that defines and manages a particular task. You can use unit files to configure system behavior. Examples of various systemd unit types are as follows:

You can edit or create unit files manually. Three main directories contain unit files on the system:

The /etc/systemd/system/ directory is reserved for unit files created or customized by a system administrator.

Unit file naming convention is as follows:

<unit_name>.<type_extension>

In this example, <unit_name> stands for the name of the unit and <type_extension> identifies the unit type. For example, you can find sshd.service and sshd.socket units present on your system.

For additional configurations, you can use systemd drop-in files.

The system uses systemd to manage the sshd.service dependencies through the directories /etc/systemd/system/sshd.service.wants/ and /etc/systemd/system/sshd.service.requires/. These directories are for symlinks to other services that the SSH daemon needs or wants to start. While systemd does not create these directories directly, you can use the systemctl enable <service> command to automatically add the necessary links. systemd creates the symbolic links automatically either during installation according to the [Install] section options or at runtime based on the [Unit] section options from the unit file.

With unit specifiers, you can set many unit file options. These are wildcard strings that are dynamically replaced with unit parameters when the unit file is loaded. This enables creation of unit files that serve as templates for generating instantiated units. See Working with instantiated units.

You can find the unit configuration files in the mentioned directories.

The default configuration of systemd is defined during the compilation and you can find the configuration in the /etc/systemd/system.conf file. By editing this file, you can modify the default configuration by overriding values for systemd units globally.

For example, to override the default value of the timeout limit, which is set to 90 seconds, use the DefaultTimeoutStartSec parameter to input the required value in seconds:

DefaultTimeoutStartSec=_required value_

Unit files consist of three main sections that define unit behavior, type-specific directives, and installation information. Understanding this structure helps you to create and change systemd units effectively.

The [Unit] section has generic options that are not dependent on the type of the unit. These options have a unit description, specify the unit’s behavior, and set dependencies to other units.

To manage configuration parameters that define how the service operates and interacts with the system, use the [Service] section. Each systemd service unit has a [Service] section that includes directives for this unit type.

The [Install] section has information about unit installation used by systemctl enable and disable commands.

To modify properties of an existing unit or create a new unit from scratch, you need to create custom unit files.

There are several use cases for creating unit files from scratch: you could run a custom daemon or create a second instance of some existing service as in Creating a custom unit file by using the second instance of the sshd service

However, to modify or extend the properties of an existing unit, use the instructions from Modifying existing unit files.

To configure and run multiple instances of a service, you can create copies of the original service configuration files. Then, modify certain parameters to avoid conflicts with the primary instance of the service.

To discover the service descriptions and dependencies, you can use the systemctl show <example_service_name> command. You can also list the dependencies by using the systemctl list-dependencies <example_service_name> command.

To find the description of the service, you can use the line starting with #description. Use this description together with the service name in the Description option in the [Unit] section of the unit file. The header might contain similar data on the #Short-Description and #Description lines.

To find the dependencies of the service, you can use the Linux standard base (LSB) header. It might contain several directives that form dependencies between services.

# grep -i "Required-Start\|Required-Stop\|Default-Start\|Default-Stop" /etc/init.d/<example_service_name>

Most of them are translatable to systemd unit options, see the following table:

To decide the default systemd targets in which a service should start, check for lines such as #chkconfig or #Default-Start in the service script or Linux Standard Base (LSB) header.

The runlevels correspond to default systemd targets. In systemd, runlevels 2, 3, and 5 map to multi-user.target and graphical.target, while runlevel 4 maps to a custom or user defined target. Specify these targets in the WantedBy option in the [Install] section of your unit file to control when the service starts by default. Because graphical.target depends on multi-user.target, you can also specify only graphical.target for services meant to run in a graphical environment. Also, examine #Default-Stop to identify targets to stop the service by default. The other two values specified on the #chkconfig line represent startup and shutdown priorities of the init script. These values are interpreted by systemd if it loads the init script, but there is no unit file equivalent.

You need to review the init script or systemd unit file to find files used by a service. Look for references of configuration files, environment files, PID files, and executables in the init script or systemd unit file.

The init script header does not include the path to the executable program and other dependent files required by the service. In previous versions of Red Hat Enterprise Linux, init scripts used a Bash case statement to define the behavior of the service on default actions, such as start, stop, or restart, and custom-defined actions. The following excerpt from the example_service init script shows the block of code executed at service start.

conf_check() {
    [ -x /usr/sbin/myservice ] || exit 5
    [ -d /etc/myservice ] || exit 6
    [ -d /var/spool/myservice ] || exit 5
}

make_aliasesdb() {
	if [ "$(/usr/sbin/postconf -h alias_database)" == "hash:/etc/aliases" ]
	then
		# /etc/aliases.db might be used by other MTA, make sure nothing
		# has touched it since our last newaliases call
		[ /etc/aliases -nt /etc/aliases.db ] ||
			[ "$ALIASESDB_STAMP" -nt /etc/aliases.db ] ||
			[ "$ALIASESDB_STAMP" -ot /etc/aliases.db ] || return
		/usr/bin/newaliases
		touch -r /etc/aliases.db "$ALIASESDB_STAMP"
	else
		/usr/bin/newaliases
	fi
}

start() {
	[ "$EUID" != "0" ] && exit 4
	# Check that networking is up.
	[ ${NETWORKING} = "no" ] && exit 1
	conf_check
	# Start daemons.
	echo -n $"Starting myservice: "
	make_aliasesdb >/dev/null 2>&1
	[ -x $CHROOT_UPDATE ] && $CHROOT_UPDATE
	/usr/sbin/myservice start 2>/dev/null 1>&2 && success || failure $"$prog start"
	RETVAL=$?
	[ $RETVAL -eq 0 ] && touch $lockfile
        echo
	return $RETVAL
}

The extensibility of the init script allowed specifying two custom functions, conf_check() and make_aliasesdb() are called from the start() function block. Several external files and directories are mentioned: the /usr/sbin/myservice main executable program, the /etc/myservice/ and /var/spool/myservice/ configuration directories, and the /usr/sbin/postconf/ directory.

The systemd unit file supports only the predefined actions, but enables executing custom executables with ExecStart, ExecStartPre, ExecStartPost, ExecStop, and ExecReload options. The /usr/sbin/myservice together with supporting scripts are executed on service start.

Converting complex init scripts requires understanding the purpose of every statement in the script. Some of the statements are specific to the operating system version, therefore you do not need to convert them. However, some adjustments required for the new environment, both in the unit file and in the executable program and supporting files.

To customize and optimize services for your specific needs without creating a new configuration from scratch, you can modify an existing unit file. If you want to modify existing unit files, proceed to the /etc/systemd/system/ directory.

Do not modify the unit files in the /usr/lib/systemd/system/ directory.

To extend the default unit file with additional systemd configuration options, you can create a configuration directory in the /etc/systemd/system/ directory.

To make persistent changes to the unit file configuration after updating the package that provides the unit file, you can override the default unit configuration.

To prevent a malfunctioning service from freezing the system, you can specify a timeout value per service. Otherwise, the default value for timeout is 90 seconds for normal services and 300 seconds for SysV-compatible services.

To monitor overridden or modified unit files, you can use the systemd-delta command.

To manage multiple instances of a service, you can use a single template configuration. You can define a generic template, denoted by @, for a unit and generate multiple instances of that unit with specific parameters at runtime. By using Requires or Wants options or the systemctl start command, you can start instantiated units from another unit file.

<template_name>@<instance_name>.service

The <template_name> stands for the name of the template configuration file. Replace <instance_name> with the name for the unit instance. Several instances can point to the same template file with configuration options common for all instances of the unit. Template unit name has the form of:

<unit_name>@.service

For example, the following Wants setting in a unit file:

Wants=getty@ttyA.service getty@ttyB.service

With this command, systemd searches for given service units. If no such units are found, the part between @ and the type suffix is ignored and systemd searches for the getty@.service file, reads the configuration from it, and starts the services.

For example, the getty@.service template has the following directives:

[Unit]
Description=Getty on %I
...
[Service]
ExecStart=-/sbin/agetty --noclear %I $TERM
...

When the getty@ttyA.service and getty@ttyB.service are instantiated from the above template, Description=Getty on %I is resolved as Getty on ttyA and Getty on ttyB.

You can use the wildcard characters, called unit specifiers, in any unit configuration file. Unit specifiers substitute certain unit parameters and are interpreted at runtime.

For a complete list of unit specifiers, see the systemd.unit(5) man page on your system.