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.

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. A built-in counter metric returns 0 when valid BIND statistics omit its counter or the entire section. For example, Bind9.Requests.Rejected.ZoneTransfers returns 0 on a server that has never rejected a zone transfer.

Bind9.Other(path) reads an integer or string field of the same JSON document by its path. It returns Not supported when the field is missing, including when BIND omits a zero counter.

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 request must return HTTP 200 and a JSON document with a string json-stats-version field. 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 65535. An out-of-range port prevents the subagent from loading.

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:

  • The metric list proposes Counter 64-bit. Check the data type of existing counter DCIs and set it to Counter 64-bit if needed.

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

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. BIND omits zero counters from nsstats and zonestats. The built-in counter metrics return 0 when the counter or its entire section is missing from valid BIND statistics.

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

Counter 64-bit

Platforms

All

BIND field

nsstats/QryAuthAns

Bind9.Answers.FORMERR

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

Data Type

Counter 64-bit

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

Counter 64-bit

Platforms

All

BIND field

nsstats/QryNxrrset

Bind9.Answers.NonAuth

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

Data Type

Counter 64-bit

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

Counter 64-bit

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

Counter 64-bit

Platforms

All

BIND field

nsstats/QryRecursion

Bind9.Answers.Referral

Number of queries that resulted in a referral answer.

Data Type

Counter 64-bit

Platforms

All

BIND field

nsstats/QryReferral

Bind9.Answers.SERVFAIL

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

Data Type

Counter 64-bit

Platforms

All

BIND field

nsstats/QrySERVFAIL

Requests

Bind9.Requests.Completed.Updates

Number of completed dynamic updates.

Data Type

Counter 64-bit

Platforms

All

BIND field

nsstats/UpdateDone

Bind9.Requests.Completed.ZoneTransfers

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

Data Type

Counter 64-bit

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

Counter 64-bit

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

Counter 64-bit

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

Counter 64-bit

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

Counter 64-bit

Platforms

All

BIND field

nsstats/Requestv6

Bind9.Requests.Received.TCP

Number of requests received over TCP.

Data Type

Counter 64-bit

Platforms

All

BIND field

nsstats/ReqTCP

Bind9.Requests.Rejected.Authoritative

Number of rejected authoritative (non-recursive) queries.

Data Type

Counter 64-bit

Platforms

All

BIND field

nsstats/AuthQryRej

Bind9.Requests.Rejected.Recursive

Number of rejected recursive queries.

Data Type

Counter 64-bit

Platforms

All

BIND field

nsstats/RecQryRej

Bind9.Requests.Rejected.Updates

Number of rejected dynamic update requests.

Data Type

Counter 64-bit

Platforms

All

BIND field

nsstats/UpdateRej

Bind9.Requests.Rejected.ZoneTransfers

Number of rejected zone transfer requests.

Data Type

Counter 64-bit

Platforms

All

BIND field

nsstats/XfrRej

NOTIFY Messages

Bind9.Notifies.Received.IPv4

Number of NOTIFY messages received over IPv4.

Data Type

Counter 64-bit

Platforms

All

BIND field

zonestats/NotifyInv4

Bind9.Notifies.Received.IPv6

Number of NOTIFY messages received over IPv6.

Data Type

Counter 64-bit

Platforms

All

BIND field

zonestats/NotifyInv6

Bind9.Notifies.Sent.IPv4

Number of NOTIFY messages sent over IPv4.

Data Type

Counter 64-bit

Platforms

All

BIND field

zonestats/NotifyOutv4

Bind9.Notifies.Sent.IPv6

Number of NOTIFY messages sent over IPv6.

Data Type

Counter 64-bit

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. Integers are returned as decimal text. If the field is missing or has another type, the metric returns Not supported.

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

String

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. Use curl from the agent host to check the HTTP status and response body.

  • Some metrics are not supported — check that the BIND version provides the field (Bind9.Version needs BIND 9.11 or later) and that a Bind9.Other path points to a reported integer or string.

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.

Cannot set request URL

Check the Address and Port settings.

Call to curl_easy_perform() failed

The HTTP transfer failed. Check that named is running, the channel is configured and reachable, and the allow clause permits the agent host.

API request failed (HTTP status …​)

The subagent did not receive HTTP 200. Check the reported status and verify that the statistics channel serves JSON.

Cannot parse API response

The response body is invalid JSON.

API response is not a valid BIND statistics document

The JSON response has no string json-stats-version field. Check that the URL points to the BIND statistics channel.

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

The requested field is missing. Check the BIND version or the path passed to Bind9.Other.

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.