PiHole and Grafana "Tutorial"

"Tutorial" May 31, 2019

So after setting up some metric collection wizardry in other places, I wondered what the hell else I could gather in my house. Without malice in my heart, I began to scour the internet for idea's and I managed to stumble across a wonderful little script for collecting PiHole metrics and pushing them to Grafana. If you've read my previous "tutorial" you'll know that displaying influxDB data in Grafana is a rather simple process once you've done the legwork to actually feed that data into influx.

You can find the script at: https://github.com/janw/pi-hole-influx

He details the installation process there but if you prefer some sarcasm and lovely commands then please... do continue reading!

So what you going to need for this?

  • Firstly, a Pi would come in handy, with PiHole already installed but it's not a requirement to have that setup. I use to run PiHole on my UnRaid system with docker until I realised my internet died everytime I had to reboot my server. Not exactly a massive issue, but still having a seperate device controlling all that took that out of the equation and allowed me to add some other sensing jim pokery to the Pi which was another rather cool process I'll more than likely be writing up at some point.
  • Secondly, we will need Python3 installed somewhere, this can be on the Pi itself (as this tutorial follows) or another system you've already got running. Keeping it all on the Pi for myself just simplified the process.
  • Thirdly, that we are running on a debian based system with apt/apt-get installed.

So, first of all, we are going to SSH into our Pi/instance, and if you're using Putty like me you'll see the following screen. Results will certainly vary depending on the system you're using.

PiHole Command Line

Type the following commands into the CLI (Command Line Interface) to get this fat lady rolling.

Make sure your debian repositories are up to date:
sudo apt update
Install Python3 and Git onto your system. The -y tag just auto accepts any queries the process may require answering:
sudo apt install git python3-pip -y

Next we need to pull the script from github, some commands here may be slightly different on your system, because you know... Linux is anything but consistent across its variations. As far as I know though, all these debian installs use ~/ to designate home so for simplicity sake we'll stick to configuring everything from there.

Clone the repo into your local home folder:
git clone https://github.com/janw/pi-hole-influx.git ~/pi-hole-influx
Let's change places into the folder we just created:
cd ~/pi-hole-influx
Next we need to make sure the script has all the dependancies it requires. Thank fully it's better than PHP applications if anyone's installed dependancies for those. We get a lovely text file with all the requirements and versions which we can install with:
pip3 install -r requirements.txt
Copy the example user file so we can edit our specific configuration:
cp user.toml.example user.toml
Now we need to edit the config for our setup. Use whatever CLI based application you'd like, I prefer nano but I know there are some heathens out there who like 'vi':
nano user.toml

Sweet, if you've got this far... then there's still further to go.

The config file uses toml syntax if you're familiar with it, this should be an absolute breeze for you. If you're not, like me, and you seriously can't be bothered learning all the many different syntaxes out there then we can just use my example which I skillfully edited from the example provided in the git. Anything in [BRACKETS] will need to be edited for your setup.

Writers Note: I'm not going to detail how to create a InfluxDB database here, it's a simple 2 command process but you will need an active one to send the data to. If you need help with this you can check here:



influxdb_host = "[INFLUXDB IP ADDRESS]"
influxdb_port = "8086"
influxdb_database = "[NAME OF INFLUXDB]"
# influxdb_username = "[INFLUXDB USER]"
# influxdb_password = "[INFLUXDB PASSWORD]"

request_timeout = 10
reporting_interval = 30


If your installing this on another system that doesn't have your PiHole instance running you will need to use:

instances="pihole=http://[PIHOLE IP ADDRESS]/admin/api.php"

Because the developer is a wonderful person too, he gave the ability to track multiple PiHole instances if you have them.

instances={pihole="http://[PIHOLE IP ADDRESS]/admin/api.php", second instance="http://[PIHOLE IP ADDRESS]/admin/api.php"}
instances=["http://[PIHOLE IP ADDRESS]/admin/api.php", "http://[PIHOLE IP ADDRESS]/admin/api.php"]

For the setup, that's it! We are done, complete and if you wanna double check all is working well then you can use the following command to test.

python3 piholeinflux.py

Just please be aware that if you haven't got anyway of viewing the data bar Grafana you're not going to see anything. It will check the files syntax at the very least and throw up any typo's you might have made.

"Bar" is Yorkshire slang for apart from, if you didn't know I hail from Great Britain, in North Yorkshire. Expect more, it's engrained in me!

If you've run the above command to test, then press CTRL + C to cancel it so we can setup the systemd command. The systemd command will allow you to use your script like any other debian application with, start, stop, status, restart, reload commands.

The developer thankfully already has a systemd file ready to just copy into your system folder and activate. The below commands will action this.

Create a symlink for the pre-made systemd service file:
sudo ln -s /home/pi/pi-hole-influx/piholeinflux.service /etc/systemd/system/
Reload the systemd service to pick up our new file:
sudo systemctl --system daemon-reload
Enable our new service:
sudo systemctl enable piholeinflux.service
Starts our new service:
sudo systemctl start piholeinflux.service

sudo systemctl status piholeinflux.service

The last command for status will just give us back a status update of the serivce we have just created and started. You should hopefully see the below which means we are all setup!

● piholeinflux.service - Pi-hole-Influx - Send Pi-hole statistics to InfluxDB for visualization
   Loaded: loaded (/home/pi/pi-hole-influx/piholeinflux.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2018-06-22 19:03:56 UTC; 10min ago
     Docs: https://github.com/janw/pi-hole-influx
 Main PID: 21329 (python)
   Status: "Reported to InfluxDB at 2018-06-22 19:14:09 +0000"
   CGroup: /system.slice/piholeinflux.service
           └─21329 /usr/bin/python /home/pi/pi-hole-influx/piholeinflux.py

Setting Up Grafana

The graph I enabled above is available on Grafana's dashboard repository at the following link: https://grafana.com/dashboards/6603

That's probably the easiest way, there is also a dashboard.json file included you can use to import it too.

After importing the dashboard you just need to go add your influxDB in settings, and then edit each graph/single stat and select it from the drop down.


Seriously can't thank the python developer enough for that little script! I had found various other scripts but they were not as straight forward to setup like this was and some only worked for a single instance of PiHole.
I'll be completely honest here as well (because I'm never honest if I state that?) and state I barely ever check this... Still, for someone who's learning the in's and out's of data aggregation and display it was worthwhile just for the setup experience.

Here's the full screen shot as my lovely theme decided 'cover' was a good way to display a responsive image.

My Grafana PiHole Graph

James Mackay

Hi I'm James, Thanks for visiting and having a read of my stuff! Updates will be sparse for now, but I'll be spending more time on this as I get it!