The team behind the Pi-Hole ad-blocker has released a beta of Pi-Hole v. 5. The two big changes in this beta are (1) the introduction of per-client ad-blocking, and (2) the introduction of a Custom DNS option within the GUI itself. Per-client blocking allows a user to set different rules for, say, his iMac that for, say, his Apple TV. Custom DNS allows a user to set local DNS rules for his network without the need for a workaround. In our view, addition of these features changes Pi-Hole from a tool that primarily blocks ads into an all-around DNS manager that also happens to block ads. Bit by bit, Pi-Hole is making itself indispensable.
The upgrade process went smoothly for us (and it is an upgrade process; you can't install the beta from scratch). Nevertheless, we quickly ran into a series of error messages when trying to make changes through the GUI. Specifically, when trying to whitelist, blacklist, or change the per-client rules, we were met with the following message: "Error, something went wrong! While executing: attempt to write a readonly database":
With some help from the team at Pi-Hole, we discovered that this was the result of our running NGINX as a reverse proxy, instead of using the default
lighttpd. This post explains how those who are running both NGINX and Pi-Hole 5 Beta can fix the issue.
For the sake of this guide, we’ll assume that:
- You are familiar with SSH, with the Raspberry Pi software, with Nginx, and with how reverse proxies work
- You are already running Pi-Hole
WAIT The team behind Pi-Hole has made it extremely clear that once an installation has been upgraded to this beta, it cannot be downgraded. Ever. As such, before you start make sure that you have:
- Made a copy of your Pi’s SD card
- Backed up the data in Pi-Hole using the
Do not install this beta if you are operating in a mission critical environment.
To upgrade to the beta, SSH into your Pi and run these three lines:
echo "release/v5.0" | sudo tee /etc/pihole/ftlbranch pihole checkout core release/v5.0 pihole checkout web release/v5.0
Because you already have both Pi-Hole and your Nginx reverse proxy set up, you should be able to access the beta in exactly the same way as you accessed the older version.
The error message noted above is caused by a permissions mismatch. Unless you have changed it, the default Nginx user is
www-data and the user and group for the Pi-Hole install is
pihole:pihole. As such, make changes through the admin interface, we need to add the
www-data user into the
We can do that by running:
sudo adduser www-data pihole
Naturally, if you have changed the users or groups at any stage, this will not work. To find out which user Nginx is using, you can run:
grep user /etc/nginx/nginx.conf
And to find out which user and group Pi-Hole is using, you can run:
On some systems, a simple reboot of Nginx will suffice to update the permissions and get rid of the errors. In our case, we needed to reboot the Pi completely and to clear the cache in our browser before it worked.
One response to “Run Pi-Hole 5 Beta Behind an NGINX Reverse Proxy”
Hey, Dan from Pi-hole here:
We have some documentation at https://docs.pi-hole.net and that is open sourced at https://github.com/pi-hole/docs. Please feel free to add this to the documentation if you'd like.
Side note: Love the header image! I'm out in SoCal (Orange County) so I see the influence!