xehmad/pihole-dnsproxy repository overview

⁠Pi-hole with DNSProxy

This Docker image combines Pi-hole⁠ (a popular network-wide ad blocker) with DNSProxy⁠ (a flexible DNS proxy with advanced features like DoH, DoT, and DNSCrypt support). It is designed to provide a robust and customizable solution for managing DNS traffic while blocking ads and trackers across your network.

⁠Features

• Pi-hole Integration: Includes the latest version of Pi-hole for network-wide ad blocking.
• DNSProxy Support: Adds DNSProxy as a secondary service to enhance DNS functionality with modern protocols like DoH (DNS-over-HTTPS), DoT (DNS-over-TLS), and DNSCrypt.
• Multi-Architecture Support: Built for multiple platforms, including x86, arm, and x64, ensuring compatibility with a wide range of devices (e.g., Raspberry Pi, servers, desktops).
• Dynamic Versioning: Easily update Pi-hole and DNSProxy versions using a JSON-based configuration file (versions.json).
• Automated Builds: Includes a build script (build.sh) to automate the creation and publishing of Docker images for all supported architectures.
• Lightweight: Built on Alpine Linux for minimal resource usage.

⁠Use Cases

• Home Networks: Block ads and trackers across all devices connected to your home network.
• Custom DNS Routing: Use DNSProxy to route DNS queries through secure protocols like DoH or DoT.
• Privacy-Focused Networks: Protect your network from DNS leaks and ensure privacy with DNSCrypt.

⁠How It Works

1. Pi-hole: Acts as the primary DNS server, blocking ads and trackers at the network level.
2. DNSProxy: Runs alongside Pi-hole to handle advanced DNS routing and encryption, forwarding queries to upstream DNS servers securely.
3. Entrypoint Script: A custom entrypoint script (dnsproxy-run.sh) ensures both services start and run concurrently.

⁠Getting Started

⁠1. Pull the Image

Pull the latest version of the image from Docker Hub:

docker pull xehmad/pihole-dnsproxy:latest

⁠2. Run the Container

Run the container with the necessary ports and volumes:

docker run -d --name pihole-dnsproxy -p 53:53/udp -p 53:53/tcp   -p 443:443/tcp -p 443:443/udp  -e FTLCONF_webserver_api_password="YourPassword" -e FTLCONF_dns_upstreams="127.0.0.1#5053"  xehmad/pihole-dnsproxy:latest

⁠3. Access the Web Interface

Access the Pi-hole admin interface at https://<your-server-ip>/admin.

⁠4. Configure DNSProxy

Edit the dnsproxy.conf file to customize DNSProxy settings, such as enabling DoH, DoT, or DNSCrypt. Example configuration:

listen=0.0.0.0:5053
upstream=https://dns.google/dns-query # DoH
upstream=tls://dns.quad9.net # DoT
dnscrypt=sdns://example-dnscrypt-server

-v /path/to/dnsproxy.conf:/etc/dnsproxy/dnsproxy.conf:ro

⁠5. Advanced DNS Features

DNSProxy supports the following advanced DNS protocols:

• DoH (DNS-over-HTTPS): Encrypt DNS queries over HTTPS using upstream servers like Cloudflare (https://cloudflare-dns.com/dns-query) or Google (https://dns.google/dns-query).
• DoT (DNS-over-TLS): Secure DNS queries using TLS with upstream servers like Quad9 (tls://dns.quad9.net).
• DNSCrypt: Protect against DNS spoofing and eavesdropping with DNSCrypt-enabled servers.
• Fallback Servers: Configure multiple upstream servers for redundancy and reliability.

Example dnsproxy.conf for advanced use cases:

listen=0.0.0.0:5053
upstream=https://cloudflare-dns.com/dns-query # DoH
upstream=tls://dns.quad9.net # DoT
dnscrypt=sdns://example-dnscrypt-server
fallback=https://dns.google/dns-query

⁠Contributing

Contributions are welcome! If you encounter issues or have suggestions, please open an issue or submit a pull request.

⁠License

This project is licensed under the MIT License⁠.