BIND 9 DNS Server Monitoring

NetXMS collects name server statistics from ISC BIND 9 (named). The bind9 subagent reads the statistics from the BIND statistics channel and provides them as agent metrics: query results, received and rejected requests, zone transfers, dynamic updates, NOTIFY messages, and server version and start time.

To check only that names resolve, without BIND statistics, use the agent metrics Net.Resolver.AddressByName and Net.Resolver.NameByAddress. They use the resolver of the agent host.

How It Works

Statistics Channel

BIND 9 makes its statistics available over HTTP when the statistics-channels statement is present in named.conf. The subagent requests the JSON form of the server statistics from this URL:

http://<Address>:<Port>/json/v1/server

Address and Port are parameters of the [Bind9] section in nxagentd.conf (see Configure the Agent). The subagent uses only HTTP and only the JSON format; it does not read the XML statistics or the statistics-file.

The JSON statistics channel is available in BIND 9.10 and later. BIND must be built with JSON support (the json-c library). Without it, named accepts the statistics-channels statement, but requests for the JSON URL fail. The version field, which Bind9.Version reads, is in the JSON output from BIND 9.11.

Counters

Each metric reads one field of the JSON document by its path, for example nsstats/QryAuthAns. Most metrics are BIND counters from the name server statistics (nsstats) and the zone maintenance statistics (zonestats). named keeps these counters in memory: they start at zero when named starts and only increase. To see rates, collect them with a delta calculation (see Create DCIs).

In the name server (nsstats) and zone maintenance (zonestats) sections, BIND leaves counters with the value zero out of the JSON document. The subagent cannot find such a counter, and the metric is not supported until the counter becomes non-zero. For example, on a server that never rejected a zone transfer, Bind9.Requests.Rejected.ZoneTransfers is not supported. A DCI for such a metric goes to the Not supported state and is polled at 10 times its polling interval until the counter appears (see DCI Configuration Reference).

Bind9.Other(path) reads any other field of the same JSON document by its path.

Caching

All Bind9.* metrics share one copy of the JSON document. The subagent requests the document again only when the copy is older than CacheRetentionTime seconds (default 5). DCIs of the node that are collected at about the same time therefore cause one HTTP request to named.

A failed request is also kept for CacheRetentionTime seconds: during that time all Bind9.* metrics return an error without a new request. The HTTP request times out after 10 seconds.

Enabling BIND 9 Monitoring

The agent can run on the BIND host and use the default address 127.0.0.1, or on another host that can reach the statistics channel over the network.

Configure the BIND Statistics Channel

  1. Add a statistics-channels statement to named.conf. Restrict access with the allow clause: without it, named accepts connections from any address.

    statistics-channels {
        inet 127.0.0.1 port 8053 allow { 127.0.0.1; };
    };

    If the statement has no port, BIND uses port 80.

  2. Reload the named configuration (rndc reconfig) or restart named.

  3. Check that the JSON statistics are available:

    curl http://127.0.0.1:8053/json/v1/server

    The response must be a JSON document that starts with fields such as json-stats-version and boot-time.

Configure the Agent

  1. Load the subagent in nxagentd.conf:

    SubAgent = bind9

    On Windows, you can also select the BIND subagent in the agent installer (option BIND9, see Windows Agent Installer Reference).

  2. If the statistics channel does not listen on 127.0.0.1 port 80, set the address and port in the [Bind9] section.

  3. Restart the agent.

Table 1. [Bind9] section parameters
Parameter Default Description

Address

127.0.0.1

Host name or IP address of the statistics channel. The value is inserted into the URL as is, so write an IPv6 address in square brackets, for example [::1].

Port

80

TCP port of the statistics channel. Valid values are 1 to 65534; with any other value, the subagent does not load.

CacheRetentionTime

5

Time in seconds the subagent reuses the statistics before it requests them from named again. 0 sends a request for every metric value.

Example for the statistics channel above:

SubAgent = bind9

[Bind9]
Address = 127.0.0.1
Port = 8053

Create DCIs

Create DCIs with origin NetXMS Agent on the node where the agent runs, and select the Bind9.* metrics from the metric list.

For the counters:

  • Set the data type to Counter 64-bit. The subagent returns the full 64-bit counter value, while the metric list proposes Unsigned Integer (32-bit), which is too small for a busy server.

  • Set the delta calculation to Average delta per second to get a rate, for example queries per second (see Delta Calculation Methods).

Counters that are zero are not supported until they change (see Counters).

Reference

Agent Metrics

These metrics are provided by the bind9 subagent. It reads them from the JSON server statistics of the BIND 9 statistics channel (/json/v1/server); see BIND 9 DNS Server Monitoring.

The BIND field row of each metric is the path of the field in the JSON document. Counters (nsstats/…​, zonestats/…​) are cumulative since named started. In the nsstats and zonestats sections, BIND omits counters that are zero, so a metric for such a counter is not supported until the counter becomes non-zero. The subagent returns counters as 64-bit values, although the metrics are declared as Unsigned Integer.

Server Information

Bind9.BootTime

Time when named started, as reported by BIND: UTC in ISO 8601 format, for example 2026-11-20T08:15:42.123Z (BIND 9.10 reports no milliseconds).

Data Type

String

Platforms

All

BIND field

boot-time

Bind9.ConfigTime

Time of the last configuration change in named: startup, configuration reload (for example rndc reload or rndc reconfig), or a zone added, changed, or deleted with rndc addzone, rndc modzone, or rndc delzone. Same format as Bind9.BootTime.

Data Type

String

Platforms

All

BIND field

config-time

Bind9.Version

BIND version, for example 9.20.8. BIND reports this field from version 9.11; with BIND 9.10 the metric is not supported.

Data Type

String

Platforms

All

BIND field

version

Query Results

Bind9.Answers.Auth

Number of queries that resulted in an authoritative answer.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QryAuthAns

Bind9.Answers.FORMERR

Number of queries that resulted in a FORMERR (format error) response.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QryFORMERR

Bind9.Answers.NoData

Number of queries that resulted in a NOERROR response with no data: the name exists, but has no records of the requested type.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QryNxrrset

Bind9.Answers.NonAuth

Number of queries that resulted in a non-authoritative answer.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QryNoauthAns

Bind9.Answers.NXDOMAIN

Number of queries that resulted in an NXDOMAIN response (the name does not exist).

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QryNXDOMAIN

Bind9.Answers.Recursive

Number of queries that caused the server to perform recursion to find the final answer.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QryRecursion

Bind9.Answers.Referral

Number of queries that resulted in a referral answer.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QryReferral

Bind9.Answers.SERVFAIL

Number of queries that resulted in a SERVFAIL (server failure) response.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QrySERVFAIL

Requests

Bind9.Requests.Completed.Updates

Number of completed dynamic updates.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/UpdateDone

Bind9.Requests.Completed.ZoneTransfers

Number of zone transfers that were requested from this server and completed.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/XfrReqDone

Bind9.Requests.Failed.Dropped

Number of recursive queries that the server dropped because of configured limits, such as clients-per-query, max-clients-per-query, fetches-per-zone, fetches-per-server, and rate-limit.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QryDropped

Bind9.Requests.Failed.Other

Number of query failures. BIND keeps this counter for compatibility; most failures it includes are also counted by more specific counters, such as rejected authoritative and recursive queries.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/QryFailure

Bind9.Requests.Received.IPv4

Number of requests received over IPv4. Includes requests that are not queries, such as NOTIFY and dynamic update requests.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/Requestv4

Bind9.Requests.Received.IPv6

Number of requests received over IPv6. Includes requests that are not queries, such as NOTIFY and dynamic update requests.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/Requestv6

Bind9.Requests.Received.TCP

Number of requests received over TCP.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/ReqTCP

Bind9.Requests.Rejected.Authoritative

Number of rejected authoritative (non-recursive) queries.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/AuthQryRej

Bind9.Requests.Rejected.Recursive

Number of rejected recursive queries.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/RecQryRej

Bind9.Requests.Rejected.Updates

Number of rejected dynamic update requests.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/UpdateRej

Bind9.Requests.Rejected.ZoneTransfers

Number of rejected zone transfer requests.

Data Type

Unsigned Integer

Platforms

All

BIND field

nsstats/XfrRej

NOTIFY Messages

Bind9.Notifies.Received.IPv4

Number of NOTIFY messages received over IPv4.

Data Type

Unsigned Integer

Platforms

All

BIND field

zonestats/NotifyInv4

Bind9.Notifies.Received.IPv6

Number of NOTIFY messages received over IPv6.

Data Type

Unsigned Integer

Platforms

All

BIND field

zonestats/NotifyInv6

Bind9.Notifies.Sent.IPv4

Number of NOTIFY messages sent over IPv4.

Data Type

Unsigned Integer

Platforms

All

BIND field

zonestats/NotifyOutv4

Bind9.Notifies.Sent.IPv6

Number of NOTIFY messages sent over IPv6.

Data Type

Unsigned Integer

Platforms

All

BIND field

zonestats/NotifyOutv6

Other Fields

Bind9.Other(path)

Value of any field of the JSON server statistics, selected by its path. Path elements are separated by /; a leading / is optional. The field must hold an integer or a string; the metric is not supported for objects, arrays, and fields that BIND does not report.

Examples of paths in current BIND versions:

  • nsstats/QrySuccess — queries that resulted in a successful answer (NOERROR with at least one answer record)

  • rcodes/NOERROR — responses sent, by response code

  • qtypes/AAAA — queries received, by query type

  • views/_default/resolver/stats/Queryv4 — IPv4 queries sent by the resolver of the default view

  • current-time — current time of the server

For the list of counters, see the statistics section of the BIND Administrator Reference Manual, or read the JSON document from the statistics channel.

Data Type

Unsigned Integer (string fields are returned as strings)

Platforms

All

Table 2. Arguments
Argument Type Description

path

String

Path of the field in the JSON document, up to 255 characters

Troubleshooting

Query a metric directly from the agent to see whether the subagent can read the statistics:

nxget <agent-address> Bind9.Version
  • All Bind9.* metrics are unknown to the agent — the subagent is not loaded. Check Agent.SubAgentList and the agent log; the subagent does not load if Port is out of range.

  • All Bind9.* metrics return an error — the subagent cannot read the JSON document. Check the agent log for the messages below, and check with curl from the agent host that the URL returns JSON.

  • Some metrics are not supported — the BIND counter is zero, so BIND does not report it, or the BIND version does not provide the field (Bind9.Version before BIND 9.11).

The subagent writes these messages to the agent log. After the first error, it writes no more error messages until it receives a valid JSON document again.

Message Meaning

Query URL: …​ (debug level 2)

URL built from Address and Port at agent startup.

Invalid Address/port configuration

Port is out of range; the subagent is not loaded.

Call to curl_easy_perform() failed

No HTTP connection to the statistics channel: wrong address or port, the channel is not configured, named is not running, the allow clause rejects the agent host, or the request timed out.

Cannot parse API response

The URL returned something other than JSON, for example an HTTP error page when BIND is built without JSON support.

Cannot find property "…​" (debug level 5)

The JSON document has no field with this path: the counter is zero, or the path is wrong.

Unsupported data type for property "…​" (debug level 5)

The path points to an object, array, or other value that is neither an integer nor a string.

To see debug messages, set the debug level of the tag bind9 with DebugTags in nxagentd.conf, for example DebugTags = bind9:7 (see Diagnostics). Level 7 also shows when a request is answered from the cached statistics.