Skip to content

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 --activestate and --substate at least
  • The .service suffix is optional for service units, but recommended
  • The --machine parameter 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, ExecMainCode and ExecMainStatus. Exit statuses from 200 on are set by systemd itself and are shown with their name, for example 203/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 the journalctl command that shows the whole log. Not with --machine or --user, whose journal is elsewhere
  • Optionally supports --machine to query units inside local containers (requires systemd >= 209)
  • Optionally supports --user to 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=crit is set and any checked state does not match.
  • UNKNOWN if --machine carries a user name part (user@container).

Perfdata / Metrics

There is no perfdata.

Credits, License