Systemd Unit Files: Crafting the Perfect Configuration

Table of Contents

1. Understanding Systemd Unit Files
2. Types of Unit Files
3. Anatomy of a Unit File
4. Key Directives and Sections
   • The [Unit] Section
   • The [Service] Section
   • The [Install] Section
5. Crafting Your First Unit File: A Practical Example
6. Advanced Configuration Techniques
   • Template Unit Files
   • Dependency Management with Targets
   • Security Hardening
7. Debugging and Validation
8. Best Practices
9. Conclusion
10. References

1. Understanding Systemd Unit Files

A unit file is a plaintext configuration file that tells systemd how to manage a “unit”—a resource systemd is responsible for. Units can be services, sockets, timers, mounts, or even targets (groups of units). Unit files dictate what a unit does, when it runs, and how it interacts with other units.

Where Are Unit Files Stored?

Systemd looks for unit files in three primary directories (processed in this order, with later directories overriding earlier ones):

• /usr/lib/systemd/system/: Default units provided by the OS or installed packages (e.g., sshd.service, nginx.service). Do not edit these directly—package updates may overwrite them.
• /etc/systemd/system/: Custom units created by the system administrator. This is where you should store your own configurations.
• /run/systemd/system/: Runtime-generated units (temporary, lost on reboot).

2. Types of Unit Files

Systemd supports dozens of unit types, each with a specific purpose. Here are the most common:

3. Anatomy of a Unit File

Unit files are structured into sections, each marked by [SectionName], and contain directives (key-value pairs) that configure behavior. For service units (.service), the most critical sections are:

• [Unit]: Metadata and dependencies (e.g., “start after networking”).
• [Service]: Execution details (e.g., how to start/stop the service, user to run as).
• [Install]: Installation targets (e.g., “enable this service when booting into multi-user mode”).

4. Key Directives and Sections

Let’s dissect each section and its most important directives.

The [Unit] Section

This section defines metadata and inter-unit relationships.

The [Service] Section

This section is unique to .service units and controls how the service runs.

Service Type

The Type directive defines how systemd interacts with the service process. Choose carefully:

• simple (default): Service runs in the foreground. Systemd considers it started immediately after ExecStart.
  • Use for apps that don’t fork (e.g., node app.js).
• forking: Service forks a child process and exits. Systemd waits for the parent to exit.
  • Use for traditional daemons (e.g., sshd).
• oneshot: Runs once and exits. Systemd waits for it to finish (use with RemainAfterExit=yes to keep it “active”).
  • Use for scripts (e.g., backup.service).
• notify: Service sends a signal to systemd when ready (via sd_notify()).
  • Use for apps that need to report readiness (e.g., systemd-notify --ready).
• dbus: Service acquires a D-Bus name; systemd waits for this.
  • Use for D-Bus services (e.g., org.freedesktop.NetworkManager).

Execution Directives

These define how to start, stop, or reload the service:

• ExecStart=/path/to/command [args]: Primary command to start the service.
  • Example: ExecStart=/usr/bin/python3 /opt/myapp/app.py
• ExecStartPre=/path/to/script: Command to run before ExecStart.
  • Example: ExecStartPre=/bin/mkdir -p /var/log/myapp
• ExecStartPost=/path/to/script: Command to run after ExecStart.
• ExecReload=/path/to/script: Command to reload configuration (e.g., nginx -s reload).
• ExecStop=/path/to/script: Command to stop the service.
• ExecStopPost=/path/to/script: Command to run after the service stops (e.g., cleanups).

Lifecycle and Restart

• Restart: When to restart the service if it exits. Common values:
  • no (default): Never restart.
  • on-success: Restart only if it exits with 0 (success).
  • on-failure: Restart if it exits with non-zero (error), signal, or timeout.
  • always: Restart regardless of exit status (use for critical services).
• RestartSec=seconds: Delay before restarting (default: 100ms).
  • Example: RestartSec=5 (wait 5s before restarting).

User, Group, and Environment

• User=username: Run the service as this user (never run as root unless necessary!).
• Group=groupname: Run as this group.
• WorkingDirectory=/path: Set the working directory for the service.
• Environment=KEY=VALUE: Set environment variables (single line).
  • Example: Environment=PORT=8080 DB_PATH=/data/db
• EnvironmentFile=/path/to/file: Load environment variables from a file (one per line: KEY=VALUE).

Logging and Output

• StandardOutput=file:/var/log/myapp.log: Redirect stdout to a file.
• StandardError=journal: Send stderr to the systemd journal (view with journalctl).

The [Install] Section

This section defines how the unit is “installed” (enabled) with systemctl enable.

5. Crafting Your First Unit File: A Practical Example

Let’s create a unit file for a simple Python web app. We’ll assume:

• The app is a Flask script at /opt/myapp/app.py.
• It runs on port 5000 and requires Python 3.

Step 1: Create the Unit File

Create /etc/systemd/system/myapp.service with the following content:

[Unit]
Description=My Flask Web Application
Documentation=https://example.com/myapp-docs
After=network.target  # Start after networking is ready

[Service]
Type=simple  # App runs in foreground (no forking)
User=appuser  # Dedicated user for security
Group=appuser  # Dedicated group
WorkingDirectory=/opt/myapp  # Where the app lives
Environment="FLASK_APP=app.py" "FLASK_ENV=production"  # Env vars
ExecStart=/usr/bin/python3 -m flask run --host=0.0.0.0 --port=5000  # Start command
Restart=on-failure  # Restart on errors
RestartSec=5  # Wait 5s before restarting
StandardOutput=journal  # Log stdout to journal
StandardError=journal+console  # Log stderr to journal and console

[Install]
WantedBy=multi-user.target  # Enable when booting to multi-user mode

Step 2: Enable and Start the Service

# Reload systemd to detect the new unit file
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable myapp.service

# Start the service immediately
sudo systemctl start myapp.service

# Check status
sudo systemctl status myapp.service

Step 3: Verify and Debug

• Check logs: journalctl -u myapp.service -f ( -f follows live logs).
• Restart the service: sudo systemctl restart myapp.service.
• Disable on boot: sudo systemctl disable myapp.service.

6. Advanced Configuration Techniques

Template Unit Files

For services that need multiple instances (e.g., multiple websites), use template units with @ in the filename (e.g., [email protected]). The %i placeholder replaces the instance name.

Example template (/etc/systemd/system/[email protected]):

[Unit]
Description=App Instance %i

[Service]
Type=simple
User=appuser
WorkingDirectory=/opt/apps/%i  # %i = instance name (e.g., "site1")
ExecStart=/usr/bin/python3 app.py --port=%i  # Port from instance name
Restart=on-failure

[Install]
WantedBy=multi-user.target

Start an instance for port 8080:

sudo systemctl start [email protected]

Dependency Management with Targets

Targets group units to define system states. Use WantedBy=multi-user.target (CLI) or graphical.target (GUI) for most services. To create custom targets, define a .target file and use Requires/Wants to include units.

Security Hardening

Lock down services with these directives in [Service]:

• PrivateTmp=yes: Isolate /tmp for the service (prevents tampering with global /tmp).
• ProtectSystem=full: Make /usr read-only; only /var is writable.
• ReadWritePaths=/opt/myapp/data: Allow writes only to specific paths.
• NoNewPrivileges=yes: Prevent the service from gaining new privileges (e.g., via setuid).
• CapabilityBoundingSet=CAP_NET_BIND_SERVICE: Limit Linux capabilities (e.g., only allow binding to low ports).

7. Debugging and Validation

Even small mistakes (e.g., typos in ExecStart) can break a unit file. Use these tools:

• Validate syntax: sudo systemd-analyze verify myapp.service.
• Check status: sudo systemctl status myapp.service (shows errors like “failed to start”).
• View logs: journalctl -u myapp.service --since "5 minutes ago".
• Check dependencies: systemctl list-dependencies myapp.service.
• Profile startup: systemd-analyze blame (shows which units slow down boot).

8. Best Practices

1. Avoid root: Run services as non-root users with minimal privileges.
2. Use /etc/systemd/system/: Store custom units here (never edit /usr/lib/).
3. Prefer Wants over Requires: Soft dependencies make services more resilient.
4. Document: Add Description and Documentation directives for clarity.
5. Test restart behavior: Ensure Restart=on-failure works as expected for crashes.
6. Harden security: Use PrivateTmp, ProtectSystem, and NoNewPrivileges.

9. Conclusion

Systemd unit files are the backbone of service management in modern Linux. By mastering their structure, directives, and best practices, you can create reliable, secure, and maintainable services. Start with simple .service files, experiment with advanced features like templates and timers, and always validate and test your configurations.

10. References

• systemd.unit(5) Man Page
• systemd.service(5) Man Page
• Systemd Documentation (Freedesktop)
• Red Hat Systemd Guide
• DigitalOcean: Understanding Systemd Units and Services