About me: My name is Solène Rapenne, pronouns she/her. I like learning and sharing knowledge. Hobbies: '(BSD OpenBSD Qubes OS Lisp cmdline gaming security QubesOS internet-stuff). I love percent and lambda characters. Qubes OS core team member, former OpenBSD developer solene@. No AI is involved in this blog.

Contact me: solene at dataswamp dot org or @solene@bsd.network (mastodon).

I'm a freelance OpenBSD, FreeBSD, Linux and Qubes OS consultant, this includes DevOps, DevSecOps, technical writing or documentation work. If you enjoy this blog, you can sponsor my open source work financially so I can write this blog and contribute to Free Software as my daily job.

Presentation of Pi-hole

Written by Solène, on 18 December 2024.
Tags: #network #security #linux

Comments on Fediverse/Mastodon

1. Introduction §

This blog post is about the project Pi-hole, a libre software suite to monitor and filter DNS requests over a local network.

Pi-hole official project page

Pi-hole is Linux based, it is a collection of components and configuration that can be installed on Linux, or be used from a Raspberry PI image ready to write on a flash memory.

The top of Pi-hole dashboard display, star trek skin
The top of Pi-hole dashboard display, star trek skin

2. Features §

Most of Pi-hole configuration happens on a clear web interface (which is available with a star trek skin by the way), but there is also a command line utility and a telnet API if you need to automate some tasks.

2.1. Filtering §

The most basic feature of Pi-hole is filtering DNS requests. While it comes with a default block list from the Internet, you can add custom lists using their URLs, the import supports multiple formats as long as you tell Pi-hole which format to use for each source.

Filtering can be done for all queries, although you can create groups that will not be filtered and assign LAN hosts that will belong to this group, in some situation there are hosts you may not want to filter.

The resolving can be done using big upstream DNS servers (Cloudflare, Google, OpenDNS, Quad9 ...), but also custom servers. It is possible to configure a recursive resolver by installing unbound locally.

Pi-hole documentation: how to install and configure unbound

2.2. Dashboard §

A nice dashboard allows you to see all queries with the following information:

  • date
  • client IP / host
  • domain in the query
  • result (allowed, blocked)

It can be useful to understand what is happening if a website is not working, but also see how much queries are blocked.

It is possible to choose the privacy level of logging, because you may only want to have statistics about numbers of queries allowed / blocked and not want to know who asked what (this may also be illegal to monitor this on your LAN).

Documentation about privacy levels

2.3. Audit log §

In addition to lists, the audit log will display two columns with the 10 most allowed / blocked domains appearing in queries, that were not curated through the audit log.

Each line in the "allowed" column have a "blacklist" and "audit" buttons. The former will add the domain to the internal blacklist while the latter will just acknowledge this domain and remove it from the audit log. If you click on audit, it means "I agree with this domain being allowed".

The column with blocked queries will show a "Whitelist" and "Audit" buttons that can be used to definitely allow a domain or just acknowledge that it's blocked.

Once you added a domain to a list or clicked on audit, it got removed from the displayed list, and you can continue to manually review the new top 10 domains.

2.4. Disable blocking §

There is a feature to temporarily disable blocking for 10 seconds, 30 seconds, 5 minutes, indefinitely or a custom time. This can be useful if you have an important website that misbehave and want to be sure the DNS filtering is not involved.

2.5. Local hostnames §

It is possible to add custom hostnames that resolve to whatever IP you want, this makes easy to give nice names to your machines on your LAN. There is nothing really fancy, but the web ui makes it easy to handle this task.

2.6. Extra features §

Pi-hole can provide a DHCP server to your LAN, has self diagnosis, easy configuration backup / restore. Maybe more features I did not see or never used.

3. Conclusion §

While Pi-hole requires more work than configuring unbound on your local LAN and feed it with a block list, it provides a lot more features, flexibility and insights about your DNS than unbound.

Pi-hole works perfectly fine on low end hardware, it uses very little resources despite all its features.

4. Going further §

I am currently running Pi-hole as a container with podman, from an unpriviliged user. This setup is out of scope, but I may write about it later (or if people ask for it) as it required some quirks due to replying to UDP packets through the local NAT, and the use of the port 53 (which is restricted to root, usually).