Mastering systemd Multi-Instance Services: Configuration, Management, and Use Cases

1. What is a systemd multi‑instance service

systemd implements multi‑instance services through template units , whose filenames end with @ (e.g., [email protected]). The template resides in /usr/lib/systemd/system/ or /etc/systemd/system/. When instantiated, the part after @ becomes the instance name, allowing multiple independent services to share the same unit file.

1.1 Core characteristics

Dynamic instantiation : each instance can receive a different name and thus its own runtime environment.

Resource reuse : a single unit file serves many instances, reducing duplication.

Flexible parameterization : the instance name can be used inside the unit to load instance‑specific configuration.

2. Configuring and using multi‑instance services

2.1 Structure of a template unit

A template unit has the same sections as a regular service file – [Unit], [Service], and [Install] – but may contain placeholders that are replaced by the instance name.

Example [email protected] template:

[Unit]
Description=OpenVPN client instance %i
After=network.target

[Service]
ExecStart=/usr/sbin/openvpn --config /etc/openvpn/%i.conf

[Install]
WantedBy=multi-user.target

The placeholder %i is replaced by the instance name supplied at start‑up, allowing the same unit to launch different configuration files.

2.2 Creating and managing instances

Assume several OpenVPN client configuration files exist under /etc/openvpn/ (e.g., client1.conf, client2.conf). The following steps illustrate how to create, start, enable, check status, and stop these instances.

Start an instance :

systemctl start [email protected]
systemctl start [email protected]

Check status :

systemctl status [email protected]
systemctl status [email protected]

Enable at boot :

systemctl enable [email protected]
systemctl enable [email protected]

Stop or disable an instance :

systemctl stop [email protected]
systemctl disable [email protected]

2.3 Instance naming and parameter passing

The string after @ can be any meaningful identifier (e.g., client1, server1). systemd also supports the uppercase placeholder %I, which receives the raw instance name, while %i provides the name with any optional prefix stripped.

2.4 Log management

Each instance generates its own journal entries. Use journalctl -u [email protected] to view logs for a specific instance.

3. Typical application scenarios

Network services – running multiple independent OpenVPN clients or servers.

Container management – assigning a separate service unit to each container or VM.

Database services – hosting several database instances on the same host.

Parallel job management – handling parallel tasks with isolated service instances.

4. Advantages of multi‑instance services

Simplified management : no need to maintain separate unit files for each instance.

Enhanced flexibility : different instance names can pass distinct configurations or parameters.

Efficient resource reuse : a single unit file reduces duplication and eases centralized updates.

5. Conclusion

systemd’s multi‑instance capability provides a powerful, flexible mechanism for managing many similar services with a single template. By leveraging instance names and placeholders, administrators can dramatically improve scalability, reduce configuration overhead, and streamline operations for network services, databases, containers, and other use cases on modern Linux systems.