Check systemd-unit¶
Overview¶
Checks the state of a specific systemd unit (service, socket, device, mount, timer, scope, etc.) via systemctl show. Verifies the active state, sub-state, load state, and unit file state against expected values. If the unit failed, the check says why, for example the exit status or the signal that killed it, and shows the last log lines of the unit.
Important Notes:
- Best practice: specify
--activestateand--substateat least - The
.servicesuffix is optional for service units, but recommended - The
--machineparameter connects to a local container by its name. A user name prefix (user@container) is refused, because it would let the caller of this root check act on behalf of any account
Data Collection:
- Executes
systemctl show --property=Id,LoadState,ActiveState,SubState,UnitFileState,Result,ExecMainCode,ExecMainStatus <unit> - If the unit is not in the expected state and failed, or waits to be restarted after a failure, the check says why from
Result,ExecMainCodeandExecMainStatus. Exit statuses from 200 on are set by systemd itself and are shown with their name, for example203/EXEC, see systemd.exec(5) - Then it reads the last three lines the unit wrote itself with
journalctl --boot=0 --output=cat --lines=3 _SYSTEMD_UNIT=<unit>, and ends with thejournalctlcommand that shows the whole log. Not with--machineor--user, whose journal is elsewhere - Optionally supports
--machineto query units inside local containers (requires systemd >= 209) - Optionally supports
--userto query user-level service manager
Fact Sheet¶
| Fact | Value |
|---|---|
| Check Plugin Download | https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/systemd-unit |
| Nagios/Icinga Check Name | check_systemd_unit |
| Check Interval Recommendation | Every minute |
| Can be called without parameters | No (--unit is required) |
| Runs on | Linux |
| Compiled for Windows | No |
Help¶
usage: systemd-unit [-h] [-V]
[--activestate {None,activating,active,deactivating,failed,inactive}]
[--always-ok]
[--loadstate {None,activating,active,deactivating,failed,inactive,loaded,maintenance,masked,not-found,reloading}]
[--machine MACHINE] [--severity {warn,crit}]
[--substate {None,abandoned,activating,activating-done,active,auto-restart,cleaning,condition,deactivating,deactivating-sigkill,deactivating-sigterm,dead,elapsed,exited,failed,final-sigkill,final-sigterm,final-watchdog,listening,mounted,mounting,mounting-done,plugged,reload,remounting,remounting-sigkill,remounting-sigterm,running,start,start-chown,start-post,start-pre,stop,stop-post,stop-pre,stop-pre-sigkill,stop-pre-sigterm,stop-sigkill,stop-sigterm,stop-watchdog,tentative,unmounting,unmounting-sigkill,unmounting-sigterm,waiting}]
--unit UNIT
[--unitfilestate {None,bad,disabled,empty,enabled,enabled-runtime,generated,indirect,linked,linked-runtime,masked,masked-runtime,static,transient}]
[--user]
Checks the state of a specific systemd unit (service, socket, device, mount,
timer, scope, etc.) via systemctl. Verifies the active state, sub-state, load
state, and unit file state against expected values. Alerts when the unit is
not in the expected state, and if it failed, says why, for example the exit
status or the signal that killed it, and shows its last log lines. Requires
root or sudo.
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
--activestate {None,activating,active,deactivating,failed,inactive}
Expected systemd ActiveState (high-level unit
activation state, i.e. generalization of SUB). Can be
specified multiple times. If omitted or set to "None",
the unit's active state will not be checked.
--always-ok Always returns OK.
--loadstate {None,activating,active,deactivating,failed,inactive,loaded,maintenance,masked,not-found,reloading}
Expected systemd LoadState, reflecting whether the
unit definition was properly loaded. If omitted or set
to "None", the unit's load state will not be checked.
Default: loaded
--machine MACHINE Execute operation on a local container. Specify the
name of the container to connect to. A user name
prefix (`user@container`) is not accepted. Example:
`--machine=mycontainer`.
--severity {warn,crit}
Severity for alerting. Default: warn
--substate {None,abandoned,activating,activating-done,active,auto-restart,cleaning,condition,deactivating,deactivating-sigkill,deactivating-sigterm,dead,elapsed,exited,failed,final-sigkill,final-sigterm,final-watchdog,listening,mounted,mounting,mounting-done,plugged,reload,remounting,remounting-sigkill,remounting-sigterm,running,start,start-chown,start-post,start-pre,stop,stop-post,stop-pre,stop-pre-sigkill,stop-pre-sigterm,stop-sigkill,stop-sigterm,stop-watchdog,tentative,unmounting,unmounting-sigkill,unmounting-sigterm,waiting}
Expected systemd SubState (low-level unit activation
state; values depend on unit type). Can be specified
multiple times. If omitted or set to "None", the
unit's substate will not be checked.
--unit UNIT Systemd unit name to check (service, timer, mount,
etc.). Required. Example: `--unit=sshd.service`.
--unitfilestate {None,bad,disabled,empty,enabled,enabled-runtime,generated,indirect,linked,linked-runtime,masked,masked-runtime,static,transient}
Expected systemd UnitFileState. If set to "empty",
checks exactly for `UnitFileState=""`. If omitted or
set to "None", the unit's unit-file state will not be
checked.
--user Talk to the service manager of the calling user rather
than the service manager of the system.
Documentation:
https://linuxfabrik.github.io/monitoring-plugins/check-plugins/systemd-unit/
Usage Examples¶
Does the service exist (and nothing more)?
./systemd-unit --unit=firewalld.service
Is the service running?
./systemd-unit --substate=running --unit=firewalld.service
Is the service disabled?
./systemd-unit --unitfilestate=disabled --unit=firewalld.service
Is the service stopped and disabled?
./systemd-unit --activestate=inactive --substate=dead --unitfilestate=disabled --unit=firewalld.service
Is the service exited?
./systemd-unit --substate=exited --unit=firewalld.service
Is this service with instance name "server" running?
./systemd-unit --substate=running --unit=openvpn-server@server.service
Is this service absent/uninstalled?
./systemd-unit --loadstate=not-found --unit=firewalld.service
Is this path mounted?
./systemd-unit --substate=mounted --unit=mnt-smb.mount
Is this device plugged in?
./systemd-unit --substate=plugged --unit=sys-devices-virtual-net-tun0.device
Check a timer job (has one activestate and two substates)?
./systemd-unit --activestate=active --substate=waiting --substate=running --unit=myjob.timer
Check a service depending on a timer (has two activestates and two substates)?
./systemd-unit --activestate=active --activestate=inactive --substate=dead --substate=running --unit=myjob.service
Use the --machine parameter:
./systemd-unit --machine=mycontainer --unit=sshd
Output (mismatch):
firewalld.service - LoadState is "loaded", but should be set to "not-found"
Output (the unit failed):
httpd (exited with status 1) - ActiveState is "failed", but supposed to be "['active']"
Last log lines of httpd.service:
httpd.service: Referenced but unset environment variable evaluates to an empty string: OPTIONS
AH00526: Syntax error on line 100 of /etc/httpd/conf/httpd.conf:
Invalid command 'ServerNmae', perhaps misspelled or defined by a module not included in the server configuration
Show the log with `sudo journalctl --boot=0 --unit=httpd.service`
States¶
- OK if all checked states match the expected values.
- WARN (default) if any checked state does not match the expected value.
- CRIT if
--severity=critis set and any checked state does not match. - UNKNOWN if
--machinecarries a user name part (user@container).
Perfdata / Metrics¶
There is no perfdata.
Credits, License¶
- Authors: Linuxfabrik GmbH, Zurich
- License: The Unlicense, see LICENSE file.