Skip to main content

Unbound collector

Unbound is a validating, recursive, and caching DNS resolver product from NLnet Labs.

This module monitors one or more Unbound servers, depending on your configuration.

Requirements

  • Unbound with enabled remote-control interface ( see unbound.conf)

If using unix socket:

  • socket should be readable and writeable by netdata user

If using ip socket and TLS is disabled:

  • socket should be accessible via network

If TLS is enabled, in addition:

  • control-key-file should be readable by netdata user
  • control-cert-file should be readable by netdata user

For auto-detection parameters from unbound.conf:

  • unbound.conf should be readable by netdata user
  • if you have several configuration files (include feature) all of them should be readable by netdata user

Metrics

All metrics have "vcsa." prefix.

MetricScopeDimensionsUnits
queriesglobalqueriesqueries
queries_ip_ratelimitedglobalratelimitedqueries
dnscrypt_queriesglobalcrypted, cert, cleartext, malformedqueries
cacheglobalhits, missevents
cache_percentageglobalhits, misspercentage
prefetchglobalprefetchesprefetches
expiredglobalexpiredreplies
zero_ttl_repliesglobalzero_ttlreplies
recursive_repliesglobalrecursivereplies
recursion_timeglobalavg, medianmilliseconds
request_list_usageglobalavg, maxqueries
current_request_list_usageglobalall, usersqueries
request_list_jostle_listglobaloverwritten, droppedqueries
tcpusageglobalusagebuffers
uptimeglobaltimeseconds
thread_cachethreadhits, missevents
thread_cache_percentagethreadhits, misspercentage
thread_prefetchthreadprefetchesprefetches
thread_expiredthreadexpiredreplies
thread_zero_ttl_repliesthreadzero_ttlreplies
thread_recursive_repliesthreadrecursivereplies
thread_recursion_timethreadavg, medianmilliseconds
thread_request_list_usagethreadavg, maxqueries
thread_current_request_list_usagethreadall, usersqueries
thread_request_list_jostle_listthreadoverwritten, droppedqueries
thread_tcpusagethreadusagebuffers
cache_memoryglobalmessage, rrset, dnscrypt_nonce, dnscrypt_shared_secretKB
mod_memoryglobaliterator, respip, validator, subnet, ipsecKB
mem_streamwaitglobalstreamwaitKB
cache_countglobalinfra, key, msg, rrset, dnscrypt_nonce, shared_secretitems
type_queriesglobala dimension per query typequeries
class_queriesglobala dimension per query classqueries
opcode_queriesglobala dimension per query opcodequeries
flag_queriesglobalqr, aa, tc, rd, ra, z, ad, cdqueries
rcode_answersglobala dimension per reply rcodereplies
thread_queriesglobalqueriesqueries
thread_queries_ip_ratelimitedglobalratelimitedqueries
thread_dnscrypt_queriesglobalcrypted, cert, cleartext, malformedqueries

Configuration

Edit the go.d/unbound.conf configuration file using edit-config from the Netdata config directory, which is typically at /etc/netdata.

cd /etc/netdata # Replace this path with your Netdata config directory
sudo ./edit-config go.d/unbound.conf

This Unbound collector only needs the address to a server's remote-control interface if TLS is disabled or address of unix socket. Otherwise, you need to set path to the control-key-file and control-cert-file files.

The module tries to auto-detect following parameters reading unbound.conf:

  • address
  • cumulative_stats
  • use_tls
  • tls_cert
  • tls_key

Module supports both cumulative and non-cumulative modes. Default is non-cumulative. If your server has enabled statistics-cumulative, but the module fails to auto-detect it (unbound.conf is not readable, or it is a remote server), you need to set it manually in the configuration file.

Here is an example for several servers:

jobs:
- name: local
address: 127.0.0.1:8953
use_tls: yes
tls_skip_verify: yes
tls_cert: /etc/unbound/unbound_control.pem
tls_key: /etc/unbound/unbound_control.key

- name: remote
address: 203.0.113.10:8953
use_tls: no

- name: remote_cumulative
address: 203.0.113.11:8953
use_tls: no
cumulative_stats: yes

- name: socket
address: /var/run/unbound.sock

For all available options, please see the module configuration file.

Troubleshooting

Ensure that the control protocol is actually configured correctly. Run following command as root user:

unbound-control stats_noreset

It should print out a bunch of info about the internal statistics of the server. If this returns an error, you don't have the control protocol set up correctly.

To troubleshoot issues with the unbound collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn't working.

  • Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that's not the case on your system, open netdata.conf and look for the plugins setting under [directories].

    cd /usr/libexec/netdata/plugins.d/
  • Switch to the netdata user.

    sudo -u netdata -s
  • Run the go.d.plugin to debug the collector:

    ./go.d.plugin -d -m unbound

Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.