pihole-exporter/README.md

# PI-Hole Prometheus Exporter

![Build/Push (master)](https://github.com/eko/pihole-exporter/workflows/Build/Push%20(master)/badge.svg)
[![GoDoc](https://godoc.org/github.com/eko/pihole-exporter?status.png)](https://godoc.org/github.com/eko/pihole-exporter)
[![GoReportCard](https://goreportcard.com/badge/github.com/eko/pihole-exporter)](https://goreportcard.com/report/github.com/eko/pihole-exporter)

This is a Prometheus exporter for [PI-Hole](https://pi-hole.net/)'s Raspberry PI ad blocker.

![Grafana dashboard](https://raw.githubusercontent.com/eko/pihole-exporter/master/dashboard.jpg)

Grafana dashboard is [available here](https://grafana.com/dashboards/10176) on the Grafana dashboard website and also [here](https://raw.githubusercontent.com/eko/pihole-exporter/master/grafana/dashboard.json) on the GitHub repository.

## Prerequisites

* [Go](https://golang.org/doc/)

## Installation

### Download binary

You can download the latest version of the binary built for your architecture here:

* Architecture **i386** [
    [Linux](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-linux-386) /
    [Windows](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-windows-386.exe)
]
* Architecture **amd64** [
    [Darwin](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-darwin-amd64) /
    [Linux](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-linux-amd64) /
    [Windows](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-windows-amd64.exe)
]
* Architecture **arm** [
    [Darwin](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-darwin-arm64) /
    [Linux](https://github.com/eko/pihole-exporter/releases/latest/download/pihole_exporter-linux-arm)
]

### Using Docker

The exporter is also available as a [Docker image](https://hub.docker.com/r/ekofr/pihole-exporter).
You can run it using the following example and pass configuration environment variables:

```
$ docker run \
  -e 'PIHOLE_HOSTNAME=192.168.1.2' \
  -e 'PIHOLE_PASSWORD=mypassword' \
  -e 'PORT=9617' \
  -p 9617:9617 \
  ekofr/pihole-exporter:latest
```

Or use PiHole's `WEBPASSWORD` as an API token instead of the password

```bash
$ API_TOKEN=$(awk -F= -v key="WEBPASSWORD" '$1==key {print $2}' /etc/pihole/setupVars.conf)
$ docker run \
  -e 'PIHOLE_HOSTNAME=192.168.1.2' \
  -e "PIHOLE_API_TOKEN=$API_TOKEN" \
  -e 'PORT=9617' \
  ekofr/pihole-exporter:latest
```

If you are running pi-hole behind https, you must both set the `PIHOLE_PROTOCOL` environment variable
as well as include your ssl certificates to the docker image as it does not have any baked in:

```
$ docker run \
  -e 'PIHOLE_PROTOCOL=https' \
  -e 'PIHOLE_HOSTNAME=192.168.1.2' \
  -e 'PIHOLE_PASSWORD=mypassword' \
  -e 'PORT=9617' \
  -v '/etc/ssl/certs:/etc/ssl/certs:ro' \
  -p 9617:9617 \
  ekofr/pihole-exporter:latest
```

A single instance of pihole-exporter can monitor multiple pi-holes instances.
To do so, you can specify a list of hostnames, protocols, passwords/API tokens and ports by separating them with commas in their respective environment variable:

```
$ docker run \
  -e 'PIHOLE_PROTOCOL="http,http,http" \
  -e 'PIHOLE_HOSTNAME="192.168.1.2,192.168.1.3,192.168.1.4"' \
  -e "PIHOLE_API_TOKEN="$API_TOKEN1,$API_TOKEN2,$API_TOKEN3" \
  -e "PIHOLE_PORT="8080,8081,8080" \
  -e 'PORT=9617' \
  ekofr/pihole-exporter:latest
```

If port, protocol and API token/password is the same for all instances, you can specify them only once:

```
$ docker run \
  -e 'PIHOLE_PROTOCOL=",http" \
  -e 'PIHOLE_HOSTNAME="192.168.1.2,192.168.1.3,192.168.1.4"' \
  -e "PIHOLE_API_TOKEN="$API_TOKEN" \
  -e "PIHOLE_PORT="8080" \
  -e 'PORT=9617' \
  ekofr/pihole-exporter:latest
```

### From sources

Optionally, you can download and build it from the sources. You have to retrieve the project sources by using one of the following way:
```bash
$ go get -u github.com/eko/pihole-exporter
# or
$ git clone https://github.com/eko/pihole-exporter.git
```

Install the needed vendors:

```
$ GO111MODULE=on go mod vendor
```

Then, build the binary (here, an example to run on Raspberry PI ARM architecture):
```bash
$ GOOS=linux GOARCH=arm GOARM=7 go build -o pihole_exporter .
```

## Usage

In order to run the exporter, type the following command (arguments are optional):

Using a password

```bash
$ ./pihole_exporter -pihole_hostname 192.168.1.10 -pihole_password azerty
```

Or use PiHole's `WEBPASSWORD` as an API token instead of the password

```bash
$ API_TOKEN=$(awk -F= -v key="WEBPASSWORD" '$1==key {print $2}' /etc/pihole/setupVars.conf)
$ ./pihole_exporter -pihole_hostname 192.168.1.10 -pihole_api_token $API_TOKEN
```

```bash
2019/05/09 20:19:52 ------------------------------------
2019/05/09 20:19:52 -  PI-Hole exporter configuration  -
2019/05/09 20:19:52 ------------------------------------
2019/05/09 20:19:52 PIHoleHostname : 192.168.1.10
2019/05/09 20:19:52 PIHolePassword : azerty
2019/05/09 20:19:52 Port : 9617
2019/05/09 20:19:52 Timeout : 5s
2019/05/09 20:19:52 ------------------------------------
2019/05/09 20:19:52 New Prometheus metric registered: domains_blocked
2019/05/09 20:19:52 New Prometheus metric registered: dns_queries_today
2019/05/09 20:19:52 New Prometheus metric registered: ads_blocked_today
2019/05/09 20:19:52 New Prometheus metric registered: ads_percentag_today
2019/05/09 20:19:52 New Prometheus metric registered: unique_domains
2019/05/09 20:19:52 New Prometheus metric registered: queries_forwarded
2019/05/09 20:19:52 New Prometheus metric registered: queries_cached
2019/05/09 20:19:52 New Prometheus metric registered: clients_ever_seen
2019/05/09 20:19:52 New Prometheus metric registered: unique_clients
2019/05/09 20:19:52 New Prometheus metric registered: dns_queries_all_types
2019/05/09 20:19:52 New Prometheus metric registered: reply
2019/05/09 20:19:52 New Prometheus metric registered: top_queries
2019/05/09 20:19:52 New Prometheus metric registered: top_ads
2019/05/09 20:19:52 New Prometheus metric registered: top_sources
2019/05/09 20:19:52 New Prometheus metric registered: forward_destinations
2019/05/09 20:19:52 New Prometheus metric registered: querytypes
2019/05/09 20:19:52 New Prometheus metric registered: status
2019/05/09 20:19:52 Starting HTTP server
2019/05/09 20:19:54 New tick of statistics: 648 ads blocked / 66796 total DNS querie
...
```

Once the exporter is running, you also have to update your `prometheus.yml` configuration to let it scrape the exporter:

```yaml
scrape_configs:
  - job_name: 'pihole'
    static_configs:
      - targets: ['localhost:9617']
```

## Available CLI options
```bash
# Hostname of the host(s) where PI-Hole is installed
  -pihole_hostname string (optional) (default "127.0.0.1")

# Password defined on the PI-Hole interface
  -pihole_password string (optional)

# Timeout to connect and retrieve data from a Pi-Hole instance
  -timeout duration (optional) (default 5s)

# WEBPASSWORD / api token defined on the PI-Hole interface at `/etc/pihole/setupVars.conf`
  -pihole_api_token string (optional)

# Port to be used for the exporter
  -port string (optional) (default "9617")
```

## Available Prometheus metrics

| Metric name                  | Description                                                                               |
|:----------------------------:|-------------------------------------------------------------------------------------------|
| pihole_domains_being_blocked | This represent the number of domains being blocked                                        |
| pihole_dns_queries_today     | This represent the number of DNS queries made over the current day                        |
| pihole_ads_blocked_today     | This represent the number of ads blocked over the current day                             |
| pihole_ads_percentage_today  | This represent the percentage of ads blocked over the current day                         |
| pihole_unique_domains        | This represent the number of unique domains seen                                          |
| pihole_queries_forwarded     | This represent the number of queries forwarded                                            |
| pihole_queries_cached        | This represent the number of queries cached                                               |
| pihole_clients_ever_seen     | This represent the number of clients ever seen                                            |
| pihole_unique_clients        | This represent the number of unique clients seen                                          |
| pihole_dns_queries_all_types | This represent the number of DNS queries made for all types                               |
| pihole_reply                 | This represent the number of replies made for all types                                   |
| pihole_top_queries           | This represent the number of top queries made by PI-Hole by domain                        |
| pihole_top_ads               | This represent the number of top ads made by PI-Hole by domain                            |
| pihole_top_sources           | This represent the number of top sources requests made by PI-Hole by source host          |
| pihole_forward_destinations  | This represent the number of forward destinations requests made by PI-Hole by destination |
| pihole_querytypes            | This represent the number of queries made by PI-Hole by type                              |
| pihole_status                | This represent if PI-Hole is enabled                                                      |


## Pihole-Exporter Helm Chart

[Link](https://github.com/SiM22/pihole-exporter-helm-chart)

This is a simple Helm Chart to deploy the exporter in a kubernetes cluster.