This page provides a high-level introduction to Pi-hole: what it is, how it works, and its core capabilities. For detailed information about specific subsystems, see:
Pi-hole is a DNS sinkhole that provides network-wide ad blocking and tracking protection. It functions as a DNS server that intercepts DNS queries from devices on your network, blocks requests to known advertising and tracking domains, and forwards legitimate queries to upstream DNS providers.
Unlike browser extensions or client-side software, Pi-hole operates at the network level, which means:
pihole-FTL engine README.md116-118Core Principle: When a device requests the IP address for an advertising domain, Pi-hole returns a "sinkhole" address (typically 0.0.0.0), preventing the ad from loading. Legitimate domains are resolved normally via upstream DNS servers.
Sources: README.md13-24 pihole3-5
| Capability | Description |
|---|---|
| DNS Filtering | Blocks queries to domains in blocklists (adlist sources like StevenBlack) README.md116-124 |
| Custom Lists | Supports allowlists, denylists, regex patterns, and wildcards via list.sh pihole68-71 |
| Query Logging | Records all DNS queries for analysis and statistics in pihole-FTL.db README.md120-130 |
| Caching | Improves performance by caching frequently accessed DNS records README.md17-18 |
| IPv4 and IPv6 | Full support for both IP versions README.md23 |
| DHCP Server | Optional DHCP functionality to auto-configure all network devices README.md21 |
| FTL Integration | Direct interaction with the engine for statistics and configuration advanced/Scripts/utils.sh120-149 |
Sources: README.md15-24 pihole68-71 advanced/Scripts/utils.sh120-149
Pi-hole consists of several primary components that bridge the management layer to the DNS engine:
This diagram maps natural language components to specific code entities and file paths.
Sources: pihole12-34 pihole68-71 pihole128-130 advanced/Scripts/utils.sh120-149
The following diagram illustrates how Pi-hole processes a DNS query from a network device, utilizing the pihole-FTL engine and the gravity.db database.
Sources: README.md116-134 pihole158-211
Pi-hole supports multiple installation paths, primarily driven by the basic-install.sh script.
curl -sSL https://install.pi-hole.net | bash README.md33basic-install.sh README.md43-45For detailed installation procedures, see Installation Process.
The pihole command (located at /usr/local/bin/pihole) acts as the primary dispatcher for system management.
| Command | Function | Script Called |
|---|---|---|
pihole -g | Update gravity database | gravity.sh pihole128-130 |
pihole allow | Add domain to allowlist | list.sh pihole68-71 |
pihole -d | Start debug session | piholeDebug.sh pihole73-87 |
pihole -v | Check versions | version.sh pihole153-156 |
pihole -up | Update Pi-hole | update.sh pihole109-117 |
See Command-Line Interface for complete reference.
The pihole-FTL daemon provides a modern HTTP API for the web interface and third-party integrations.
api.sh and functions like PostFTLData pihole28-30 pihole254-257setFTLConfigValue for webserver.api.password pihole37-66See Web Interface and API for details.
Pi-hole v6 centralizes configuration within pihole-FTL and utilizes standardized script locations.
| Item | Location / Code Entity |
|---|---|
| Main Config | pihole-FTL --config (accessed via getFTLConfigValue) advanced/Scripts/utils.sh120-124 |
| Gravity DB | /etc/pihole/gravity.db |
| FTL DB | /etc/pihole/pihole-FTL.db |
| Scripts | /opt/pihole/ pihole12 |
| Version Info | /etc/pihole/versions pihole32-35 |
Sources: pihole12-35 advanced/Scripts/utils.sh120-135
To safely remove Pi-hole and its associated services, the uninstall.sh script is provided. This process cleans up system services, configuration directories, and core binaries.
See Uninstallation for the full cleanup procedure.
Sources: pihole144-151