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. 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%).
Important Notes:
- Give the check command a timeout of at least 30 seconds (the Director basket does). On Windows Server 2025, loading the DHCP Server module alone takes up to 20 seconds per run, which is why
--timeoutdefaults to 25 seconds. - The
--hostnameparameter 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-hostnameis not supported
Data Collection:
- Executes the PowerShell cmdlet
Get-DhcpServerv4ScopeStatistics -ComputerName "<hostname>"locally or via WinRM on the target Windows server - Reads
PercentageInUsefor 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] [--timeout TIMEOUT]
[-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%).
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. 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.
--timeout TIMEOUT Network timeout in seconds. Default: 25 (seconds)
-w, --warning WARN WARN threshold in percent. Default: >= 80
--winrm-domain WINRM_DOMAIN
AD domain name for NTLM authentication. When set, the
username is sent as user@DOMAIN. Not needed for
Kerberos or local accounts.
--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
the credential cache from kinit).
--winrm-transport {basic,ntlm,kerberos,credssp,plaintext}
WinRM transport type. Default: ntlm
--winrm-username WINRM_USERNAME
WinRM account name. Optional for Kerberos (uses the
credential cache from kinit). 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
--hostnameis 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-oksuppresses 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¶
- Authors: Linuxfabrik GmbH, Zurich
- License: The Unlicense, see LICENSE file.