DHCP Server Metrics
For how these metrics are used and how the server detects DHCP servers, see DHCP Server Monitoring.
These metrics are provided by the DHCP server subagents: kea (ISC Kea) and dnsmasq (dnsmasq) on UNIX-like systems, and winnt (Microsoft DHCP Server role, IPv4 only) on Windows.
All subagents return the same lists and tables, with the same columns.
The scope ID used as the argument is the scope network in address/bits form (for example 192.168.10.0/24 or 2001:db8:1::/64); it is matched case-insensitively.
The DHCP.Scopes list returns valid scope IDs.
For a dnsmasq range whose network cannot be determined, the scope ID is the address range itself (first-last).
Scope Metrics
DHCP.Scope.Declined(scope)
Number of addresses in the scope that clients have declined (for example, because of an address conflict).
Only the kea subagent provides this metric, because dnsmasq and Microsoft DHCP Server do not report declined addresses.
Data Type |
Unsigned Integer 64 |
Platforms |
UNIX-like systems ( |
| Argument | Type | Description |
|---|---|---|
scope |
String |
Scope ID |
DHCP.Scope.Free(scope)
Number of free addresses in the scope: total minus used minus declined (declined counts as 0 when the DHCP server does not report it).
Data Type |
Unsigned Integer 64 |
Platforms |
UNIX-like systems ( |
| Argument | Type | Description |
|---|---|---|
scope |
String |
Scope ID |
DHCP.Scope.Total(scope)
Number of addresses in the scope that are available for leasing (the size of the address pools, not of the whole network).
Data Type |
Unsigned Integer 64 |
Platforms |
UNIX-like systems ( |
| Argument | Type | Description |
|---|---|---|
scope |
String |
Scope ID |
Tables
DHCP.Scopes (Table)
DHCP scopes with address usage. The server reads this table during configuration polls to detect whether a node is a DHCP server.
Data Type |
Table |
Platforms |
UNIX-like systems ( |
| Column | Type | Description |
|---|---|---|
ID |
String |
Scope ID (instance key) |
IP_VERSION |
Integer |
IP version: 4 or 6 |
NETWORK |
String |
Scope network in |
NAME |
String |
Scope name, if the DHCP server configuration provides one |
RANGES |
String |
Address ranges available for leasing, comma-separated |
ENABLED |
Integer |
1 if the scope is enabled, 0 if it is disabled |
TOTAL |
Unsigned Integer 64 |
Number of addresses available for leasing |
USED |
Unsigned Integer 64 |
Number of leased addresses |
DECLINED |
Unsigned Integer 64 |
Number of declined addresses; empty when the DHCP server does not report declined addresses |
FREE |
Unsigned Integer 64 |
Number of free addresses |
UTILIZATION |
Float |
Used addresses as a percentage of total |
DHCP.Leases, DHCP.Leases(scope)
DHCP leases and reservations. Without an argument, the table contains leases from all scopes; with a scope ID, only leases from that scope. Reservations that have no active lease are included as rows with type 1 and state 5.
Data Type |
Table |
Platforms |
UNIX-like systems ( |
| Argument | Type | Description |
|---|---|---|
scope |
String |
Scope ID (optional; |
| Column | Type | Description |
|---|---|---|
IP_ADDRESS |
String |
Leased or reserved address (instance key) |
PREFIX_LENGTH |
Integer |
Prefix length: 32 for IPv4 addresses, 128 for IPv6 addresses, the delegated prefix length for IPv6 prefix delegation |
SCOPE_ID |
String |
ID of the scope the address belongs to |
MAC_ADDRESS |
String |
Client MAC address |
CLIENT_ID |
String |
DHCP client identifier (DUID for DHCPv6) |
HOSTNAME |
String |
Client host name |
TYPE |
Integer |
Lease type: 0 = dynamic, 1 = reservation |
STATE |
Integer |
Lease state: 0 = active, 1 = expired, 2 = declined, 3 = released, 4 = offered, 5 = inactive (reservation without active lease) |
LAST_TRANSACTION |
Integer 64 |
Time of the last client transaction (UNIX time); 0 if not known |
EXPIRATION |
Integer 64 |
Lease expiration time (UNIX time); 0 if not known or the lease does not expire |