eko/pihole-exporter eko/pihole-exporter

  • Stars
    star
    729
  • Rank 60,010 (Top 2 %)
  • Language
    Go
  • License
    MIT License
  • Created about 5 years ago
  • Updated about 1 year ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
eko/pihole-exporter
github

eko

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Prometheus exporter for PI-Hole's Raspberry PI ad blocker

PI-Hole Prometheus Exporter

Build/Push (master) GoDoc GoReportCard

This is a Prometheus exporter for PI-Hole's Raspberry PI ad blocker.

Grafana dashboard

Available Grafana Dasboards:

Prerequisites

Installation

Download binary

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

Using Docker

The exporter is also available as a Docker image. 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

$ 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' \
  -p 9617: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' \
  -p 9617: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' \
  -p 9617: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:

$ go install github.com/eko/pihole-exporter@latest
# 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):

$ 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

$ ./pihole_exporter -pihole_hostname 192.168.1.10 -pihole_password azerty

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

$ 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
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:

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

Available CLI options

# 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)

# Address to be used for the exporter
  -bind_addr string (optional) (default "0.0.0.0")

# 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

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

More Repositories

1

gocache

β˜”οΈ A complete Go cache library that brings you multiple ways of managing your caches
Go
1,803
star
2

monday

⚑️ A dev tool for microservice developers to run local applications and/or forward others from/to Kubernetes SSH or TCP
Go
1,315
star
3

docker-symfony

Run a Symfony application using Docker & docker-compose
Dockerfile
1,299
star
4

authz

πŸ›‘οΈ Authorization backend that comes with a UI for RBAC and ABAC permissions
Go
158
star
5

FeedBundle

A Symfony bundle to build RSS feeds from your entities
PHP
138
star
6

monday-app

A GUI application for Monday original CLI application: https://github.com/eko/monday
JavaScript
51
star
7

tado-exporter

A Prometheus exporter for tado smart heating solution
Rust
48
star
8

GoogleTranslateBundle

A Symfony bundle to deals with Google Translate API
PHP
44
star
9

gofast

A simple micro-framework written in Go
Go
39
star
10

graphql-go-structure

An example of a graphql-go based structured project.
Go
28
star
11

graphql-go-upload

A middleware for GraphQL-Go to allow file upload and field data using multipart/form-data in mutations
Go
19
star
12

slackbot

This is a Slack Robot written in Go.
Go
15
star
13

book

A simple pandoc and markdown template repository for writing a book
Makefile
12
star
14

dotfiles

My personal configuration files
Vim Script
11
star
15

InstagramBundle

A Symfony bundle to interact with Instagram API
PHP
9
star
16

foREST

RESTful PHP 5.3 API Light Framework
PHP
8
star
17

git-notifier

A Golang Git notifier for Mac OS X.
Go
5
star
18

flowbot

A Flowdock robot library written in Go
Go
3
star
19

vagrant-vm

Puppet
2
star
20

python-websocket

A Python WebSocket server
Python
2
star
21

atom-pull-request

This package allows you to quickly prepare your pull request by driving you directly on your pull request creation page of your current Git project and by pre-defining source/target branches.
JavaScript
2
star
22

SonataDatagridBundle

This is a development repository
PHP
1
star
23

authz-php-sdk

Authz PHP SDK
PHP
1
star