BIND Plugin

This plugin monitors a BIND (named) nameserver. It reads the server's built-in statistics channel and reports the number of queries by record type, the response codes, and the nameserver's own query statistics, so you can see load, failures and unusual traffic on your DNS server.

Reported Metrics

The plugin reads the qtypes, rcodes and nsstats sections of the BIND JSON statistics and reports them together as one flat list of counters.

The exact counters depend on your BIND version and on what the server has done so far. A counter appears once BIND has counted at least one event of that kind.

The values are totals since BIND started, not rates. To see traffic per second, graph the change over time. If two sections have a counter with the same name, only one value is reported.

Requirements

• BIND 9.10 or later, built with JSON statistics support. This is the case for the standard packages of the common Linux distributions.
• A statistics channel enabled in BIND, see below.
• curl and jq installed and available to the agent user. For example, on Debian or Ubuntu: apt install curl jq. On RHEL-based systems: dnf install curl jq.

The plugin doesn't need root or a sudoers rule.

Configure BIND

Add a statistics-channels block to your BIND configuration, for example to /etc/bind/named.conf.options or /etc/named.conf:

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

Keep the statistics channel on localhost. It has no authentication and exposes details about your server's traffic. Listen on 127.0.0.1 and allow only 127.0.0.1, as above, and don't open the port in your firewall.

Check the configuration and apply it:

named-checkconf
rndc reconfig

Then check that the statistics are available:

curl http://localhost:8053/json | jq 'keys'

The output should be a list of sections that includes nsstats, qtypes and rcodes.

Configure the plugin

Add the following lines to the /etc/agent360-custom.ini file:

[bind]
enabled = yes
port = 8053

The plugin connects to localhost on this port, so the statistics channel has to be reachable there. The port option is required, and the plugin fails without it.

Test the plugin

Run the following command:

sudo -u agent360 agent360 test bind

The output should show the query counters. Then restart the agent for the change to take effect:

service agent360 restart

Troubleshooting

• The test fails or returns nothing. Run the plugin's command as the agent user to see where it fails:
  Bash

  sudo -u agent360 sh -c 'curl -s http://localhost:8053/json | jq ".qtypes * .rcodes * .nsstats"'

  • If it says curl or jq isn't found, install them.
  • If it prints nothing, the statistics channel isn't reachable. Check the statistics-channels block, that you ran rndc reconfig, and that the port matches the port option.
  • If it prints null, your BIND version doesn't provide these sections in /json. Check the output of curl http://localhost:8053/json.
• The plugin returns an error about the port option. Add port = ... to the [bind] section.
• A counter I expect is missing. BIND only reports counters for events that have happened. It also depends on the BIND version.
• No data in the dashboard. Make sure the [bind] section is in /etc/agent360-custom.ini, enabled = yes, and that you restarted the agent.