github.com/netdata/go.d.plugin@v0.58.1/modules/pihole/integrations/pi-hole.md (about) 1 <!--startmeta 2 custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/modules/pihole/README.md" 3 meta_yaml: "https://github.com/netdata/go.d.plugin/edit/master/modules/pihole/metadata.yaml" 4 sidebar_label: "Pi-hole" 5 learn_status: "Published" 6 learn_rel_path: "Data Collection/DNS and DHCP Servers" 7 most_popular: False 8 message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE" 9 endmeta--> 10 11 # Pi-hole 12 13 14 <img src="https://netdata.cloud/img/pihole.png" width="150"/> 15 16 17 Plugin: go.d.plugin 18 Module: pihole 19 20 <img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" /> 21 22 ## Overview 23 24 This collector monitors Pi-hole instances using [PHP API](https://github.com/pi-hole/AdminLTE). 25 26 The data provided by the API is for the last 24 hours. All collected values refer to this time period and not to the 27 module's collection interval. 28 29 30 31 32 This collector is supported on all platforms. 33 34 This collector supports collecting metrics from multiple instances of this integration, including remote instances. 35 36 37 ### Default Behavior 38 39 #### Auto-Detection 40 41 This integration doesn't support auto-detection. 42 43 #### Limits 44 45 The default configuration for this integration does not impose any limits on data collection. 46 47 #### Performance Impact 48 49 The default configuration for this integration is not expected to impose a significant performance impact on the system. 50 51 52 ## Metrics 53 54 Metrics grouped by *scope*. 55 56 The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels. 57 58 59 60 ### Per Pi-hole instance 61 62 These metrics refer to the entire monitored application. 63 64 This scope has no labels. 65 66 Metrics: 67 68 | Metric | Dimensions | Unit | 69 |:------|:----------|:----| 70 | pihole.dns_queries_total | queries | queries | 71 | pihole.dns_queries | cached, blocked, forwarded | queries | 72 | pihole.dns_queries_percentage | cached, blocked, forwarded | percentage | 73 | pihole.unique_clients | unique | clients | 74 | pihole.domains_on_blocklist | blocklist | domains | 75 | pihole.blocklist_last_update | ago | seconds | 76 | pihole.unwanted_domains_blocking_status | enabled, disabled | status | 77 | pihole.dns_queries_types | a, aaaa, any, ptr, soa, srv, txt | percentage | 78 | pihole.dns_queries_forwarded_destination | cached, blocked, other | percentage | 79 80 81 82 ## Alerts 83 84 85 The following alerts are available: 86 87 | Alert name | On metric | Description | 88 |:------------|:----------|:------------| 89 | [ pihole_blocklist_last_update ](https://github.com/netdata/netdata/blob/master/health/health.d/pihole.conf) | pihole.blocklist_last_update | gravity.list (blocklist) file last update time | 90 | [ pihole_status ](https://github.com/netdata/netdata/blob/master/health/health.d/pihole.conf) | pihole.unwanted_domains_blocking_status | unwanted domains blocking is disabled | 91 92 93 ## Setup 94 95 ### Prerequisites 96 97 No action required. 98 99 ### Configuration 100 101 #### File 102 103 The configuration file name for this integration is `go.d/pihole.conf`. 104 105 106 You can edit the configuration file using the `edit-config` script from the 107 Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory). 108 109 ```bash 110 cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata 111 sudo ./edit-config go.d/pihole.conf 112 ``` 113 #### Options 114 115 The following options can be defined globally: update_every, autodetection_retry. 116 117 118 <details><summary>Config options</summary> 119 120 | Name | Description | Default | Required | 121 |:----|:-----------|:-------|:--------:| 122 | update_every | Data collection frequency. | 5 | no | 123 | autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no | 124 | url | Server URL. | http://127.0.0.1 | yes | 125 | setup_vars_path | Path to setupVars.conf. This file is used to get the web password. | /etc/pihole/setupVars.conf | no | 126 | timeout | HTTP request timeout. | 5 | no | 127 | username | Username for basic HTTP authentication. | | no | 128 | password | Password for basic HTTP authentication. | | no | 129 | proxy_url | Proxy URL. | | no | 130 | proxy_username | Username for proxy basic HTTP authentication. | | no | 131 | proxy_password | Password for proxy basic HTTP authentication. | | no | 132 | method | HTTP request method. | GET | no | 133 | body | HTTP request body. | | no | 134 | headers | HTTP request headers. | | no | 135 | not_follow_redirects | Redirect handling policy. Controls whether the client follows redirects. | no | no | 136 | tls_skip_verify | Server certificate chain and hostname validation policy. Controls whether the client performs this check. | no | no | 137 | tls_ca | Certification authority that the client uses when verifying the server's certificates. | | no | 138 | tls_cert | Client TLS certificate. | | no | 139 | tls_key | Client TLS key. | | no | 140 141 </details> 142 143 #### Examples 144 145 ##### Basic 146 147 A basic example configuration. 148 149 <details><summary>Config</summary> 150 151 ```yaml 152 jobs: 153 - name: local 154 url: http://127.0.0.1 155 156 ``` 157 </details> 158 159 ##### HTTPS with self-signed certificate 160 161 Remote instance with enabled HTTPS and self-signed certificate. 162 163 <details><summary>Config</summary> 164 165 ```yaml 166 jobs: 167 - name: local 168 url: https://203.0.113.11 169 tls_skip_verify: yes 170 password: 1ebd33f882f9aa5fac26a7cb74704742f91100228eb322e41b7bd6e6aeb8f74b 171 172 ``` 173 </details> 174 175 ##### Multi-instance 176 177 > **Note**: When you define multiple jobs, their names must be unique. 178 179 Collecting metrics from local and remote instances. 180 181 182 <details><summary>Config</summary> 183 184 ```yaml 185 jobs: 186 - name: local 187 url: http://127.0.0.1 188 189 - name: remote 190 url: http://203.0.113.10 191 password: 1ebd33f882f9aa5fac26a7cb74704742f91100228eb322e41b7bd6e6aeb8f74b 192 193 ``` 194 </details> 195 196 197 198 ## Troubleshooting 199 200 ### Debug Mode 201 202 To troubleshoot issues with the `pihole` collector, run the `go.d.plugin` with the debug option enabled. The output 203 should give you clues as to why the collector isn't working. 204 205 - Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on 206 your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`. 207 208 ```bash 209 cd /usr/libexec/netdata/plugins.d/ 210 ``` 211 212 - Switch to the `netdata` user. 213 214 ```bash 215 sudo -u netdata -s 216 ``` 217 218 - Run the `go.d.plugin` to debug the collector: 219 220 ```bash 221 ./go.d.plugin -d -m pihole 222 ``` 223 224