Skip to content

Unit Files

Scope: the small INI-style files that describe units — where they live, how they're structured, and the one behavior (unknown keys are ignored) that bites everyone.

Where units live

Location Belongs to
/usr/lib/systemd/system/ The distribution's units. Don't edit.
/etc/systemd/system/ Yours. Units you install and override with.
~/.config/systemd/user/ Your per-user units (see the user-services chapter)

Same name in /etc beats the one in /usr/lib — that's how you override a shipped unit without editing it (and systemctl edit builds overrides as drop-in files under /etc/systemd/system/<unit>.d/).

After adding or changing any unit file:

sudo systemctl daemon-reload

Forget this and systemd keeps using the old version — the single most common cause of "I edited the file and nothing changed." The Troubleshooting chapter starts there for a reason.

The anatomy

This guide's demo unit, examples/mere-demo.service:

[Unit]
Description=Mere Mortals demo heartbeat service
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/mere-demo.sh
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target

Three sections, three jobs:

  • [Unit] — identity and relationships. Description is the human label shown in status. After= is ordering: start this after the network target is reached. (Ordering is not requiring — chapter 7.)
  • [Service] — how to run it. ExecStart is the command, with an absolute path (systemd has no PATH-guessing patience for the main command). Type says how systemd knows it started; Restart says what to do when it dies. Both get a chapter.
  • [Install] — what "enabled" means for this unit. WantedBy=multi-user.target is the standard line: when the system reaches normal multi-user operation, this unit is wanted. systemctl enable reads this section to know which symlink to create — a unit with no [Install] section can't be enabled, only started by hand.

Check before you run

systemd-analyze verify /etc/systemd/system/mere-demo.service

Silence means the file parses and its references resolve. Problems print with line numbers — from the lab, a unit with two misspelled keys:

/etc/systemd/system/mere-broken.service:6: Unknown key name 'BogusDirective' in section 'Service', ignoring.
/etc/systemd/system/mere-broken.service:7: Unknown key name 'Typee' in section 'Service', ignoring.

Learn the lesson in those lines: unknown keys are ignored, not errors. Typee=simple doesn't fail the unit — it quietly drops your setting and the unit runs with the default (Type=simple happens to be the default; a typo'd Restartt=always would silently mean "no restart policy at all"). Verify, and read status output with a detective's eye when behavior surprises you.