1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
<!--
title: "Monitor Unbound DNS servers with Netdata"
date: 2020-03-31
custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/guides/collect-unbound-metrics.md
-->
# Monitor Unbound DNS servers with Netdata
[Unbound](https://nlnetlabs.nl/projects/unbound/about/) is a "validating, recursive, caching DNS resolver" from NLNet
Labs. In v1.19 of Netdata, we release a completely refactored collector for collecting real-time metrics from Unbound
servers and displaying them in Netdata dashboards.
Unbound runs on FreeBSD, OpenBSD, NetBSD, macOS, Linux, and Windows, and supports DNS-over-TLS, which ensures that DNS
queries and answers are all encrypted with TLS. In theory, that should reduce the risk of eavesdropping or
man-in-the-middle attacks when communicating to DNS servers.
This guide will show you how to collect dozens of essential metrics from your Unbound servers with minimal
configuration.
## Set up your Unbound installation
As with all data sources, Netdata can auto-detect Unbound servers if you installed them using the standard installation
procedure.
Regardless of whether you're connecting to a local or remote Unbound server, you need to be able to access the server's
`remote-control` interface via an IP address, FQDN, or Unix socket.
To set up the `remote-control` interface, you can use `unbound-control`. First, run `unbound-control-setup` to generate
the TLS key files that will encrypt connections to the remote interface. Then add the following to the end of your
`unbound.conf` configuration file. See the [Unbound
documentation](https://nlnetlabs.nl/documentation/unbound/howto-setup/#setup-remote-control) for more details on using
`unbound-control`, such as how to handle situations when Unbound is run under a unique user.
```conf
# enable remote-control
remote-control:
control-enable: yes
```
Next, make your `unbound.conf`, `unbound_control.key`, and `unbound_control.pem` files readable by Netdata using [access
control lists](https://wiki.archlinux.org/index.php/Access_Control_Lists) (ACL).
```bash
sudo setfacl -m user:netdata:r unbound.conf
sudo setfacl -m user:netdata:r unbound_control.key
sudo setfacl -m user:netdata:r unbound_control.pem
```
Finally, take note whether you're using Unbound in _cumulative_ or _non-cumulative_ mode. This will become relevant when
configuring the collector.
## Configure the Unbound collector
You may not need to do any more configuration to have Netdata collect your Unbound metrics.
If you followed the steps above to enable `remote-control` and make your Unbound files readable by Netdata, that should
be enough. Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate
method](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) for your system. You should see Unbound metrics in your Netdata
dashboard!
If that failed, you will need to manually configure `unbound.conf`. See the next section for details.
### Manual setup for a local Unbound server
To configure Netdata's Unbound collector module, navigate to your Netdata configuration directory (typically at
`/etc/netdata/`) and use `edit-config` to initialize and edit your Unbound configuration file.
```bash
cd /etc/netdata/ # Replace with your Netdata configuration directory, if not /etc/netdata/
sudo ./edit-config go.d/unbound.conf
```
The file contains all the global and job-related parameters. The `name` setting is required, and two Unbound servers
can't have the same name.
> It is important you know whether your Unbound server is running in cumulative or non-cumulative mode, as a conflict
> between modes will create incorrect charts.
Here are two examples for local Unbound servers, which may work based on your unique setup:
```yaml
jobs:
- name: local
address: 127.0.0.1:8953
cumulative: no
use_tls: yes
tls_skip_verify: yes
tls_cert: /path/to/unbound_control.pem
tls_key: /path/to/unbound_control.key
- name: local
address: 127.0.0.1:8953
cumulative: yes
use_tls: no
```
Netdata will attempt to read `unbound.conf` to get the appropriate `address`, `cumulative`, `use_tls`, `tls_cert`, and
`tls_key` parameters.
Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate
method](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) for your system.
### Manual setup for a remote Unbound server
Collecting metrics from remote Unbound servers requires manual configuration. There are too many possibilities to cover
all remote connections here, but the [default `unbound.conf`
file](https://github.com/netdata/go.d.plugin/blob/master/config/go.d/unbound.conf) contains a few useful examples:
```yaml
jobs:
- name: remote
address: 203.0.113.10:8953
use_tls: no
- name: remote_cumulative
address: 203.0.113.11:8953
use_tls: no
cumulative: yes
- name: remote
address: 203.0.113.10:8953
cumulative: yes
use_tls: yes
tls_cert: /etc/unbound/unbound_control.pem
tls_key: /etc/unbound/unbound_control.key
```
To see all the available options, see the default [unbound.conf
file](https://github.com/netdata/go.d.plugin/blob/master/config/go.d/unbound.conf).
## What's next?
Now that you're collecting metrics from your Unbound servers, let us know how it's working for you! There's always room
for improvement or refinement based on real-world use cases. Feel free to [file an
issue](https://github.com/netdata/netdata/issues/new?assignees=&labels=bug%2Cneeds+triage&template=BUG_REPORT.yml) with your
thoughts.
|
