DNSCrypt-Proxy Configuration

DNSCrypt-Proxy Configuration

Overview

The Pimeleon router implements DNSCrypt-proxy as the final stage in the DNS resolution chain, providing encrypted DNS queries to upstream servers with DNSSEC validation, caching, and privacy protection. Operating on port 5054, DNSCrypt-proxy receives filtered queries from the DNS filter and securely resolves them through encrypted protocols (DNSCrypt and DNS-over-HTTPS).

Architecture & Design Philosophy

Encrypted DNS Privacy Layer

DNSCrypt-proxy serves as the privacy and security endpoint:

  • Protocol Encryption: All upstream queries encrypted via DNSCrypt or DoH
  • DNSSEC Validation: Cryptographic DNS response validation required
  • Privacy Protection: Prevents ISP DNS monitoring and manipulation
  • Censorship Resistance: Bypass potential DNS-based blocking

Integration with Filtering Chain

Final stage in comprehensive DNS processing pipeline:

  • DNS Filtering Integration: Receives filtered queries from the DNS filter on port 5553
  • Upstream Diversity: Multiple encrypted DNS providers for redundancy
  • Local Caching: High-performance local cache reduces upstream queries
  • Fallback Capability: Bootstrap resolvers ensure connectivity during startup

Security-First Configuration

Enhanced security through multiple protective measures:

  • DNSSEC Mandatory: All responses must pass cryptographic validation
  • Tor Integration: .onion domain routing through Tor network
  • Anonymized Routing: Query routing through anonymizing relays
  • Pattern Blocking: Additional blocking layer for malicious patterns

Service Configuration

Core DNSCrypt Settings

Foundation configuration for encrypted DNS resolution:

  • Listen Address: 127.0.0.1:5054 (localhost-only for DNS filtering integration)
  • Protocol Support: DNSCrypt and DNS-over-HTTPS enabled
  • IPv4 Only: IPv6 disabled for simplified network configuration
  • DNSSEC Required: All responses must include valid DNSSEC signatures
  • TCP Fallback: Automatic TCP retry for truncated UDP responses

Upstream Server Configuration

Carefully selected encrypted DNS providers:

Primary Servers

  • Cloudflare: cloudflare (1.1.1.1 with DNSCrypt)
  • Cloudflare IPv6: cloudflare-ipv6 (IPv6 support when needed)
  • Quad9: quad9-dnscrypt-ip4-filter-pri (filtered DNS with malware protection)

Server Selection Strategy

  • Load Balancing: P2 (Ping and Fastest) strategy for optimal performance
  • Bootstrap Resolvers: 9.9.9.9 and 1.1.1.1 for initial connectivity
  • System DNS Ignored: Independent of system DNS configuration
  • Server Sources: Automatically updated from DNSCrypt resolver lists

Performance Optimization

Tuned for Pi 3B+ hardware performance:

  • Query Timeout: 2.5 seconds maximum (balanced for reliability vs speed)
  • Connection Strategy: Prefer UDP, fallback to TCP when needed
  • Cache Optimization: 4,096 entry cache with intelligent TTL management
  • Concurrent Queries: Efficient connection pooling and reuse

Caching Strategy

Local Cache Configuration

High-performance caching reduces upstream query load:

  • Cache Size: 4,096 entries (optimized for Pi 3B+ memory)
  • Cache Hit Priority: Local cache checked before upstream queries
  • TTL Management: Intelligent TTL handling for optimal performance
  • Negative Caching: Failed queries cached to prevent repeated failures

TTL Optimization

Balanced caching for performance and accuracy:

  • Minimum TTL: 2,400 seconds (40 minutes) for positive responses
  • Maximum TTL: 86,400 seconds (24 hours) for stable records
  • Negative Min TTL: 60 seconds for temporary failures
  • Negative Max TTL: 600 seconds (10 minutes) for persistent failures

Cache Efficiency Benefits

  • Bandwidth Reduction: Fewer encrypted upstream queries needed
  • Latency Improvement: Cached responses serve instantly
  • Upstream Load: Reduced load on encrypted DNS providers
  • Resilience: Cached responses available during upstream issues

Security Features

DNSSEC Validation

Comprehensive cryptographic DNS response validation:

  • Mandatory Validation: All responses must pass DNSSEC checks
  • Chain of Trust: Full cryptographic chain verification
  • Tamper Detection: Modified responses automatically rejected
  • Authentic Data: Only cryptographically verified responses served

Anonymized DNS Routing

Advanced privacy protection through relay routing:

  • Relay Network: Queries routed through anonymizing relays
  • Server Isolation: Upstream servers cannot identify client IP
  • Traffic Analysis Resistance: Query patterns obscured through routing
  • Geographic Diversity: Relays in different countries for enhanced privacy

Configured Anonymized Routes

  • Quad9: Routed through anon-cs-fr and anon-cs-nl relays
  • Scaleway France: Additional anonymized routing option
  • Cloudflare: Available but currently disabled for performance

Tor Network Integration

Special handling for .onion domain resolution:

  • Tor DNS Forwarding: .onion queries forwarded to Tor DNS (127.0.0.1:15353)
  • Static Configuration: Hardcoded Tor DNS resolver stamp
  • Network Separation: Tor queries isolated from regular DNS traffic
  • Privacy Protection: .onion resolution maintains Tor anonymity

Pattern Blocking and Filtering

Additional Blocking Layer

DNSCrypt-proxy provides secondary filtering beyond the DNS filter:

  • Pattern Blocking: Advanced regex-based domain blocking
  • Blocked Names File: Static blocklist for malicious domains
  • Cloaking Rules: Custom domain to IP address mapping
  • Complementary Filtering: Works alongside DNS filtering

Cloaking Configuration

Custom domain resolution for specific use cases:

  • Cloaking Rules File: /opt/dnscrypt-proxy/cloaking-rules.txt
  • Local Override: Override specific domains with custom IP addresses
  • Development Support: Redirect domains for testing purposes
  • Service Integration: Custom routing for internal services

Query Pattern Analysis

Advanced query monitoring and blocking:

  • Query Logging: Detailed query logs for analysis and debugging
  • Ignored Types: DNSKEY and NS queries filtered from logs
  • Pattern Detection: Automatic detection of suspicious query patterns
  • Behavioral Analysis: Long-term query pattern analysis

Integration with DNS Chain

DNS Filter Upstream Integration

Seamless integration with DNS filtering:

  • Upstream Configuration: DNS filter configured to use 127.0.0.1:5054
  • Query Forwarding: Only clean (unblocked) queries reach DNSCrypt-proxy
  • Response Handling: Encrypted responses passed back through DNS filter
  • Error Handling: Timeout and failure handling coordinated

Bind9 Coordination

Integration with primary DNS service:

  • Local Zone Bypass: Internal zones resolved by Bind9, not DNSCrypt-proxy
  • External Query Path: Only external DNS queries reach encryption layer
  • Caching Coordination: Multiple cache layers work efficiently together
  • Failover Support: Service degradation graceful if DNSCrypt-proxy fails

Network Service Discovery

Coordination with network service resolution:

  • mDNS Bypass: Local service discovery doesn't use encrypted DNS
  • NetBIOS Integration: SMB name resolution works independently
  • DHCP Coordination: Dynamic DNS updates bypass encryption layer
  • Service Isolation: Internal services maintain direct resolution paths

Performance Characteristics

Query Performance Metrics

Expected performance on Pi 3B+ hardware:

  • Cache Hit Response: < 1ms for cached queries
  • Encrypted Query: 20-50ms for upstream resolution via DNSCrypt
  • DoH Queries: 30-70ms for DNS-over-HTTPS resolution
  • DNSSEC Validation: Additional 5-15ms for signature verification

Resource Utilization

Optimized resource usage:

  • Memory Usage: ~50-100MB RAM for cache and service operations
  • CPU Usage: Minimal during normal operation, spikes during DNSSEC validation
  • Network Bandwidth: Efficient due to local caching
  • Disk I/O: Periodic cache updates and log rotation

Scalability Considerations

Performance scaling for network load:

  • Concurrent Queries: Efficient handling of multiple simultaneous queries
  • Cache Efficiency: High cache hit ratio reduces upstream load
  • Connection Pooling: Reused connections to upstream servers
  • Load Distribution: P2 strategy balances load across upstream servers

Monitoring and Maintenance

Service Health Monitoring

Comprehensive monitoring for reliable operation:

  • Service Status: SystemD integration for service lifecycle management
  • Upstream Connectivity: Regular health checks to encrypted DNS servers
  • DNSSEC Validation: Monitoring of cryptographic validation success rates
  • Cache Performance: Cache hit ratios and efficiency metrics

Log Analysis

Detailed logging for troubleshooting and security analysis:

  • Proxy Logs: /var/log/dnscrypt-proxy/proxy.log for service operation
  • Query Logs: /var/log/dnscrypt-proxy/query.log for debugging
  • Error Tracking: Failed queries and upstream connectivity issues
  • Performance Metrics: Query response times and cache efficiency

Configuration Management

Automated configuration updates and maintenance:

  • Resolver List Updates: Automatic updates from DNSCrypt resolver sources
  • Certificate Management: Automatic handling of server certificates
  • Relay List Maintenance: Updated anonymizing relay configurations
  • Blocklist Updates: Regular updates to pattern blocking rules

Advanced Features

Load Balancing and Failover

Intelligent upstream server selection:

  • P2 Strategy: Ping and performance-based server selection
  • Automatic Failover: Failed servers automatically excluded
  • Performance Monitoring: Continuous upstream server performance tracking
  • Geographic Selection: Optimal server selection based on network topology

Protocol Flexibility

Multiple encrypted DNS protocol support:

  • DNSCrypt Support: Native DNSCrypt protocol for maximum privacy
  • DNS-over-HTTPS: DoH protocol for firewall traversal
  • Protocol Selection: Automatic protocol selection based on server capabilities
  • Fallback Modes: Graceful degradation when preferred protocols unavailable

Anonymization Network

Advanced privacy through traffic routing:

  • Relay Selection: Automatic selection of anonymizing relays
  • Traffic Distribution: Query load distributed across relay network
  • Geographic Diversity: Relays in multiple countries for enhanced privacy
  • Timing Obfuscation: Query timing patterns obscured through routing

Security Considerations

Threat Protection

Multi-layered protection against various threats:

  • DNS Spoofing: DNSSEC validation prevents response tampering
  • Traffic Analysis: Encrypted queries prevent ISP monitoring
  • Censorship Bypass: Encrypted protocols bypass DNS-based blocking
  • Privacy Protection: Query patterns hidden from upstream observation

Operational Security

Secure operational practices:

  • Local Binding: Service only accessible from localhost
  • Configuration Security: Sensitive configuration files protected
  • Log Management: Query logs rotated and managed securely
  • Update Security: Resolver lists cryptographically verified

Network Isolation

Proper network security boundaries:

  • Firewall Integration: DNSCrypt-proxy traffic controlled by Shorewall
  • Service Isolation: Internal service separated from encrypted DNS
  • Tor Integration: .onion queries properly isolated through Tor
  • Bypass Prevention: Direct upstream DNS access blocked

Troubleshooting

Common Issues and Solutions

Frequent problems and resolution approaches:

Upstream Connectivity Issues

  1. Bootstrap Resolver Test: Verify 9.9.9.9 and 1.1.1.1 accessibility
  2. Server Status Check: Test configured upstream servers individually
  3. Network Connectivity: Verify internet access and routing
  4. Firewall Rules: Ensure outbound DNS traffic allowed

DNSSEC Validation Failures

  1. Time Synchronization: Verify system time accuracy for certificate validation
  2. Upstream Support: Confirm upstream servers support DNSSEC
  3. Validation Logs: Check logs for specific DNSSEC validation errors
  4. Fallback Testing: Temporarily disable DNSSEC to isolate issues

Performance Problems

  1. Cache Configuration: Optimize cache size and TTL settings
  2. Server Selection: Review and optimize upstream server list
  3. Load Balancing: Adjust P2 strategy parameters
  4. Resource Monitoring: Check memory and CPU usage during operation

Diagnostic Commands

Useful commands for troubleshooting:

# Check DNSCrypt-proxy service status
systemctl status dnscrypt-proxy

# Test DNSCrypt-proxy resolution
dig @127.0.0.1 -p 5054 example.com

# Monitor DNSCrypt-proxy logs
tail -f /var/log/dnscrypt-proxy/proxy.log

# Check query logs
tail -f /var/log/dnscrypt-proxy/query.log

# Test DNSSEC validation
dig @127.0.0.1 -p 5054 +dnssec example.com

← Back to Dashboard

ON THIS PAGE
Overview
Architecture & Design Philosophy
Service Configuration
Caching Strategy
Security Features
Pattern Blocking and Filtering
Integration with DNS Chain
Performance Characteristics
Monitoring and Maintenance
Advanced Features
Security Considerations
Troubleshooting
Related Documentation