DHCP Server Monitoring
NetXMS reads scope and lease information from DHCP servers. It shows the scopes and leases of a DHCP server in the management console, collects scope utilization as data collection items, and makes the same information available to NXSL scripts and the REST API.
The information comes either from the NetXMS agent on the DHCP server host (ISC Kea, dnsmasq, Microsoft DHCP Server) or from the network device driver of a network device that acts as a DHCP server (MikroTik RouterOS, Cisco IOS, Dell PowerConnect / N-series).
How It Works
Data Sources
| DHCP server | Read by | Access method | IP versions | Leases | Declined addresses |
|---|---|---|---|---|---|
ISC Kea |
|
Kea control sockets ( |
IPv4, IPv6 |
Yes, requires the Kea |
Yes |
dnsmasq |
|
dnsmasq configuration files and lease file |
IPv4, IPv6 |
Yes |
No |
Microsoft DHCP Server |
|
DHCP Server management API |
IPv4 |
Yes |
No |
MikroTik RouterOS |
|
SSH ( |
IPv4 |
Yes |
Yes |
Cisco IOS |
|
SSH interactive session ( |
IPv4 |
Yes |
No |
Dell PowerConnect / N-series (DNOS) |
|
SNMP (DNOS-DHCPSERVER-PRIVATE-MIB) |
IPv4 |
Yes |
No |
All sources deliver the same data: a list of scopes with address counts, and a list of leases and reservations.
The agent subagents return it as the agent tables DHCP.Scopes and DHCP.Leases (see Agent Metrics); network device drivers return it to the server directly.
DHCP Server Detection
During each configuration poll, the server checks whether a node provides DHCP information:
-
If the node has a NetXMS agent, the server requests the agent table
DHCP.Scopes. -
If the agent does not provide the table, the server asks the node’s network device driver for the DHCP scopes.
-
If either source returns scope information, the node gets the capability DHCP server (shown in the Capabilities section of the node’s Overview tab), and the poll output shows
DHCP server information is available fromfollowed byagentor the driver name. -
If no source returns scope information, the capability is removed — unless one of the sources failed with a communication error or no source could be checked at all (no agent and no usable network device driver); in that case the capability stays unchanged.
When the server later reads scopes or leases, it uses the agent first. It falls back to the network device driver only when the agent reports that it does not support the request; any other agent error is returned as is.
The DHCP tab in the management console, the NXSL methods, and the REST API endpoints work only for nodes that have the DHCP server capability.
Scopes and Address Counts
Each scope is identified by its network in address/bits form, for example 192.168.10.0/24.
The same scope ID is used as the metric argument, as the instance of DCIs created by the template, and as the scope filter in NXSL and the REST API.
For a dnsmasq address range whose network cannot be determined, the scope ID is the range itself (first-last).
For every scope, NetXMS reports these address counts:
-
Total — addresses available for leasing (the address pools of the scope, not the whole network)
-
Used — leased addresses
-
Declined — addresses that clients declined, for example because of an address conflict; only Kea and MikroTik report it, for other sources the value is unknown
-
Free — total minus used minus declined (declined counts as 0 when unknown)
-
Utilization — used addresses as a percentage of total
How each source counts addresses:
-
Kea — total, used, and declined come from Kea subnet statistics (
total-addresses,assigned-addresses,declined-addresses; for DHCPv6,total-nasandassigned-nas, so delegated prefixes are not counted). The scope name is taken from the subnet’suser-context(name, thencomment), or from the name of its shared network. -
dnsmasq — one scope is created per network of
dhcp-rangeoptions. Total is the size of the ranges; for a scope with onlystaticranges, total is the number of reservations. Used is the number of unexpired leases in the lease file. The scope name is theset:tag of the range. -
Microsoft DHCP Server — total is the sum of addresses in use, free addresses, and pending offers, as reported by the DHCP server.
-
MikroTik — one scope is created per DHCP network (
/ip dhcp-server network), with the address pools of the DHCP servers that fall into it. Bound leases inside the pools count as used, and leases with statusbusycount as declined. -
Cisco IOS — one scope is created per DHCP pool. From
show ip dhcp pool, total isTotal addressesminusExcluded addresses, and used isLeased addresses. -
Dell DNOS — one scope is created per dynamic pool. Total is the number of host addresses in the pool network minus excluded address ranges, and used is the number of leases in the pool.
Enabling DHCP Server Monitoring
The DHCP server tables are provided by subagents (Kea, dnsmasq, Windows) or by network device drivers. After you set up the source, run a configuration poll on the node () and check that the node has the DHCP server capability and a DHCP tab.
ISC Kea
The kea subagent connects to the control sockets of the Kea DHCPv4 and DHCPv6 servers (UNIX domain sockets, so the subagent runs on UNIX-like systems only).
-
In the Kea configuration, enable a UNIX control socket for each Kea server you want to monitor.
-
To see leases, load the
lease_cmdshook library in the Kea servers. Without it, scopes and address counts are still available, but the lease list is not. -
Make sure that the agent process has permission to connect to the control sockets.
-
Load the subagent in
nxagentd.conf:SubAgent = kea -
If the control sockets are not in a default location, set their paths in the
[KEA]section and restart the agent.
Example Kea configuration fragment in Kea 2.x syntax (the hook library path depends on the distribution; see the Kea documentation for your version):
"Dhcp4": {
"control-socket": {
"socket-type": "unix",
"socket-name": "/run/kea/kea4-ctrl-socket"
},
"hooks-libraries": [
{ "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so" }
]
}
| Parameter | Default | Description |
|---|---|---|
|
First existing socket of |
Path to the control socket of the Kea DHCPv4 server. Set an empty value to disable DHCPv4 monitoring. |
|
First existing socket of |
Path to the control socket of the Kea DHCPv6 server. Set an empty value to disable DHCPv6 monitoring. |
|
|
Timeout in milliseconds for control socket commands. |
|
|
Time in seconds the subagent reuses scope information before it reads it from Kea again. |
[KEA]
DHCPv4Socket = /var/lib/kea/kea4-ctrl-socket
DHCPv6Socket =
Kea reports host reservations defined in the subnet configuration. A reservation that has no active lease appears in the lease list with state Inactive. Declined leases are reported with state Declined.
dnsmasq
The dnsmasq subagent reads the dnsmasq configuration and lease file; it does not communicate with the dnsmasq process.
It runs on UNIX-like systems.
-
Make sure that the agent process can read the dnsmasq configuration files and the lease file.
-
Load the subagent in
nxagentd.conf:SubAgent = dnsmasq -
If the files are not in a default location, set their paths in the
[DNSMASQ]section and restart the agent.
The subagent builds scopes from dhcp-range options and reservations from dhcp-host options, including the files named in dhcp-hostsfile and dhcp-hostsdir.
It follows conf-file and conf-dir options.
Ranges in proxy, ra-only, or ra-stateless mode lease no addresses and are ignored.
A missing lease file is treated as an empty lease list, because dnsmasq creates the file only when it grants the first lease.
| Parameter | Default | Description |
|---|---|---|
|
First existing file of |
Path to the main dnsmasq configuration file. |
|
Value of the |
Path to the dnsmasq lease file. |
|
|
Time in seconds the subagent reuses parsed configuration and lease information before it reads the files again. |
dnsmasq does not report declined addresses. Leases from the lease file are reported as Active or Expired, and reservations without a lease as Inactive.
Microsoft DHCP Server
On Windows, the winnt platform subagent (loaded automatically) reads IPv4 scopes and leases from the DHCP Server role through the DHCP Server management API.
DHCPv6 scopes are not reported, and Microsoft DHCP Server does not report declined addresses.
By default, the subagent reads the local DHCP Server service (127.0.0.1) and reports the DHCP tables only when that service is installed and running.
To read a DHCP server on another host, set its address in the [WinNT] section; the local service check is then skipped:
[WinNT]
DHCPServerAddress = 10.0.0.5
The subagent reuses scope information for 5 seconds.
Network Devices
For network devices, no extra configuration is required in NetXMS other than access to the device:
-
MikroTik and Cisco IOS — the drivers read DHCP information over SSH, so the node needs working SSH settings (see Configuring SSH on a Node). The Cisco IOS drivers use an interactive SSH session.
-
Dell PowerConnect / N-series — the
DELL-PWCdriver reads the DNOS-DHCPSERVER-PRIVATE-MIB over SNMP.
See Network Device Drivers Reference for driver selection.
DHCP Server Template
The server includes the template DHCP Server (file dhcp_server.json in the server’s share/templates directory, for example /usr/share/netxms/templates).
The server imports it on startup as controlled by the server configuration variable Server.ImportConfigurationOnStartup (default: only missing elements; see Server Configuration Variables).
If that variable is set to Never, import the file manually with .
After import, the template is in the template group Network Services.
The template:
-
Is applied automatically to nodes with the DHCP server capability, and removed automatically when a node loses it (auto-apply rule
return (classof($object) == "Node") && $node.isDHCPServer;). -
Uses instance discovery with method Internal Table over the server internal table
DHCP.Scopes, so it creates one set of DCIs per scope, with the scope ID as instance. -
Uses only server internal metrics (see Server Internal Metrics), so it works with every source in Data Sources.
| DCI | Threshold |
|---|---|
|
Value >= 90 for 2 consecutive polls generates |
|
— |
|
— |
|
— |
The template has no DCI for declined addresses.
Add DHCP.Scope.Declined({instance}) yourself if your DHCP server reports them.
DHCP Tab in the Management Console
Nodes with the DHCP server capability have a DHCP tab. The tab reads scopes and leases from the node when you open it or refresh it; the data is not stored on the server.
The upper table lists the scopes:
| Column | Content |
|---|---|
Network |
Scope network (the scope ID if the network is not known) |
Name |
Scope name |
Ranges |
Address ranges available for leasing |
Total |
Addresses available for leasing |
Used |
Leased addresses |
Declined |
Declined addresses; empty when the DHCP server does not report them |
Free |
Free addresses |
Utilization |
Used addresses as a percentage of total |
The lower table lists leases and reservations. When no scope is selected, it shows leases from all scopes; select a scope to show only the leases of that scope. The scope selection is kept when the tab is refreshed, as long as the scope still exists.
| Column | Content |
|---|---|
IP Address |
Leased or reserved address (the prefix for an IPv6 prefix delegation) |
MAC Address |
Client MAC address |
NIC Vendor |
Network adapter vendor, looked up from the MAC address |
Host Name |
Client host name |
Client ID |
DHCP client identifier (DUID for DHCPv6) |
Scope |
Scope ID |
Type |
Dynamic or Reservation |
State |
Active, Expired, Declined, Released, Offered, or Inactive (reservation without active lease); see Lease Types and States |
Last Transaction |
Time of the last client transaction |
Expiration |
Lease expiration time |
The filter bar filters the lease list by IP address, MAC address, NIC vendor, host name, client ID, and scope.
Context menu of the scope list: Copy to clipboard, Export all to CSV…. Context menu of the lease list: Copy to clipboard, Export selection to CSV… (Export to CSV… in the web console), Export all to CSV…. The view toolbar has Export all to CSV… for the lease list.
If the DHCP server provides scopes but no lease list, the tab shows the message Lease list is not available for this DHCP server. Errors are shown as Cannot read DHCP scopes or Cannot read DHCP leases.
Access from Scripts and the REST API
All access requires read access to the node, and the node must have the DHCP server capability.
-
NXSL — the
NodeattributeisDHCPServer, and the methodsNode.getDHCPScopes()andNode.getDHCPLeases()(optionally with a scope ID), which return arrays of DHCPScope and DHCPLease objects. See Node. -
REST API —
GET /v1/objects/{object-id}/dhcp/scopesandGET /v1/objects/{object-id}/dhcp/leases(optionalscopequery parameter). See REST API.
These requests read the data from the node every time; the 30-second cache of the internal metrics does not apply.
Reference
Server Internal Metrics
Internal metrics (DCI origin Internal) are calculated by the server from the scope information of the node, whichever source provides it. The server keeps the scope list of a node for 30 seconds, so all DHCP DCIs of a node collected at the same time cause a single request to the agent or the device. A failed request is cached for the same time.
| Metric | Type | Description |
|---|---|---|
|
Table |
Scopes of the DHCP server, with the same columns as the agent table DHCP.Scopes. Usable for table DCIs and as the source of instance discovery with method Internal Table. |
|
Unsigned Integer 64 |
Addresses available for leasing in the scope |
|
Unsigned Integer 64 |
Leased addresses in the scope |
|
Unsigned Integer 64 |
Free addresses in the scope |
|
Unsigned Integer 64 |
Declined addresses in the scope; the DCI gets the status not supported when the DHCP server does not report declined addresses |
|
Float |
Used addresses as a percentage of total, with two decimal places |
The argument scope is the scope ID.
An unknown scope ID results in the error no such instance.
Lease Types and States
The agent table DHCP.Leases and the NXSL class DHCPLease use the numeric values; NXSL also has them as the constants DHCPLeaseType::<name> and DHCPLeaseState::<name>.
The REST API returns the names.
| Value | Type name | Meaning |
|---|---|---|
0 |
|
Address leased from a pool |
1 |
|
Address reserved for a specific client |
| Value | State name | Meaning |
|---|---|---|
0 |
|
Lease is valid |
1 |
|
Lease has expired |
2 |
|
Client declined the address |
3 |
|
Client released the address |
4 |
|
Address is offered to a client, not yet confirmed |
5 |
|
Reservation without an active lease (also a disabled lease on MikroTik) |
Not every source reports every state. For example, dnsmasq reports only Active, Expired, and Inactive.
Agent Metrics
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 |
Troubleshooting
-
The node has no DHCP server capability — query the agent table directly, for example
nxget -T <agent-address> DHCP.Scopes. If the table is not supported, check that the subagent is loaded (Agent.SubAgentList) and that it can reach the DHCP server: Kea control sockets, dnsmasq configuration file with at least onedhcp-range, or a running DHCP Server service on Windows. -
Scopes are shown, but the lease list is not available — for Kea, load the
lease_cmdshook library. -
No information from a network device — check that the correct network device driver is selected for the node and that SSH (MikroTik, Cisco) or SNMP (Dell) access works.
To see details, enable these debug tags (agent tags with DebugTags in nxagentd.conf, server tags with the debug server console command; see Diagnostics):
| Debug tag | Component |
|---|---|
|
Server: reading DHCP information from agents and network device drivers |
|
Server: DHCP server detection during configuration poll |
|
Agent: |
|
Agent: |
|
Agent: Microsoft DHCP Server support in the |
|
Server: MikroTik network device driver |
|
Server: Cisco network device drivers |
|
Server: Dell PowerConnect / N-series network device driver |