Skip to content

Check dhcp-scope-usage

Overview

Monitors IPv4 DHCP scope usage on a Windows DHCP server. Runs locally on the DHCP server or connects via WinRM, and queries scope statistics using PowerShell. Alerts when the address pool usage of any scope exceeds the configured thresholds (default: WARN at 80%, CRIT at 90%).

Important Notes:

  • Set the plugin timeout to 30 seconds, as WinRM connections can be slow
  • The --hostname parameter specifies which DHCP server to query (can differ from the WinRM target)
  • Without --winrm-hostname, the check runs locally on a Windows host with the DHCP Server tools, typically the DHCP server itself
  • Running directly on Linux without --winrm-hostname is not supported

Data Collection:

  • Executes the PowerShell cmdlet Get-DhcpServerv4ScopeStatistics -ComputerName "<hostname>" locally or via WinRM on the target Windows server
  • Reads PercentageInUse for each scope, cutting off the fraction, and returns UNKNOWN if the server answers with something that is no scope list
  • Reports "No IPv4 scope configured." on a DHCP server without scopes
  • Reports each scope individually with its usage percentage

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/dhcp-scope-usage
Nagios/Icinga Check Name check_dhcp_scope_usage
Check Interval Recommendation Every 15 minutes
Can be called without parameters Yes (on the Windows DHCP server itself)
Runs on Cross-platform
Compiled for Windows Yes
3rd Party Python modules winrm (for remote execution via WinRM)

Help

usage: dhcp-scope-usage [-h] [-V] [--always-ok] [--brief] [-c CRIT]
                        [-H HOSTNAME] [--no-perfdata] [-w WARN]
                        [--winrm-domain WINRM_DOMAIN]
                        [--winrm-hostname WINRM_HOSTNAME]
                        [--winrm-password WINRM_PASSWORD]
                        [--winrm-transport {basic,ntlm,kerberos,credssp,plaintext}]
                        [--winrm-username WINRM_USERNAME]

Monitors IPv4 DHCP scope usage on a Windows DHCP server. Runs locally on the
DHCP server or connects via WinRM, and queries scope statistics using
PowerShell. On servers with thousands of scopes, --brief hides rows within the
thresholds so the output only lists scopes in WARN/CRIT state. Alerts when the
address pool usage of any scope exceeds the configured thresholds (default:
WARN at 80%, CRIT at 90%). Supports extended reporting via --lengthy.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --always-ok           Always returns OK.
  --brief               Hide scopes within the thresholds and show only those
                        in WARN/CRIT state. Inverse of `--lengthy` (which adds
                        columns); `--brief` filters rows. The two are
                        orthogonal and can be combined. Perfdata and alerting
                        are unaffected: all scopes still emit perfdata and
                        still drive the overall check state.
  -c, --critical CRIT   CRIT threshold in percent. Default: >= 90
  -H, --hostname HOSTNAME
                        DNS name, IPv4, or IPv6 address of the DHCP server.
                        Default: localhost
  --no-perfdata         Suppress the performance data section from the output.
                        The status message and the exit code are unaffected,
                        so alerting keeps working while trending data is
                        dropped.
  -w, --warning WARN    WARN threshold in percent. Default: >= 80
  --winrm-domain WINRM_DOMAIN
                        WinRM Domain Name. Default: None
  --winrm-hostname WINRM_HOSTNAME
                        Target Windows computer on which the command will be
                        executed. Without it, the command runs on the local
                        Windows host.
  --winrm-password WINRM_PASSWORD
                        WinRM account password. Optional for Kerberos (uses
                        credential cache from kinit).
  --winrm-transport {basic,ntlm,kerberos,credssp,plaintext}
                        WinRM transport type. Default: ntlm
  --winrm-username WINRM_USERNAME
                        WinRM account name. Default: Administrator

Documentation:
https://linuxfabrik.github.io/monitoring-plugins/check-plugins/dhcp-scope-usage/

Usage Examples

Local usage on the Windows DHCP server:

./dhcp-scope-usage --warning=80 --critical=90

Remote usage, for example from a Linux server:

./dhcp-scope-usage \
    --hostname=dhcp01.example.com \
    --winrm-hostname=10.80.32.246 \
    --winrm-username=Administrator \
    --winrm-password=linuxfabrik \
    --winrm-domain=EXAMPLE.COM \
    --winrm-transport=ntlm

Output:

There are one or more criticals.

* 192.168.120.0: 0% used
* 192.168.121.0: 83% used [WARNING]
* 192.168.122.0: 91% used [CRITICAL]

States

  • OK if all DHCP scope usage percentages are below the thresholds.
  • OK with "No IPv4 scope configured." on a DHCP server without scopes.
  • WARN if the DHCP server does not answer: its service is stopped, or the host named by --hostname is unreachable.
  • WARN if any DHCP scope usage is >= --warning (default: 80%).
  • CRIT if any DHCP scope usage is >= --critical (default: 90%).
  • UNKNOWN if the answer of the DHCP server cannot be read as a list of scopes.
  • UNKNOWN if the host is no DHCP server or lacks the DHCP Server PowerShell tools.
  • UNKNOWN if the WinRM login or connection fails, or the account may not query the DHCP server.
  • --always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics

Name Type Description
scope_SCOPEID Percentage The address pool usage for the DHCP scope identified by SCOPEID (for example scope_192.168.122.0).

Credits, License