DNS Filtering Configuration

Network-wide DNS filtering for ad blocking and malware protection

DNS Filtering Configuration

Overview

The Pimeleon router integrates DNS filtering as a network-wide DNS filtering solution, providing ad blocking, tracking protection, and malicious domain filtering for all connected devices. The DNS filter operates on port 5553, receiving queries forwarded from Bind9 and returning filtered responses that protect the entire network infrastructure.

Architecture & Design Philosophy

Integration with Bind9

The DNS filter operates as a filtering layer within the DNS resolution chain:

  • Bind9 Frontend: Clients query Bind9 on port 53 (standard DNS port)
  • DNS Filter Backend: Bind9 forwards external queries to the DNS filter on port 5553
  • Encrypted Upstream: DNS filter forwards clean queries to DNSCrypt-proxy (127.0.0.1:5054)
  • Transparent Operation: Clients unaware of filtering layer existence

Network-Wide Protection Philosophy

Single point of filtering protects all network devices:

  • Universal Coverage: All DNS queries filtered regardless of device type
  • Zero Client Configuration: No software installation or configuration required
  • Bypass Prevention: Network-level filtering prevents most bypass attempts
  • Mobile Protection: Smartphones and IoT devices automatically protected

Security-First Filtering Strategy

Comprehensive protection against multiple threat vectors:

  • Ad Blocking: Advertisement and tracking domain blocking
  • Malware Protection: Malicious domain and phishing site filtering
  • Privacy Enhancement: Tracking pixel and analytics blocking
  • Bandwidth Optimization: Blocked content doesn't consume network resources

Service Configuration

Core DNS Filter Settings

Foundation configuration for network-wide filtering:

  • Domain: pimeleon.local (or custom domain matching DHCP and DNS configuration)
  • Interface: eth1 (LAN interface binding)
  • Listening Mode: ALL (accepts queries from all network interfaces)
  • Port: 5553 (non-standard port for integration with Bind9)
  • Query Logging: Disabled for performance and privacy

DNS Resolution Chain

Multi-stage DNS resolution process with encrypted upstream:

  1. Client Query: Device queries 192.168.76.1 or 192.168.77.1 port 53
  2. Bind9 Processing: Bind9 checks local zones first (pimeleon.local or custom domain)
  3. DNS Filter Forwarding: External queries forwarded to the DNS filter port 5553
  4. Filtering Decision: DNS filter checks query against blocklists
  5. DNSCrypt Resolution: Clean queries forwarded to DNSCrypt-proxy (127.0.0.1:5054)
  6. Encrypted Upstream: DNSCrypt-proxy queries encrypted DNS servers (Cloudflare, Quad9)
  7. Response Chain: Encrypted responses filtered and returned to client

Network Interface Integration

DNS filter configured for dual-network operation:

  • Primary Interface: eth1 (wired LAN - 192.168.76.x)
  • Secondary Coverage: wlan0 (WiFi - 192.168.77.x) via Bind9 forwarding
  • Loopback Access: 127.0.0.1:5553 for Bind9 integration
  • Cross-Network Filtering: Uniform filtering across all network segments

Filtering Configuration

Blocking Behavior

How the DNS filter responds to blocked queries:

  • Block Mode: NULL response (0.0.0.0 for A records, :: for AAAA)
  • Block TTL: 2 seconds (rapid retry for false positives)
  • EDNS Information: TEXT mode with detailed blocking reason
  • Upstream Blocked TTL: 24 hours (cache upstream-blocked domains)

Special Domain Handling

Targeted blocking of bypass mechanisms:

  • Mozilla Canary: Blocks use-application-dns.net (disables Firefox DoH)
  • iCloud Private Relay: Blocks mask.icloud.com and mask-h2.icloud.com
  • Designated Resolver: Blocks resolver.arpa (prevents DoH bypass via RFC 9462)
  • ESNI Blocking: Blocks _esni. subdomains to maintain filtering effectiveness

Privacy and Security Features

Enhanced protection through advanced configuration:

  • CNAME Deep Inspection: Enabled for comprehensive tracking prevention
  • EDNS0 Client Subnet: Enabled for accurate client identification behind NAT
  • Bogus Private: Disabled to allow reverse DNS for internal networks
  • DNSSEC: Disabled (handled by upstream resolvers)

Performance Optimization

Cache Configuration

Optimized caching for Pi 3B+ hardware:

  • Cache Size: 10,000 entries (balanced for memory usage)
  • Cache Optimizer: 3,600 seconds (1 hour stale data tolerance)
  • Upstream Blocked TTL: 86,400 seconds (24 hours for blocked domains)
  • Local TTL: Fast response for frequently queried domains

Rate Limiting

Protection against DNS abuse and attacks:

  • Query Limit: 1,000 queries per client
  • Time Window: 60 seconds
  • Response: REFUSED status for rate-limited queries
  • Behavior: Per-client basis, other clients unaffected

Resource Management

Efficient operation on constrained hardware:

  • Process Priority: -10 (high priority for DNS responsiveness)
  • Memory Monitoring: 90% shared memory usage warning threshold
  • Disk Monitoring: 90% disk usage warning threshold
  • Load Monitoring: System load monitoring enabled

Database and Logging

Query Database Management

Long-term query storage for analysis:

  • Database Location: /etc/pihole/pihole-FTL.db
  • Retention Period: 91 days (configurable)
  • Storage Interval: 60 seconds
  • WAL Mode: Enabled for performance (Write-Ahead Logging)

Logging Configuration

Balanced logging for troubleshooting without performance impact:

  • Query Logging: Disabled (privacy and performance)
  • FTL Logging: Enabled for service diagnostics
  • Web Server Logging: Enabled for admin interface access
  • Privacy Level: 0 (full statistics available)

Network Analysis

Advanced network monitoring capabilities:

  • ARP Cache Parsing: Enabled for client identification
  • IPv4 Resolution: Enabled for hostname lookup
  • IPv6 Resolution: Enabled for comprehensive coverage
  • Network Names: Enabled for cross-IP hostname correlation

Management Interface

Pimeleon Web Interface Integration

DNS filtering is managed through the native Pimeleon web interface:

  • Access: Integrated into Pimeleon dashboard at 192.168.76.1
  • Authentication: Uses Pimeleon's unified authentication system
  • Monitoring: Real-time filtering statistics and blocked query counts
  • Configuration: Blocklist management and whitelist configuration
  • Theme: Follows Pimeleon's consistent UI design

API Access

Programmatic access for automation and integration:

  • CLI Tools: Standard DNS filtering CLI commands available via SSH
  • Automation: Configuration via command-line tools
  • Monitoring Scripts: Query statistics accessible for custom monitoring

Integration Benefits

Bind9 DNS Integration

Seamless integration with primary DNS service:

  • Zone Preservation: Local zones (pimeleon.local or custom domains) resolved by Bind9
  • Dynamic DNS: DHCP hostname updates bypass DNS filter
  • Caching Efficiency: Two-layer caching (Bind9 + DNS filter)
  • Fallback Capability: Bind9 can operate independently if DNS filter fails

DHCP Service Coordination

Network-wide automatic configuration:

  • DNS Server Assignment: All DHCP clients receive DNS filtering
  • Domain Configuration: Local domain (pimeleon.local) automatically distributed
  • Cross-Network Consistency: Same filtering applied to LAN and WiFi clients
  • Service Discovery: NetBIOS and mDNS services work through filtering

Firewall Integration

Coordinated security through multiple layers:

  • Port Protection: DNS service protected by nftables firewall
  • Zone-Based Access: Different access rules for LAN vs WiFi
  • WAN Isolation: Management interface blocked from external access
  • Service Integration: DNS filtering complements firewall blocking

Monitoring and Maintenance

Health Monitoring

Comprehensive service health tracking:

  • Service Status: SystemD integration for service monitoring
  • Database Integrity: Automatic database consistency checking
  • Query Processing: Real-time query processing statistics
  • Cache Performance: Cache hit rates and efficiency metrics

Performance Metrics

Key performance indicators for optimization:

  • Query Response Time: DNS resolution latency monitoring
  • Cache Hit Ratio: Effectiveness of caching configuration
  • Blocked Query Percentage: Filtering effectiveness measurement
  • Resource Utilization: Memory, CPU, and disk usage tracking

Log Analysis

Troubleshooting and security monitoring:

  • FTL Logs: /var/log/pihole/FTL.log for service diagnostics
  • Web Server Logs: /var/log/pihole/webserver.log for admin access
  • Query Analysis: Blocked vs allowed query patterns
  • Client Behavior: Device-specific query patterns and blocking

Advanced Features

NTP Service Integration

Network time synchronization service:

  • IPv4 NTP Server: Enabled for internal network time sync
  • IPv6 NTP Server: Enabled for dual-stack environments
  • Upstream Sync: pool.ntp.org synchronization every hour
  • RTC Support: Real-time clock updating available

Custom DNS Records

Local hostname resolution enhancement:

  • Host Records: Custom A/AAAA record capability (currently unused)
  • CNAME Records: Alias record support for internal services
  • Domain Expansion: Automatic domain suffix addition
  • Reverse Lookup: PTR record management for internal hosts

Conditional Forwarding

Selective DNS resolution for specific networks:

  • Local Domain: Internal domain (pimeleon.local) queries handled locally
  • Network Range: 192.168.0.0/16 coverage for internal resolution
  • Cross-Network Discovery: Hostname resolution across network segments
  • Service Integration: Coordinated with DHCP dynamic DNS updates

Security Considerations

Bypass Prevention

Multiple layers prevent filtering circumvention:

  • Network-Level Filtering: Cannot be disabled by individual devices
  • Alternative DNS Blocking: DoH, DoT, and other bypass methods blocked
  • Port Filtering: Only router DNS service accessible to clients
  • Firmware Integration: Filtering built into network infrastructure

Privacy Protection

Balanced security with user privacy:

  • Query Logging Disabled: DNS queries not stored for privacy
  • Client Anonymization: Option to hide client information available
  • Data Retention: 91-day limit on stored query data
  • External Blocking: No queries sent to external analytics services

Attack Surface Management

Minimized exposure through careful configuration:

  • Non-Standard Port: DNS filter on port 5553 reduces external discovery
  • Firewall Protection: Management interface protected by nftables rules
  • Authentication Required: Password protection for all administrative functions
  • Rate Limiting: Protection against DNS amplification attacks

Troubleshooting

Common Issues and Solutions

Frequent problems and resolution approaches:

DNS Resolution Failures

  1. Check Bind9 Integration: Verify forwarding to port 5553
  2. DNS Filter Service Status: Ensure DNS filter service is running
  3. Upstream Configuration: Verify 127.0.0.1:5054 accessibility
  4. Network Connectivity: Test internal network routing

Management Interface Access

  1. Web Interface: Access Pimeleon dashboard at https://192.168.76.1
  2. Authentication: Use Pimeleon's unified login credentials
  3. Network Access: Ensure device is connected to LAN or WiFi
  4. Firewall Rules: Management interface only accessible from internal networks

Performance Issues

  1. Cache Size: Adjust cache size for available memory
  2. Rate Limiting: Review rate limit settings for legitimate clients
  3. Database Optimization: Check database size and performance
  4. Resource Monitoring: Monitor CPU and memory usage

Diagnostic Commands

Useful commands for troubleshooting:

# Check DNS filter service status
systemctl status pihole-FTL

# Test DNS resolution through DNS filter
dig @127.0.0.1 -p 5553 example.com

# Monitor DNS filter query logs
tail -f /var/log/pihole/FTL.log

# Check DNS filter statistics
pihole status

# Verify configuration
pihole-FTL --config

← Back to Dashboard

ON THIS PAGE
Overview
Architecture & Design Philosophy
Service Configuration
Filtering Configuration
Performance Optimization
Database and Logging
Management Interface
Integration Benefits
Monitoring and Maintenance
Advanced Features
Security Considerations
Troubleshooting
Related Documentation