systemctl and unit management · Linux

systemctl is the interface to systemd. Two pairs of verbs do most of the work: start / stop for runtime, enable / disable for boot. Understanding the distinction is the foundation of every operational change.

Start, stop, restart, reload

Service impact possibleruntime verbs— start activates the unit now. stop deactivates it. restart stops then starts. reload tells the service to re-read configuration (only works for services that implement it — sshd does).

$ sudo systemctl start sshd; sudo systemctl stop sshd; sudo systemctl restart sshd; sudo systemctl reload sshd

Illustrative output

Verb	Effect on running state	Effect on boot
start	activates now	nothing
stop	deactivates now	nothing
restart	stops, starts	nothing
reload	runs the unit’s `ExecReload=`; fails if the unit defines none	nothing
enable	nothing	activates at boot
disable	nothing	deactivates at boot

`systemctl reload` does not mean send SIGHUP

reload runs whatever the unit’s ExecReload= line says. Many units set it to kill -HUP $MAINPID, which is where the shorthand comes from — but plenty do not:

# nginx: a real command, not a signal
ExecReload=/usr/sbin/nginx -s reload

And a unit with no ExecReload= at all does not fall back to SIGHUP. It refuses:

$ sudo systemctl reload chronyd
Failed to reload chronyd.service: Job type reload is not applicable
for unit chronyd.service.

That matters in a runbook. A step that says “reload to pick up the config” fails outright on such a unit, and if the script does not check the exit status the change is never applied while the run reports success. Check first:

systemctl show -p ExecReload --value nginx    # empty means reload is unavailable
systemctl reload-or-restart nginx             # reload if it can, restart if not

reload-or-restart is usually what a deployment script actually wants — but know that it may restart, so it is not safe where a restart drops connections.

enable, disable, mask, unmask

Service impact possibleboot verbs— enable creates the symlinks that activate the unit at boot. disable removes them. mask creates a /etc/systemd/system/<unit> symlink to /dev/null, preventing any activation — even by other services. unmask removes the mask.

$ sudo systemctl enable sshd; sudo systemctl disable sshd; sudo systemctl mask sshd; sudo systemctl unmask sshd

Illustrative output

Reading state

Read-only / Safesystemctl status— status shows loaded state, active state with sub-state, main PID, task count, memory, CPU time, and the cgroup tree. The Loaded line tells you whether the unit is enabled and whether it is vendor-preset.

$ systemctl status sshd

● sshd.service - OpenBSD Secure Shell server
Loaded: loaded (/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
Active: active (running) since Mon 2026-08-04 11:23:45 UTC; 5 days ago
Main PID: 12345 (sshd)
Tasks: 5 (limit: 23456)
Memory: 12.4M
CPU: 5.230s
CGroup: /system.slice/sshd.service
└─12345 /usr/sbin/sshd -D
...

Illustrative output

Read-only / Safeis-active / is-enabled / is-failed— Three queries that return single words — designed for scripting. is-active returns active/inactive/activating/deactivating/failed. is-enabled returns enabled/disabled/static/enabled-runtime. is-failed prints failed when the unit is in the failed state; otherwise it prints the current active state — which is why a perfectly healthy sshd prints active here.

$ systemctl is-active sshd; systemctl is-enabled sshd; systemctl is-failed sshd

active
enabled
active

Illustrative output

Read-only / Safeis-failed both ways— Healthy unit: prints its state, exits 1. Failed unit: prints failed, exits 0. Verified against systemd 255+.

$ systemctl is-failed sshd; echo "exit=$?"; systemctl is-failed broken.service; echo "exit=$?"

active
exit=1
failed
exit=0

Illustrative output

Script it on the exit code, never on the string:

# Correct: exit 0 means "this unit is in the failed state"
if systemctl is-failed --quiet "$unit"; then
    alert "$unit has failed"
fi

# WRONG - this alert never fires. A failed unit prints
# 'failed', not 'inactive', so the comparison is never true.
# It is also silently wrong the other way: a unit that is
# merely stopped prints 'inactive' and would alert falsely.
if [ "$(systemctl is-failed "$unit")" = "inactive" ]; then
    alert "$unit has failed"
fi

--quiet suppresses the state word so the exit code is the only output, which is what a check script wants. For the fleet-wide form, ask systemd for the whole list rather than looping:

Read-only / Safeevery failed unit at once— --no-legend strips the header and summary so each line is one failed unit — an empty output means nothing has failed. Cheaper and less racy than iterating over a hard-coded unit list, and it catches units you forgot to monitor. Bare `systemctl is-failed` with no unit answers the same question for the system as a whole: it reports the degraded state.

$ systemctl list-units --state=failed --no-legend

nginx.service loaded failed failed A high performance web server

Illustrative output

Clearing a failed state with reset-failed

A unit that has failed stays failed. systemd remembers it, and it also remembers how many times the unit has been started recently. Exceed the start rate limit — StartLimitBurst starts within StartLimitIntervalSec, 5 in 10 seconds on a stock system, both directives living in [Unit] — and systemd refuses every further start and restart, including the one you issue after fixing the problem.

Service impact possiblereset-failed then start— reset-failed clears the failed state AND the start rate-limit counter, so the next start is allowed. With no unit argument it clears every failed unit on the host, which is how you get systemctl --failed back to a meaningful list after an incident.

$ sudo systemctl reset-failed myapp; sudo systemctl start myapp

Active: active (running) since Mon 2026-08-10 09:14:02 UTC

Illustrative output

Start request repeated too quickly is not a broken host

A bad config push crash-loops a service. You roll the config back correctly, in seconds, then run systemctl restart myapp and get:

Failed to restart myapp.service: Unit myapp.service has a start
request repeated too quickly.

The config is already fixed. Nothing is wrong with the host. The rate-limit counter is simply still armed. Without reset-failed the usual next move is a reboot, which turns a 30-second rollback into a full node outage — and on a cluster member it can trigger a failover nobody planned for.

daemon-reload does not help: it re-reads unit files, it does not clear the counter. systemctl reset-failed <unit> is the correct move, and systemctl status will show Result: start-limit-hit on the failed unit to confirm that is what you are looking at.

Listing and filtering

Read-only / Safelist-units— list-units shows runtime status of units. list-unit-files shows the on-disk state (enabled/disabled/static) without runtime. --state=failed is the canonical first command after a reboot — it tells you what failed to start.

$ systemctl list-units --type=service; systemctl list-units --state=failed; systemctl list-unit-files --type=service | head

UNIT                         LOAD   ACTIVE SUB     DESCRIPTION
accounts-daemon.service      loaded active running Accounts Service
chrony.service                loaded active running chrony, an NTP client/server
...

Illustrative output

Production patterns

Read-only / Safepost-boot health check— After a reboot, run this. If any unit is in failed state, the system has a problem. Then `systemctl status <unit>` and `journalctl -xeu <unit>` for diagnostics.

$ systemctl list-units --state=failed --no-pager

0 loaded units listed.

Illustrative output

Read-only / Safereverse deps— --reverse shows what depends ON this unit. Useful when stopping a service — the list tells you what will be affected. runlevel2.target means sshd is part of multi-user.target; many services transitively depend on it.

$ systemctl list-dependencies --reverse sshd

sshd.service
● └─runlevel2.target
...

Illustrative output

Start, stop, restart, reload

enable, disable, mask, unmask

Reading state

Clearing a failed state with reset-failed

Listing and filtering

Production patterns

Knowledge check