Create And Apply Custom systemd Service Templates

A systemd service template lets one unit definition manage several related processes. Instead of creating separate files for worker-a, worker-b, and worker-c, you create one template and start it with different instance names.

This approach is useful for application workers, VPN connections, queue consumers, and per-customer services. It works well on RHEL, CentOS Stream, Fedora, and other distributions that use systemd as the service manager.

The template filename contains an @ before the .service suffix, such as worker@.service. The value supplied after @ becomes the instance identifier, which systemd exposes through specifiers such as %i.

Administrators running workloads in an Australian cloud region can use the same pattern across Sydney, Melbourne, or Perth hosts. The unit remains portable while configuration files, firewall rules, and time-zone settings stay specific to each server.

Understand Template Unit Naming

Create a template under /etc/systemd/system/ so that it takes precedence over a vendor-supplied unit. For example, /etc/systemd/system/queue-worker@.service can represent any queue worker instance.

The %i placeholder contains the unescaped instance name. %I provides the unescaped form, while %n expands to the complete unit name. For ordinary names such as orders or reports, %i is generally sufficient.

A template can be started with systemctl start queue-worker@orders.service. Systemd then loads the template, substitutes orders, and treats the result as a distinct unit from queue-worker@reports.service.

Prepare The Application And User

Create a dedicated service account rather than running an application as root. On Fedora or RHEL-based systems, useradd --system --home-dir /opt/queue-worker --shell /sbin/nologin queueworker creates a restricted account. Store application files in /opt/queue-worker and configuration in /etc/queue-worker/.

A simple per-instance layout might contain /etc/queue-worker/orders.conf and /etc/queue-worker/reports.conf. Ensure ownership and permissions prevent ordinary users from reading credentials: chown -R root:queueworker /etc/queue-worker followed by chmod 750 /etc/queue-worker.

For a machine in the Sydney region, confirm that the application handles AEST and AEDT correctly. Systemd timers and log timestamps use the host's configured time zone, so keeping servers on UTC is often safer for distributed systems.

Write The Service Template

Create the unit with sudo vi /etc/systemd/system/queue-worker@.service:

[Unit]
Description=Queue worker instance %i
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=queueworker
Group=queueworker
WorkingDirectory=/opt/queue-worker
EnvironmentFile=-/etc/queue-worker/%i.env
ExecStart=/opt/queue-worker/bin/worker --config /etc/queue-worker/%i.conf
Restart=on-failure
RestartSec= five
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Replace RestartSec= five with RestartSec=5; systemd values cannot contain that extra word. The EnvironmentFile=- prefix makes the file optional, while ExecStart selects a configuration file matching the instance name. On a production server, add resource limits such as LimitNOFILE=65536 when the application requires many open connections.

Load And Test Each Instance

After saving the file, run sudo systemctl daemon-reload. This refreshes systemd's unit cache; it does not start anything. Test one instance with sudo systemctl start queue-worker@orders.service, then inspect it using systemctl status queue-worker@orders.service --no-pager.

The journal is usually the fastest diagnostic tool. Run sudo journalctl -u queue-worker@orders.service -f to follow live output, or add --since today to review the current day's messages. If the process exits immediately, check the executable path, permissions, environment file, and configuration syntax.

For administrators working from a dark terminal on a Melbourne laptop, readable logs and consistent colour settings can make long troubleshooting sessions easier; a related dark theme guide explains the broader DayNight approach.

Enable Instances At Boot

Starting a service manually does not make it persistent. Enable the required instance with sudo systemctl enable queue-worker@orders.service, or combine enablement and startup using sudo systemctl enable --now queue-worker@orders.service.

Each instance has its own state, so orders can be active while reports is disabled or failed. List matching units with systemctl list-units 'queue-worker@*.service' --all. Avoid enabling every possible name unless you have a clear provisioning process.

If a unit depends on a mounted data directory, add a mount dependency or use RequiresMountsFor=/srv/queue-data/%i. This helps prevent workers from starting before an Australian office's attached storage or remote mount is ready after a reboot.

Connect Templates To Nginx

Templates are useful behind Nginx when each application instance listens on a predictable local port. For example, queue-worker@orders.service could bind to 127.0.0.1:8101, while reports uses 127.0.0.1:8102. Nginx can then route requests by hostname or URL path.

Keep public exposure at the reverse proxy and bind workers to loopback where possible. The web server category contains related Nginx administration material, including configuration and service-management practices.

When deploying in a Sydney or Melbourne data centre, allow for health checks, TLS termination, and Australian traffic patterns. A failed worker should return a clear upstream error rather than leave Nginx waiting indefinitely, so configure sensible application timeouts and use Restart=on-failure.

Secure, Inspect, And Remove Instances

Validate a unit before enabling it with systemd-analyze verify /etc/systemd/system/queue-worker@.service. Check the rendered settings with systemctl cat queue-worker@orders.service and systemctl show queue-worker@orders.service. These commands often reveal spelling errors and unexpected defaults.

Stop and disable an instance with sudo systemctl disable --now queue-worker@orders.service. Removing the template does not remove its logs or application data. Preserve logs required for audits, particularly when services handle customer records or business systems governed by Australian privacy obligations.

For disaster recovery, keep the unit file and instance configuration in version control. If a server must be rebuilt from a rescue environment, a terminal-based bootable USB guide can help prepare installation or recovery media.

A systemd template is simply a reusable contract between an instance name, its configuration, and its process. Remember to use %i consistently, reload systemd after edits, test each instance, and enable only the workers that should run at boot.