Pi-hole V6 Beta Testing

Originally published at: Pi-hole V6 Beta Testing – Pi-hole

It’s no secret that we’ve been working on the next iteration of Pi-hole for quite some time now (Nearly four years!). You may have seen mentions of v6.0 floating around on our Github, Discourse, or Reddit channels.

Today we’re looking to ask some of the more brave users to help us test and troubleshoot it

Read first: Please do not run this if you are not comfortable with digging into any issues that may arise. That said, we would like to have some support in making sure we have every imaginable configuration covered before release. Pi-hole can already do so much, it is almost impossible to test all features ourselves properly.

It must be stressed that as there are many fundamental changes, updating from Pi-hole 5.x to 6.0 is strictly a one way operation.

The only way to revert back to master from the beta will be to restore from an earlier backup.
If you are using a Raspberry Pi, it may be worth taking an image of your SD card first, or at least make a backup copy of the directory /etc/pihole, it is also advised you take a backup of your config via the teleporter function in the web interface

Please use the “Beta 6.0” Category on our Discourse Forum to discuss the beta/report any findings. We will try to look into any arising issues ASAP and provide solutions in due time wherever possible

With that in mind…

What’s new?

Quite a bit, but lets start with:

A new REST API and webserver directly embedded into the pihole-FTL binary

With that, we’re dropping the lighttpd and php from the dependencies, which should make the a Pi-hole installation much smaller in footprint. The API Documentation is underway, and the binary itself also ships with up to date documentation – an example of which can be found here. In a user environment, this would be found at http://pi.hole/api/docs

The embedded webserver is civetweb

Most of the core functionality of the web interface is now handled via this new API, and includes many optimisations such as server side pagination of the query log. Any remaining php-like functionality has been migrated to lua, which has been fully embedded inside the pihole-FTL binary for some time now.

Developers of third party tools/apps will want to take a look at the documentation mentioned above to get their tools/apps ready for the next version

Subscribed allowlists (Antigravity)

This has been on the feature request list for a while now (another one here), and is a recent addition to our v6 changes. This extends our recent work in allowing for ABP-style blocklists to be used. Subscribed allow lists will only ever override entries in a subscribed blocklist. If you have a individual domain marked as denied/denied regex, then that will continue to be blocked.

Consolidated settings files

/etc/pihole/setupVars.conf? /etc/pihole/pihole-FTL.conf?/etc/dnsmasq.d/01-pihole.conf? We now have a single file in /etc/pihole/pihole.toml. Just change the settings in this file and FTL will know what to do with them. What’s better, is that this file is richly commented, so you know exactly what you’re changing.

Server-side pagination of the query log

With the old php-based API, the query log page has been a bottleneck for most users experience. This is because historically we have loaded the entire query log into memory in order to display it on screen, which can get very painful on old hardware! With the new FTL API results for the query log are loaded 1 page at a time, which makes for a much much faster experience when browsing


Redesigned settings menu in the web interface

Web interface settings have been split into different levels of Basic, Advanced, and Expert. Depending on which mode you have selected, different settings will be available to you to change. For example, if you choose Expert and then select All Settings, you can see every available setting along with a full description of what it does.

HTTPS support baked into FTL

You can, of course, use a reverse proxy to handle HTTPS for your web interface, but FTL can also handle HTTPS connections. You can provide your own certificates, but FTL will also generate a self signed one if none is provided.

Docker image now based on Alpine

This is something that people have asked about for a while – mostly for image size reasons, but really if we can make it work in a docker alpine environment, that then opens up the possibility of supporting more systems in future.

There is still a lot of work that needs to be done on the image, but it can be found at tag :development-v6 for those looking to try it out. As it stands, it “works”, but it is not a drop in replacement for the current latest image – as such environment variables etc will have changed, and the documentation will evolve as the image does. The Readme file on the development-v6 branch has some relevant information already.

FTLCONF_ environment variables need to follow the new config schema. As an example, setting the web password would be FTLCONF_webserver_api_password: 'mysecurepassword'. This is the preferred way of setting config values (vs manually editing the toml file/using the web interface) This may change/evolve over time.

When can we expect a full release?

“When it’s ready” and/or Soon™. There is still a lot to do to make this stable enough to consider it releasable, our project board for this can be found on Github, but we work on this in our free time as and when our busy schedules allow for it.

How can we help?

Glad you asked! We really must stress that testing these branches is entirely at your own risk and only for those that are comfortable digging into any potential issues and, if you’re able, dig into the code and propose potential solutions/improvements. Feeling more adventurous? Roll up your sleeves and contribute code via a Pull Request, we don’t bite!

If you’re not into testing beta code, but like what we’re doing – please feel free (but certainly not obligated!) to throw a little money our way. Pi-hole is a community driven project, and your support helps us to continue to develop, provide technical support and give back to the community.

I’ve had enough of reading everything above, how do I run this?

To avoid any potential data loss, it may be preferable to try this as a fresh installation/container. For a bare metal fresh-install of v6, first install v5 in the normal way (curl -sSL https://install.pi-hole.net | bash) and then follow the commands below to switch to the v6 branches. For a container, just start a new container with fresh volumes.

The safest way to just try this out is using Docker and the :development-v6 tag. However, if you prefer bare metal then:

echo "development-v6" | sudo tee /etc/pihole/ftlbranch 
pihole checkout core development-v6
pihole checkout web development-v6

Please Note:
There is not currently any code in the installer/updater to remove/disable lighttpd or php, and it is unlikely that there will be – the last thing we want to do is squish peoples running webservers if they are using it for anything other than Pi-hole. You will need to remove/disable these yourself if you no longer need them

If lighttpd is still running on your system and listening on port 80, then FTL will start on port 8080 for http traffic. If you wish for it to be on port 80, or any other port, first stop/remove lighttpd and configure FTL’s listening port. For docker, do this with the environment variable FTLCONF_webserver_port