Pi-hole, the network-wide ad-blocking solution, has recently undergone significant updates, introducing a range of new features and improvements. In this article, we will explore the latest advancements in Pi-hole v6. These include a new REST API, subscribed allowlists, consolidated settings files, server-side pagination of the query log, a redesigned settings menu, HTTPS support, and a Docker image based on Alpine. These updates aim to enhance the user experience, optimize performance, and provide greater flexibility in configuring and managing Pi-hole installations.
1. New Features and Improvements
1.1 New REST API and Embedded Webserver
The pihole-FTL binary now incorporates a REST API and a webserver, eliminating the dependency on lighttpd and PHP. This change not only reduces the installation's footprint but also improves performance. Developers can refer to the API documentation to update their third-party tools and applications accordingly.
1.2 Subscribed Allowlists (Antigravity)
Pi-hole's v6 changes introduced subscribed allowlists, allowing users to override entries in subscribed blocklists. This enhancement expands Pi-hole's functionality and provides more control over allowed domains while maintaining effective ad-blocking capabilities.
1.3 Consolidated Settings Files
Previously scattered across multiple files, Pi-hole now utilizes a single configuration file, pihole.toml, located in /etc/pihole/. This centralized approach simplifies the process of modifying Pi-hole's settings. Furthermore, it provides comprehensive documentation within the file itself.
1.4 Server-side Pagination of the Query Log
To enhance the query log browsing experience, the new FTL API incorporates server-side pagination. The previous approach loads the entire query log into memory. However, the updated method loads results one page at a time, significantly improving performance, particularly on older hardware.
1.5 Redesigned Settings Menu
The web interface's settings menu has undergone a redesign, categorizing options into Basic and Expert levels. Depending on the selected mode, users can access different settings.
1.6 HTTPS Support Baked into FTL
While users can still use a reverse proxy for HTTPS handling, Pi-hole now includes built-in support for HTTPS connections. Users can either provide their own SSL certificates or allow FTL to generate a self-signed certificate when none is available.
2. Pi-hole Development version 6 Installation
2.1. Update Pi-hole
Before upgrading, ensure your Pi-hole installation is up to date. Run the following command to update Pi-hole:
$ pihole -up
2.2 Backup Pi-hole 5.x Image
Backup your Pi-hole 5.x image from the USB stick to the local disk using the command:
$ sudo dd bs=4M if=/dev/sda | pv | dd of=pihole-bak.img && sync
This command creates a backup image of your Pi-hole installation, ensuring you have a copy in case anything goes wrong during the upgrade process.
2.3 Switch to Development Branch
Pi-hole version 6 is currently in development, so you need to switch to the development branch to access it. Use the following command:
$ echo "development-v6" | sudo tee /etc/pihole/ftlbranch
This command sets the development branch as the active branch for Pi-hole.
2.4 Checkout Pi-hole Core and Web Development Branches
To switch Pi-hole to version 6, you'll need to checkout the development branches for both core and web components:
$ pihole checkout core development-v6
$ pihole checkout web development-v6
2.5 Change password to Web UI
Change the password for the Pi-hole web interface using the command:
$ sudo pihole setpassword
2.6 Remove Lighttpd and PHP
Remove the Lighttpd and PHP packages from your system using the commands:
$ sudo apt remove lighttpd php*
These commands remove the Lighttpd web server and PHP packages, which are no longer needed in Pi-hole version 6.
2.7 Edit Pi-hole Configuration File
Edit the Pi-hole configuration file /etc/pihole/pihole.toml and change the port from 8080 to 80 as follows:
port = "80,443s,[::]:80,[::]:443s"
This configuration change ensures that Pi-hole listens on port 80 for HTTP traffic. Restart the Pi-hole-FTL service to apply the configuration changes using the command:
$ sudo systemctl restart pihole-FTL
3. Testing Pi-hole v6 API
After installing Pi-hole and configuring it to your preferences, you might want to explore its API v6 capabilities. The Pi-hole API allows users to interact with their Pi-hole instance programmatically, opening up a range of possibilities for automation and customization. In this article, we'll walk through some examples of using the Pi-hole API to authenticate, retrieve statistics, and query specific domains.
Firstly, we need to install jq tool in order to display output in JSON format:
$ sudo apt install jq
3.1 Authenticate with the Pi-hole API using cURL
Before you can start using the Pi-hole API, you need to authenticate yourself. One way to do this is using cURL, a command-line tool for transferring data with URL syntax. Here s an example command:
$ curl -s -k --request POST -d '{"password":"pihole"}' https://pi.hole/api/auth |jq
-s uppresses the progress meter
-k ignore the certificate verification
--request POST specifies that the request method is POST
-d '{"password":"pihole"}' sends the password "pihole" in the request body
https://pi.hole/api/auth is the URL of the Pi-hole API endpoint for authentication.
Figure 1 - Authenticating with Curl
Executing this command will authenticate with the Pi-hole API and returns a temporarily valid session ID (SID). The response will include a session ID (SID) that we will use in subsequent requests.In our case, SID is vu4DAia0J+Wh/ew34vJUvA=.
Note:
The validity of the SID is prolonged on every request, and, otherwise, can also be set via a config option. This endpoint will return an SID you will from this point on send in your requests.
3.2 Get Top 3 Clients
$ curl -s -k -X GET "https://192.168.88.10:443/api/stats/database/top_clients?from=1712737288&until=1713169288&blocked=false&count=3" -H "accept: application/json" -H "sid: vu4DAia0J+Wh/ew34vJUvA=" | jq
This command retrieves information about the top 3 clients with requests within a specified time range (Figure 2). It uses query parameters like from, until, blocked=yes, and count=3 to filter the data. The jq tool is used to process the JSON response (if available).
Figure 2 - Top Three Clients with Queries
Note: Please note that the time range specified is in Unix epoch time and spans from Wednesday, April 10, 2024, at 10:21:28 AM GMT+02:00 DST to Monday, April 15, 2024, at 10:21:28 AM GMT+02:00 DST. If you need to convert Unix epoch time to a human-readable format, you can use the provided time converter link.
3.3 Query Specific Domain
Query domain brezular.com:
$ curl -s -k -X GET "https://192.168.88.10:443/api/queries?domain=brezular.com&disk=true&status=denylist" -H "accept: application/json" -H "sid: vu4DAia0J+Wh/ew34vJUvA=" | jq
The JSON response you received contains information about two queries made for the domain "brezular.com" that were denied due to being on a denylist. (Figure 3).
Figure 3 - Checking Denied Queries to brezular.com Using API
Both queries are received from the client 192.168.100.98. This is confirmed from with the output from web UI (Figure 4). This consistency between the API data and the web UI data reinforces the accuracy of the information retrieved through the API query. It demonstrates how the API can be a valuable tool for programmatic access to Pi-hole data, offering an alternative approach to information retrieval.
Figure 4 - Denied Queries to brezular.com from Web UI
Conclusion
The latest updates to Pi-hole bring exciting enhancements, making the ad-blocking solution more efficient, flexible, and user-friendly. With the integration of new features, Pi-hole offers improved performance, streamlined configuration, and enhanced security.
These updates demonstrate the continuous commitment of the Pi-hole community to deliver a robust and user-centric ad-blocking solution. As development progresses, further stability improvements and additional features can be expected, ensuring Pi-hole remains a leading choice for network-wide ad blocking.