pi-hole/docker-pi-hole
Docker Pi Hole
This project provides a containerized DNS sinkhole and network-wide traffic filtering solution. It functions as a central network resolver that intercepts domain queries, allowing users to block advertisements, trackers, and malicious domains by returning null responses to connected devices.
The platform distinguishes itself through its integrated DHCP server and comprehensive management capabilities, which allow for automated IP address allocation and granular control over network traffic. It supports complex filtering through regular expression matching, hierarchical rule prioritization, and the ability to group clients for custom policy enforcement. Users can monitor network activity in real time via a web-based dashboard or programmatic API, while persistent storage ensures that configurations, logs, and blocklists remain intact across container restarts.
Beyond core filtering, the project includes extensive tools for DNS performance optimization, including query caching, recursive resolution, and upstream server configuration. It also incorporates security features such as DNSSEC validation, encrypted DNS routing, and administrative access controls to protect network integrity.
The software is distributed as a portable container image, with configuration managed primarily through environment variables and persistent volume mapping for state preservation.
Features
- DNS Sinkholes - Intercepts domain queries and returns null responses to block unwanted traffic as a central network sinkhole.
- Network Ad Blockers - Intercepts and filters DNS queries network-wide to block advertisements and trackers for all connected devices.
- DHCP Servers - Provides an integrated DHCP server for automatic IP address allocation and network configuration for connected devices.
- Domain Blocklists - Maintains comprehensive domain blocklists to prevent access to advertisements, trackers, and malicious sites.
- Administrative Interfaces - Provides a web-based dashboard for managing server settings, monitoring traffic, and configuring filtering policies.
- DNS Resolvers - Functions as a containerized DNS resolution engine with support for caching and DNSSEC validation.
- Web Dashboards - Provides a web-based dashboard for configuring DNS and DHCP settings and monitoring network traffic in real time.
- Network Traffic Filters - Intercepts DNS queries for known ad and tracker domains and returns a null response to prevent content from loading.
- Network Traffic Dashboards - Provides a web-based dashboard for real-time visualization of DNS query statistics and network traffic monitoring.
- DNS Distribution Services - Configures network clients to use the sinkhole automatically by pushing DNS settings through DHCP.
- DNS Configuration - Allows injection of custom DNS resolution logic via configuration files and environment variables.
- DNS Management Tools - Maps local hostnames to specific IP addresses to ensure reliable internal network resolution for local devices.
- DNS Resolution - Directs network traffic to a designated sinkhole by updating router settings, DHCP server configuration, or manual DNS assignment.
- Domain Filtering Engines - Provides a domain filtering engine that uses regular expressions to block unwanted network traffic.
- Traffic Filtering Rules - Organizes clients, allowlists, and blocklists into groups to control which network devices are subject to specific filtering policies.
- Encrypted DNS Resolvers - Forwards DNS resolution requests through encrypted tunnels to remote providers.
- Administrative Dashboards - Pi-hole provides a command-line interface and web dashboard to monitor service status, update software, and manage configuration settings.
- Network Traffic Analyzers - Provides real-time network traffic monitoring and visualization of DNS query statistics.
- Query Logging - Persists DNS query logs in an embedded relational database to maintain a long-term record of network activity.
- More to explore - Network-wide ad blocking.
- DNS Caches - Caches resolved domain names in memory to accelerate future lookups and reduce upstream server load.
- Network Statistics APIs - Exposes an interactive API for querying detailed network analysis data and performance statistics.
- Recursive DNS Resolvers - Operates a local recursive DNS resolver to fetch domain information directly from root servers.
- Regex Filtering Engines - Uses regular expression patterns to dynamically permit or deny network traffic requests.
- External Filter List Integrations - Automatically fetches and maintains collections of domains from remote sources to keep filtering rules updated against evolving threats.
- DNS Validation Tools - Validates cryptographic signatures for DNS records to ensure data integrity.
- Grouped Filters - Assigns network clients to custom groups for unique filtering rule enforcement.
- Network Hostname Resolvers - Resolves IP addresses to human-readable hostnames using PTR lookups and network table analysis.
- DNS Services - Provides global toggles to enable or disable DNS filtering, including temporary suspension periods for unrestricted access.
- Administrative Access Controls - Provides password-protected administrative access to the web interface and API services.
- Content Filtering APIs - Enables programmatic toggling of network-wide content filtering states via API requests.
- Encrypted Traffic Blockers - Rejects HTTPS and QUIC traffic at the network level to prevent advertisement assets from bypassing standard DNS filtering.
- DNS Filtering Solutions - Reloads gravity databases and recompiles regular expression filters to apply blocking changes without flushing the active DNS cache.
- Secure Remote Access - Supports secure remote DNS access by routing queries through encrypted tunnels or VPN connections.
- Activity Monitors - Records operational events and DNS query details to persistent files for troubleshooting and monitoring.
- Diagnostic and Error Reporting - Analyzes system logs and configuration to generate diagnostic reports for troubleshooting and support.
- Query Performance Monitoring - Streams DNS query logs in real-time to observe network traffic and troubleshoot connectivity or blocking issues.
- Client Activity Reporters - Calculates and reports network activity statistics for individual clients based on historical database records.
- DNS Query Filters - Configures specific DNS replies, such as empty answers or custom IP addresses, when queries match filtering rules.
- IP Address Management Systems - Manages IP address allocation and network configuration for local devices via an integrated DHCP server.
- Network Traffic Routing - Configures VPN servers to push network-wide DNS filtering to connected clients.
- API Access Security - Authenticates API requests using session identifiers and supports two-factor authentication.
- DNS Security - Validates DNS responses using cryptographic signatures to ensure data integrity.
- Network Access Controls - Configures firewall rules to isolate services and secure administrative access.
- Path-Based Access Rules - Identifies network devices by IP or CIDR range to apply specific filtering policies.
- Privacy Configuration - Configures the level of detail stored for DNS queries to balance network statistics with user privacy.
- Remote Access Security - Establishes VPN connections to route traffic and DNS queries securely.
- Management Interface Networking - Configures the service to listen for requests on all network interfaces, enabling consistent filtering for local and VPN clients.
- Metrics Exporters - Transmits DNS filtering statistics to external monitoring systems for long-term traffic analysis.
- Network Device Synchronizers - Parses system ARP and neighbor caches to maintain an accurate, synchronized list of connected network devices.
- Reverse DNS Resolution - Performs reverse DNS lookups for local IP addresses to map hostnames in the management dashboard.
