Your network is talking. Every device that connects to your router asks a domain name server (DNS) to translate a human-readable name like example.com into an IP address. Those requests are a record of what your devices are trying to reach. Pi-hole, an open-source DNS sinkhole, gives you a way to see that record and decide what to block. The official documentation describes it as “a DNS sinkhole that protects your devices from unwanted content, without installing any client-side software” and notes that it blocks content “in non-browser locations, such as ad-laden mobile apps and smart TVs” (Pi-hole documentation).
This is not a surveillance tool. It is a transparency practice. The query log shows what your own network asks for, so you can make informed allow-or-deny decisions instead of trusting a vendor’s summary. The steps below follow the official Pi-hole documentation. Where the documentation is silent, I say so.
What the official docs say you need before installing
Pi-hole is lightweight. The prerequisites page lists minimum hardware of 2GB free space (4GB recommended) and 512MB RAM. It is not limited to Raspberry Pi hardware; any hardware that runs a supported operating system will do. The officially supported operating systems are Alpine, Armbian OS, Debian, CentOS Stream, Fedora, Raspberry Pi OS (formerly Raspbian), and Ubuntu. The docs add that Pi-hole only supports actively maintained versions of these systems (Prerequisites).
Pi-hole needs a static IP address to function properly. A DHCP reservation is acceptable. The FTL service uses port 53 for DNS over TCP and UDP. If you already run another DNS server such as BIND, you must turn it off for Pi-hole to respond to DNS queries. The web interface uses ports 80 and 443; if those are taken, Pi-hole will try 8080 and 8443. Optional DHCP and NTP features use additional ports (Prerequisites).
The docs also provide firewall guidance, noting that Pi-hole is designed to work inside a local network and that the example rules block traffic from the internet for security reasons. The examples use common local network ranges such as 192.168.0.0/16, 10.0.0.0/8, and 172.16.0.0/12, and advise checking your own network settings before applying them (Prerequisites).
Installation and post-install routing
The installer walks you through the process. After installation, the docs say you need to configure your router to have DHCP clients use Pi-hole as their DNS server. This ensures all devices connected to your network have content blocked without further intervention. If your router does not support setting the DNS server, you can use Pi-hole’s built-in DHCP server after disabling DHCP on the router. As a last resort, you can manually set each device to use Pi-hole as its DNS server (Post-Install).
One warning from the docs deserves emphasis: if the Pi-hole host uses Pi-hole as its upstream DNS server and Pi-hole fails, the host loses DNS resolution. This can prevent repair attempts such as pihole -r, which needs a working internet connection. The docs state this plainly. Decide deliberately whether to accept that trade-off (Post-Install).
For command-line access without repeated password prompts, the docs describe adding your local user to the pihole group. On Debian, Ubuntu, Raspberry Pi OS, Armbian, Fedora, and CentOS, the command is sudo usermod -aG pihole $USER. On Alpine, it is doas addgroup $USER pihole (Post-Install).
Reading the query log
Pi-hole provides a responsive web interface dashboard to view and control it, and a command-line interface (Pi-hole documentation). The dashboard is the most direct way for a non-technical user to see recent queries. The docs do not, in the retrieved pages, give a step-by-step guide to interpreting every column. What they do establish is that the log exists and is accessible through the interface.
For programmatic access, Pi-hole’s API is REST-based. It returns JSON, uses standard HTTP response codes and verbs, and most but not all endpoints require authentication. Unauthenticated requests to protected endpoints fail with 401 Unauthorized. The entire API is documented at http://pi.hole/api/docs and is self-hosted by your Pi-hole to match the installed API version. The docs say using the locally served documentation is preferred (Pi-hole API).
The API uses GET to read from a resource, POST to create, PATCH to update, PUT to create or replace, and DELETE to delete (Pi-hole API). For reading the query log, GET is the relevant method. Avoid POST, PATCH, PUT, and DELETE until you understand what they change.
The retrieved documentation does not describe the query log’s database schema or retention settings. The page that would cover that (https://docs.pi-hole.net/ftldns/query-database/) was unavailable at the time of writing. If you need to query the database directly, consult the locally served API docs or the Pi-hole community resources. Do not assume a schema from memory.
A hypothetical worked example
The following is a constructed scenario, not a report of a real device or test.
Suppose you open the Pi-hole dashboard and see a query from an IP address you recognize as your smart TV, asking for a domain you do not recognize. The log tells you a name was resolved. It does not tell you why. The responsible next step is to look up the domain in a public WHOIS service or the vendor’s own documentation. If the domain appears to be for firmware updates, you might allowlist it. If it appears to be for advertising or telemetry you consider unwanted, you might denylist it. The docs support that allowlist and denylist editing exists; they do not prescribe which domains belong on either list.
This is the civic value of the query log: it gives you a verifiable starting point for a decision, not a verdict. You can see the name your device asked for. You can check that name against a primary source. You can decide.
Limits and safety
Pi-hole is a DNS sinkhole. It blocks content at the DNS layer. It does not block all ads, trackers, or telemetry. The docs describe it as protecting devices from unwanted content, not as a universal blocker. It also does not tell you which local device made a query unless you have configured your network so that Pi-hole can see that information. The retrieved documentation does not detail how to map queries to specific devices beyond the IP address shown in the log.
The docs’ firewall guidance assumes a local network. Exposing Pi-hole directly to the internet is not described as a supported configuration. If you need remote access, consult the VPN guides in the Pi-hole documentation rather than opening ports.
Finally, the query log is shared data. If your network serves a household, an office, or an organization, the log reflects every device that uses Pi-hole as its resolver. Treat it as household or organizational data, not just your own. The retrieved documentation does not make legal claims about privacy law or employee monitoring. If you need to know your obligations under EU or North American law, consult a qualified professional and the relevant statutes.
What you can do today
If you have compatible hardware and a supported operating system, run the installer. Then configure your router to point DHCP clients at Pi-hole. Open the dashboard. Look at the query log. Pick one domain you do not recognize and look it up in a public WHOIS service or the vendor’s documentation. That is the whole practice: see the name, check the source, make a decision. The documentation gives you the tools. The judgment is yours.