This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

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 (kea)

Table 1. Arguments
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 (kea, dnsmasq), Windows (winnt)

Table 2. Arguments
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 (kea, dnsmasq), Windows (winnt)

Table 3. Arguments
Argument Type Description

scope

String

Scope ID

DHCP.Scope.Used(scope)

Number of leased addresses in the scope.

Data Type

Unsigned Integer 64

Platforms

UNIX-like systems (kea, dnsmasq), Windows (winnt)

Table 4. Arguments
Argument Type Description

scope

String

Scope ID

DHCP.Scope.Utilization(scope)

Used addresses as a percentage of total addresses, with two decimal places (0 for a scope with no addresses).

Data Type

Float

Platforms

UNIX-like systems (kea, dnsmasq), Windows (winnt)

Table 5. Arguments
Argument Type Description

scope

String

Scope ID

Lists

DHCP.Scopes (List)

IDs of all scopes of the DHCP server.

Data Type

List

Platforms

UNIX-like systems (kea, dnsmasq), Windows (winnt)

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 (kea, dnsmasq), Windows (winnt)

Table 6. Columns
Column Type Description

ID

String

Scope ID (instance key)

IP_VERSION

Integer

IP version: 4 or 6

NETWORK

String

Scope network in address/bits form

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 (kea, dnsmasq), Windows (winnt)

Table 7. Arguments
Argument Type Description

scope

String

Scope ID (optional; DHCP.Leases(*) form only)

Table 8. Columns
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