Pi-hole v5.0 is here!

After a successful beta testing and development period (many thanks to the beta testers!), we are pleased to announce the release of 5.0 for general availability!

Important notice

There are many fundamental changes between Pi-hole 4.x and 5.0 – as such, this is strictly a one way operation. Once you move from 4.x to 5.0, there is no way to go back; you will need to restore from a backup. Read all the notes before you make the jump, and make a backup!

What’s new?

Quite a lot, actually, but we’ll go over the bigger things briefly here.

Per-client blocking

This is something that users have been asking for for a long time, and we are proud to be finally able to offer this awesome feature. Groups can be created and block lists, blacklist, and whitelist can be applied to groups. Blocklists, blacklist and whitelist can all be individually enabled/disabled.

To support this new functionality, we migrated the list storage from individual files in /etc/pihole to a new gravity database in the same directory. This allows control over enabling and disabling items in the lists, and even the ability to add comments to remind you why you black/whitelisted something! Furthermore, the database will store when you initially added a domain and when you last changed it (or disabled it). You may notice that updating gravity (pihole -g) takes a little longer to run than previously, however this process normally happens in the background once a week in the early morning hours and should not disrupt your DNS service. The longer run time comes due to generating an efficient B-tree index that allows fast lookups in the database.

We added a dashboard interface (Group Management) to be able to easily use this powerful new functionality, however, there is currently no CLI interface through the pihole command. If you want to manage groups from the CLI, you’ll have to directly interact with the database. We prepared an extensive example in our official documentation showing some possible configurations once through the web interface (https://docs.pi-hole.net/database/gravity/example/) but also how to achieve the same thing through the CLI.

Custom user scripts that rely on manipulating files such as gravity.list,black.list,whitelist.txt etc. will need to be changed to interacting with the database. There is so much power in this new database, it’s worth it! And, we’re here to help, just open a discussion on our Discourse platform and we can assist with advice on how to use the new gravity database for your custom scripts. The bonus is that you will learn how to interact with a database system that is also heavily used in widespread applications such as Android (yes, the smartphone operating system!), Google’s Chrome, Firefox, many content management systems, and a lot more. You can even add this to your CV for your next letter of application, if you like.

Deep CNAME inspection

This has been a covered in a broadly discussed feature request for the ability to deeply analyze CNAME queries. This will allow Pi-hole to find whether any domain in the CNAME chain is known to be blocked. If one is found, Pi-hole can now block the original query. The feature defaults to being enabled but can be disabled with an FTL config option (CNAME_DEEP_INSPECT=false). Note that if you explicitly whitelist a domain, the domain will be retrieved regardless of whether the CNAME trail leads to a blocked domain (whitelist always takes precedence).

Other notable new features

• Improved graphics on the dashboard (bar charts for the 24 hour history, vs the previous smoothed curves).

• Regex/wildcard support for the whitelist
• Additional information on why a domain was blocked on the query log page. For example, if a query was blocked by a regex, clicking on that status block will take you to the blocklist entry that blocked it.

• Improved parsing of imported blocklists. The gravity script will now show how many domains were not able to be imported, and provide some examples of why

• Much more efficient memory use.

• Custom host names from the web GUI through the “Local DNS Records” tab. This assigns host names to IP addresses, similarly to what can be done in the /etc/hosts file using the CLI. The mapping is stored in /etc/pihole/custom.list. Along with this change, the previous pihole -a hostrecordcommand is removed.

• Improved debug log that shows your blocklists and groups in a tabular format, including comments and enable/disable status.

• Slightly changed order of precedence in blocking. The precedence is now:
  • Exact Whitelist
  • Regex Whitelist
  • Exact Blacklist
  • Blocklist domains (AKA gravity)
  • Regex Blacklist
• Improved teleporter function. More settings are exported, and there are additional options for import from a teleporter file.
• Pi-hole no longer changes the nameserver assigned to the Pi (in /etc/resolv.conf). The existing nameserver settings for the Pi-hole host are respected and unchanged.
• IPv6 support added to the network table. Note: this network overview is intended as a quick look at the clients on your network using available information, to help you determine if clients on the network are using Pi-hole for DNS. It is not intended to be a network management tool.
• Network table can be flushed from the admin GUI.
• Additional FTL configuration options to reflect the new database capabilities.
• Changed the blocklists offered at initial install (some of the previous blocklists are no longer maintained).
• Embedded dnsmasq version has been updated to 2.81. See here for details on that.
• Add an FTL variant for Raspberry Pi 1 and 0 editions using a qemu armel docker image.
• Add a self-contained FTL variant using musl on Alpine Linux. This binary does not depend on glibc in any way.

And, of course, also a larger number of small tweaks, improvements and some fixed bugs.

To update to this new version from version 4.x, run pihole -up. If you have been running the 5.0 beta release, run pihole checkout master to move from the beta to the master branch.

As there are also changes to the web interface in this version, you may need to clear your browser cache to ensure you can see the new changes. Usually CTRL+F5 will do the trick