unbound module

cmd/godplugin/main.go

@@ -42,6 +42,7 @@ import (
 	_ "github.com/netdata/go.d.plugin/modules/solr"
 	_ "github.com/netdata/go.d.plugin/modules/springboot2"
 	_ "github.com/netdata/go.d.plugin/modules/tengine"
+	_ "github.com/netdata/go.d.plugin/modules/unbound"
 	_ "github.com/netdata/go.d.plugin/modules/vcsa"
 	_ "github.com/netdata/go.d.plugin/modules/vsphere"
 	_ "github.com/netdata/go.d.plugin/modules/weblog"

config/go.d/unbound.conf

@@ -0,0 +1,136 @@
+# netdata go.d.plugin configuration for unbound
+#
+# This file is in YaML format. Generally the format is:
+#
+# name: value
+#
+# There are 2 sections:
+#  - GLOBAL
+#  - JOBS
+#
+#
+# [ GLOBAL ]
+# These variables set the defaults for all JOBs, however each JOB may define its own, overriding the defaults.
+#
+# The GLOBAL section format:
+# param1: value1
+# param2: value2
+#
+# Currently supported global parameters:
+#  - update_every
+#    Data collection frequency in seconds. Default: 1.
+#
+#  - autodetection_retry
+#    Re-check interval in seconds. Attempts to start the job are made once every interval.
+#    Zero means not to schedule re-check. Default: 0.
+#
+#  - priority
+#    Priority is the relative priority of the charts as rendered on the web page,
+#    lower numbers make the charts appear before the ones with higher numbers. Default: 70000.
+#
+#
+# [ JOBS ]
+# JOBS allow you to collect values from multiple sources.
+# Each source will have its own set of charts.
+#
+# IMPORTANT:
+#  - Parameter 'name' is mandatory.
+#  - Jobs with the same name are mutually exclusive. Only one of them will be allowed running at any time.
+#
+# This allows autodetection to try several alternatives and pick the one that works.
+# Any number of jobs is supported.
+#
+# The JOBS section format:
+#
+# jobs:
+#   - name: job1
+#     param1: value1
+#     param2: value2
+#
+#   - name: job2
+#     param1: value1
+#     param2: value2
+#
+#   - name: job2
+#     param1: value1
+#
+#
+# [ List of JOB specific parameters ]:
+#  - address
+#    Server address.
+#    Syntax:
+#      address: 127.0.0.1:8953
+#      address: /var/run/unbound.sock
+#
+#  - timeout
+#    Connection/read/write/ssl handshake timeout.
+#    Syntax:
+#      timeout: 1
+#
+#  - conf_path
+#    Absolute path to the unbound configuration file. Module uses the file to autodetect 'address', 'cumulative',
+#    'use_tls', 'tls_cert' and 'tls_key' parameters.
+#    To disable parameters auto detection set it to empty string ("").
+#    Syntax:
+#      conf_path: /path/to/unbound.conf
+#
+#  - cumulative
+#    Statistics collection mode. Should have the same value as the `statistics-cumulative` parameter in the unbound
+#    configuration file.
+#    Syntax:
+#      cumulative: yes/no
+#
+#  - use_tls
+#    Whether to use or not TLS.
+#    Syntax:
+#      use_tls: yes/no
+#
+#  - tls_skip_verify
+#    Whether to skip verifying server's certificate chain and hostname.
+#    Syntax:
+#      tls_skip_verify: yes/no
+#
+#  - tls_cert
+#    Client tls certificate.
+#    Syntax:
+#      tls_cert: path/to/cert.pem
+#
+#  - tls_key
+#    Client tls key.
+#    Syntax:
+#      tls_key: path/to/key.pem
+#
+#
+# [ JOB defaults ]:
+#  address: 127.0.0.1:8953
+#  timeout: 1
+#  conf_path: /etc/unbound/unbound.conf
+#  cumulative: no
+#  use_tls: yes
+#  tls_skip_verify: yes
+#  tls_cert: /etc/unbound/unbound_control.pem
+#  tls_key: /etc/unbound/unbound_control.key
+#
+#
+# [ JOB mandatory parameters ]:
+#  - name
+#  - address
+#
+# ------------------------------------------------MODULE-CONFIGURATION--------------------------------------------------
+# [ GLOBAL ]
+# update_every: 1
+# autodetection_retry: 0
+# priority: 70000
+#
+#
+# [ JOBS ]
+jobs:
+  - name: local
+    address: 127.0.0.1:8953
+    timeout: 1
+    conf_path: /etc/unbound/unbound.conf
+    cumulative: no
+    use_tls: yes
+    tls_skip_verify: yes
+    tls_cert: /etc/unbound/unbound_control.pem
+    tls_key: /etc/unbound/unbound_control.key

modules/unbound/README.md

@@ -0,0 +1,131 @@
+# unbound
+
+This module monitors one or more [`Unbound`](https://nlnetlabs.nl/projects/unbound/about/) servers, depending on your configuration.
+
+## Requirements
+
+-   `Unbound` with enabled `remote-control` interface (see [unbound.conf](https://nlnetlabs.nl/documentation/unbound/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
+
+## Charts
+
+Module produces following summary charts:
+
+-   Received Queries in `queries`
+-   Rate Limited Queries in `queries`
+-   DNSCrypt Queries in `queries`
+-   Cache Statistics in `events`
+-   Cache Statistics Percentage in `events`
+-   Cache Prefetches in `prefetches`
+-   Replies Served From Expired Cache in `replies`
+-   Replies That Needed Recursive Processing in `replies`
+-   Time Spent On Recursive Processing in `milliseconds`
+-   Request List Usage in `queries`
+-   Current Request List Usage in `queries`
+-   Request List Jostle List Events in `queries`
+-   TCP Handler Buffers in `buffers`
+-   Uptime `seconds`
+
+If `extended-statistics` is enabled:
+
+-   Queries By Type in `queries`
+-   Queries By Class in `queries`
+-   Queries By OpCode in `queries`
+-   Queries By Flag in `queries`
+-   Replies By RCode in `replies`
+-   Cache Items Count in `items`
+-   Cache Memory in `KB`
+-   Module Memory in `KB`
+-   TCP and TLS Stream Waif Buffer Memory in `KB`
+
+Per thread charts (only if number of threads > 1):
+
+-   Received Queries in `queries`
+-   Rate Limited Queries in `queries`
+-   DNSCrypt Queries in `queries`
+-   Cache Statistics in `events`
+-   Cache Statistics Percentage in `events`
+-   Cache Prefetches in `prefetches`
+-   Replies Served From Expired Cache in `replies`
+-   Replies That Needed Recursive Processing in `replies`
+-   Time Spent On Recursive Processing in `milliseconds`
+-   Request List Usage in `queries`
+-   Current Request List Usage in `queries`
+-   Request List Jostle List Events in `queries`
+-   TCP Handler Buffers in `buffers`
+
+
+## Configuration
+
+This Unbound collector only needs the `address` to aserver's `remote-control` interface if TLS is disabled or `address` is 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
+-   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:
+
+```yaml
+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: yes
+
+  - name: socket
+    address: /var/run/unbound.sock
+```
+
+For all available options, please see the module [configuration file](https://github.com/netdata/go.d.plugin/blob/master/config/go.d/unbound.conf).
+
+
+## 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.
+
+Check the module debug output.
+Run following command as `netdata` user:
+
+> ./go.d.plugin -d -m unbound
+
+---