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 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 subagent

Kea control sockets (config-get, statistic-get-all; leases with lease4-get-all / lease6-get-all)

IPv4, IPv6

Yes, requires the Kea lease_cmds hook library

Yes

dnsmasq

dnsmasq subagent

dnsmasq configuration files and lease file

IPv4, IPv6

Yes

No

Microsoft DHCP Server

winnt subagent

DHCP Server management API

IPv4

Yes

No

MikroTik RouterOS

MIKROTIK network device driver

SSH (/ip dhcp-server and /ip pool commands)

IPv4

Yes

Yes

Cisco IOS

CISCO-GENERIC, CATALYST-GENERIC, CATALYST-2900XL, and CISCO-C9800 network device drivers

SSH interactive session (show ip dhcp pool, show ip dhcp binding)

IPv4

Yes

No

Dell PowerConnect / N-series (DNOS)

DELL-PWC network device driver

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:

  1. If the node has a NetXMS agent, the server requests the agent table DHCP.Scopes.

  2. If the agent does not provide the table, the server asks the node’s network device driver for the DHCP scopes.

  3. 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 from followed by agent or the driver name.

  4. 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-nas and assigned-nas, so delegated prefixes are not counted). The scope name is taken from the subnet’s user-context (name, then comment), or from the name of its shared network.

  • dnsmasq — one scope is created per network of dhcp-range options. Total is the size of the ranges; for a scope with only static ranges, total is the number of reservations. Used is the number of unexpired leases in the lease file. The scope name is the set: 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 status busy count as declined.

  • Cisco IOS — one scope is created per DHCP pool. From show ip dhcp pool, total is Total addresses minus Excluded addresses, and used is Leased 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 (Poll  Configuration) 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).

  1. In the Kea configuration, enable a UNIX control socket for each Kea server you want to monitor.

  2. To see leases, load the lease_cmds hook library in the Kea servers. Without it, scopes and address counts are still available, but the lease list is not.

  3. Make sure that the agent process has permission to connect to the control sockets.

  4. Load the subagent in nxagentd.conf:

    SubAgent = kea
  5. 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" }
    ]
}
Table 1. [KEA] section parameters
Parameter Default Description

DHCPv4Socket

First existing socket of /run/kea/kea4-ctrl-socket, /var/run/kea/kea4-ctrl-socket, /tmp/kea4-ctrl-socket

Path to the control socket of the Kea DHCPv4 server. Set an empty value to disable DHCPv4 monitoring.

DHCPv6Socket

First existing socket of /run/kea/kea6-ctrl-socket, /var/run/kea/kea6-ctrl-socket, /tmp/kea6-ctrl-socket

Path to the control socket of the Kea DHCPv6 server. Set an empty value to disable DHCPv6 monitoring.

Timeout

5000

Timeout in milliseconds for control socket commands.

CacheTime

5

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.

  1. Make sure that the agent process can read the dnsmasq configuration files and the lease file.

  2. Load the subagent in nxagentd.conf:

    SubAgent = dnsmasq
  3. 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.

Table 2. [DNSMASQ] section parameters
Parameter Default Description

ConfigFile

First existing file of /etc/dnsmasq.conf, /usr/local/etc/dnsmasq.conf, /opt/homebrew/etc/dnsmasq.conf

Path to the main dnsmasq configuration file.

LeaseFile

Value of the dhcp-leasefile option in the dnsmasq configuration; otherwise first existing file of /var/lib/misc/dnsmasq.leases, /var/lib/dnsmasq/dnsmasq.leases, /var/db/dnsmasq.leases, /tmp/dhcp.leases

Path to the dnsmasq lease file.

CacheTime

5

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-PWC driver 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 Configuration  Import configuration. 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

DHCP.Scope.Utilization({instance})

Value >= 90 for 2 consecutive polls generates SYS_THRESHOLD_REACHED; SYS_THRESHOLD_REARMED after 2 consecutive polls below

DHCP.Scope.Used({instance})

 — 

DHCP.Scope.Free({instance})

 — 

DHCP.Scope.Total({instance})

 — 

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 Node attribute isDHCPServer, and the methods Node.getDHCPScopes() and Node.getDHCPLeases() (optionally with a scope ID), which return arrays of DHCPScope and DHCPLease objects. See Node.

  • REST API — GET /v1/objects/{object-id}/dhcp/scopes and GET /v1/objects/{object-id}/dhcp/leases (optional scope query 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

DHCP.Scopes

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.

DHCP.Scope.Total(scope)

Unsigned Integer 64

Addresses available for leasing in the scope

DHCP.Scope.Used(scope)

Unsigned Integer 64

Leased addresses in the scope

DHCP.Scope.Free(scope)

Unsigned Integer 64

Free addresses in the scope

DHCP.Scope.Declined(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

DHCP.Scope.Utilization(scope)

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

DYNAMIC

Address leased from a pool

1

RESERVATION

Address reserved for a specific client

Value State name Meaning

0

ACTIVE

Lease is valid

1

EXPIRED

Lease has expired

2

DECLINED

Client declined the address

3

RELEASED

Client released the address

4

OFFERED

Address is offered to a client, not yet confirmed

5

INACTIVE

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

Table 3. 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 4. 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 5. 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 6. 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 7. 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 8. 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 9. Arguments
Argument Type Description

scope

String

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

Table 10. 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

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 one dhcp-range, or a running DHCP Server service on Windows.

  • Scopes are shown, but the lease list is not available — for Kea, load the lease_cmds hook 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

dhcp

Server: reading DHCP information from agents and network device drivers

poll.conf

Server: DHCP server detection during configuration poll

kea

Agent: kea subagent

dnsmasq

Agent: dnsmasq subagent

winnt.dhcp

Agent: Microsoft DHCP Server support in the winnt subagent

ndd.mikrotik

Server: MikroTik network device driver

ndd.cisco

Server: Cisco network device drivers

ndd.dell.powerconnect

Server: Dell PowerConnect / N-series network device driver