Skip to main content

Pi-hole collector

Pi-hole is a Linux network-level advertisement and Internet tracker blocking application which acts as a DNS sinkhole, intended for use on a private network.

This module will monitor one or more Pi-hole instances using PHP API.

The API exposed data time frame is for the last 24 hr. All collected values are for that time frame, not for the module collection interval.

Metrics

All metrics have "pihole." prefix.

MetricScopeDimensionsUnits
dns_queries_totalglobalqueriesqueries
dns_queriesglobalcached, blocked, forwardedqueries
dns_queries_percentageglobalcached, blocked, forwardedpercentage
unique_clientsglobaluniqueclients
domains_on_blocklistglobalblocklistdomains
blocklist_last_updateglobalagoseconds
unwanted_domains_blocking_statusglobalenabled, disabledstatus
dns_queries_typesglobala, aaaa, any, ptr, soa, srv, txtpercentage
dns_queries_forwarded_destinationglobalcached, blocked, otherpercentage

Configuration

Edit the go.d/pihole.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/pihole.conf

Module automatically detects Pihole web password reading setupVars.conf file. It expects to find the file in the /etc/pihole/ directory.

If you want to monitor remote instance you need to set the password in the module configuration file.

Here is an example for local and remote instances:

jobs:
- name: local
top_clients_entries: 10
top_items_entries: 10 # top permitted and top blocked domains charts

- name: remote
url: http://203.0.113.10
password: 1ebd33f882f9aa5fac26a7cb74704742f91100228eb322e41b7bd6e6aeb8f74b

- name: remote_https
url: https://203.0.113.11
password: 1ebd33f882f9aa5fac26a7cb74704742f91100228eb322e41b7bd6e6aeb8f74b
tls_skip_verify: yes # self signed certificate verification skip

For all available options please see module configuration file.

Troubleshooting

To troubleshoot issues with the pihole 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.

First, navigate to your plugins' directory, usually at /usr/libexec/netdata/plugins.d/. If that's not the case on your system, open netdata.conf and look for the setting plugins directory. Once you're in the plugin's directory, switch to the netdata user.

cd /usr/libexec/netdata/plugins.d/
sudo -u netdata -s

You can now run the go.d.plugin to debug the collector:

./go.d.plugin -d -m pihole

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