systemctl Commands

Most state-changing commands need sudo; reading status and listing units does not. Unit names can drop the .service suffix (systemctl status nginx and systemctl status nginx.service are the same).

Manage a Service

restart and reload differ: reload sends the service its reload signal (nginx re-reads its config with no dropped connections), restart kills and relaunches it. systemctl status exits non-zero when the service is not running, which trips up scripts that only wanted the output.

Enable and Disable

Enabling controls what happens at boot. It does not start anything on its own, and starting does not enable anything.

static means the unit has no [Install] section and is pulled in by something else; you cannot enable it and do not need to. Failed to start nginx.service: Unit nginx.service is masked means someone masked it, on purpose or by a package; unmask restores it.

List Units

list-units shows what systemd has loaded; list-unit-files shows what is installed on disk. A service that is installed but has never started shows up only in the second.

Logs

systemd services log to the journal, and journalctl reads it. These are the calls you need alongside systemctl; the journalctl cheat sheet covers the full toolkit.

systemctl status shows the last ten lines. When the service failed to start and those lines do not explain why, journalctl -u name -b -p err usually does. If journalctl shows nothing for a unit, the service may be writing to its own log file under /var/log instead of stdout.

Timers

Timers are systemd's cron: a .timer unit that starts a matching .service on a schedule.

A timer that runs a script every night at 03:00, in two files:

# /etc/systemd/system/backup.service
[Unit]
Description=Nightly backup

[Service]
Type=oneshot
ExecStart=/usr/local/bin/backup.sh

# /etc/systemd/system/backup.timer
[Unit]
Description=Run backup nightly

[Timer]
OnCalendar=*-*-* 03:00:00
Persistent=true

[Install]
WantedBy=timers.target

Persistent=true runs a missed job at the next boot, which cron never did. Have a crontab line already? The cron to systemd timer converter turns it into these two files, and the cron generator helps with the schedule itself.

Edit Unit Files

Your units go in /etc/systemd/system. Package units live in /usr/lib/systemd/system (or /lib/systemd/system on Debian and Ubuntu, which is the same directory) and get overwritten on upgrade, so never edit those directly. A file in /etc with the same name wins over the one in /usr/lib.

systemctl edit opens an empty drop-in in $EDITOR; whatever you type is layered on top of the original, and it runs daemon-reload for you. It does not restart the service, so follow with systemctl restart. Overriding ExecStart in a drop-in needs an empty line first, because ExecStart lines add up:

[Service]
ExecStart=
ExecStart=/usr/sbin/nginx -c /etc/nginx/custom.conf

A minimal service unit for your own program:

[Unit]
Description=My app
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=app
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/bin/server --port 3000
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Save it as /etc/systemd/system/myapp.service, then sudo systemctl daemon-reload and sudo systemctl enable --now myapp. The systemd unit generator writes this for you and the systemd unit validator checks one you already have. Moving a Node app off pm2? The pm2 to systemd converter turns an ecosystem file into units.

Boot and Power

systemd-analyze blame shows time spent, not time that delayed the boot; a unit can take 30 seconds in parallel without slowing anything. critical-chain shows the ones that actually held things up.

User Services

--user manages units under your own account, without sudo, from ~/.config/systemd/user/. Handy for a personal sync client, an editor daemon, or a dev server.

Without enable-linger, user services stop when your last session closes, which is the usual reason a --user service dies as soon as you disconnect from SSH.

Gotchas

• start is now, enable is at boot. A service you enabled but never started is still stopped until you reboot; enable --now does both.
• After editing any unit file by hand, run sudo systemctl daemon-reload, or systemd keeps using the old version and warns Warning: The unit file ... changed on disk. systemctl edit reloads for you but does not restart.
• A drop-in that sets ExecStart needs ExecStart= on its own line first to clear the original, or the unit fails with Service has more than one ExecStart= setting.
• Start request repeated too quickly is the start rate limit, not the real error. Read journalctl -u name -b for the crash that caused it, fix that, then systemctl reset-failed name before starting again.
• Unit is masked means someone ran mask, or the package masks it by design. unmask first, then enable.
• systemctl status truncates long lines and pages its output. Add --no-pager -l when you want to copy from it or pipe it.
• systemctl: command not found means no systemd: most Docker containers, macOS, Alpine, and WSL without systemd=true in /etc/wsl.conf. Inside a container, run the process directly and let the container's restart policy handle failures; the docker commands sheet covers that side.
• ExecStart needs an absolute path and does not understand shell syntax. ExecStart=cd /app && ./run fails; use WorkingDirectory=/app and ExecStart=/app/run, or call /bin/sh -c explicitly.