Recursive DNS+AD-Blocker — Part 5: unbound2influxdb2 — How to monitor your Unbound servers
In this article I will show you how to collect and send Unbound stats to an influxdb2 bucket by using a simple Python script unbound-to-influxdb2.py or my giannicostanzi/unbound2influxdb2 docker image you can find on DockerHub
This article is a lot similar to the previous one, Recursive DNS+AD-Blocker — Part 4: pihole2influxdb2 — How to monitor your Pi-hole servers, and we will see how we can monitor our unbound servers and collect data to be visualized in our Grafana dashboards.
Unbound allows you to query its server through an utility, unbound_control, and through the unbound_console Python package. As I’ve did with Pihole, I’ve built my own Python script and so I’ve chosen the unbound_console way.
This is an example of output returned by unbound (it’s not the native info returned by unbound_control, as you will see later I’ve renamed the keys and added a percent_cachehits key) and formatted with json.dumps(data, indent=4):
Collecting and Uploading data with Python
As I’ve done to collect and upload Pihole stats, I’ve built my own Python script to query unbound servers and upload formatted data to my influxdb server. You can find the whole script on GitHub, where you can find an always up-to-date version.
Script Environment Variables
The script relies on some environment variables:
INFLUX_HOST="INFLUX_IP"
INFLUX_PORT=8086
INFLUX_ORGANIZATION="influx_org"
INFLUX_BUCKET="influx_bucket"
INFLUX_SERVICE_TAG="influx_service_tag"
INFLUX_TOKEN="influx_token"
UNBOUND_HOSTS="ip1:port1:tag1:G,ip2:port2:tag2:S,ip3:port3:tag3:N"
RUN_EVERY_SECONDS=10
VERBOSE="True"
# Create this folder and the required subfolders
# (see README.md on GitHub for more info)
CONFIG_DIR="./etc/unbound"I won’t go into much detail about the variables, expecially the CONFIG_DIR which must contains certs and keys that must be used to connect to the unbound servers. You can find more details in the README.md and the source code of the script directly on https://github.com/MightySlaytanic/unbound2influxdb2
I’ve prepared a shell launcher that exports the environment variables, which are useful to embed the script in a Docker Container as I’ve did for Pihole stats, and that calls the python script:
If you pass the -t flag to the launcher script, it will pass it to unbound-to-influxdb2 and print collected data without uploading it.
Script Execution
The script runs forever querying Unbound hosts in UNBOUND_HOSTS every RUN_EVERY_SECONDS seconds.
You can run the script with -t flag in order to retrieve data from Unbound and print it in a well-formatted easy-to-read form, without uploading it to InfluxDB2. You can also view debug information by setting VERBOSE to True.
The script uses unbound_console.RemoteControl to query the unbound server:
We manipulate the returned data in order to format fields with underscores instead of dots, to make naming uniform between different versions of unbound running on our Raspberry and our Docker container (for example one version used zero_ttl instead of expired to count the number of expired elements in the cache) and to avoid errors when uploading values to influxdb2 (we force some values to floats and other to integers):
Finally, the parsed data which has ben packed into a Python Dictionary can be uploaded to InfluxDB2:
Exploring data on InfluxDB2
You will find stats measurements on your InfluxDB2 server:
As you can see all the Unbound stats and the percent_cachehits we’ve computed in our script are available in the stats measurment. You will also find the host and service as additional tags that can be used to filter queried data.
Visualizing data in Grafana
Now that you have all the data available on InfluxDB2, it is easy to enrich your Grafana dashboards with Unbound stats:
As an example, this is the Flux query I’ve used to plot the most interesting Unbound data on the Bar Gauge panel above:
unbound2influxdb2 Docker Image
If you’ve read my previous articles in this series, you surely expect me to build another Docker Image to embed the my Python script and you are right: I’ve taken the unbound-to-influxdb2.py script and embedded it in my unbound2influxdb2 Docker Image that you can download with the following command:
docker pull giannicostanzi/unbound2influxdb2:latestYou can find more info about how to setup environment variables and run this image on unbound2influxdb2 Docker Hub page.
If you want you can execute a test run with the following command, which should give the same output as unbound2influxdb2.sh -t:
docker run -t --rm \
-e INFLUX_HOST="influxdb_server_ip" \
-e INFLUX_PORT="8086" \
-e INFLUX_ORGANIZATION="org-name" \
-e INFLUX_BUCKET="bucket-name" \
-e INFLUX_TOKEN="influx_token" \
-e INFLUX_SERVICE_TAG="unbound-test" \
-e VERBOSE="true" \
-e UNBOUND_HOSTS="ip1:port1:tag_name1:enc_flag1,ip2:port2:tag_name2:enc_flag2" \
-e CONFIG_DIR="/etc/unbound" \
-v /path_to_local_folder/etc/unbound:/etc/unbound \
giannicostanzi/unbound2influxdb2 -tIf the Influx host or the unbound host runs on the same docker instance you can specify the respective container names, but this requires the unbound2influxdb2 container to be attached to the same non-default bridge network(s) of influxdb and unbound in order to have container-to-ip name resolution work as expected. For example I have this container running on my Synology NAS, attached to npm network (influxdb1container) and services network (unbound-secns1 container).
You can create the container from the CLI or by using the Synology Docker App GUI, as I’ve shown in the previous article.
The image implements an healthcheck that fails if it fails to query one of the defined unbound servers or if it fails to upload data to the influxdb2 server. You can see the status (healthy or unhealty) of the container with docker ps and if it is unhealthy you can inspect the logs with docker logs unbound2influxdb2_container_name.
Conclusions
I hope you will found this article useful, don’t forget to give a look (and maybe a star) to my unbound2influxdb2 docker image and to visit my Github page for updated scripts. If you have question, just add a comment and I’ll try to help you!
