How to Use Docker to Set Up Pi-hole and Unbound for Ad Blocking

By /

How to Use Docker to Set Up Pi-hole and Unbound for Network-Wide Ad Blocking

This comprehensive guide will walk you through setting up a robust and private ad-blocking solution for your entire network using Docker, Pi-hole, and Unbound. Pi-hole acts as a DNS sinkhole, intercepting ad requests and redirecting them to a null IP address. Unbound, a validating, recursive, and caching DNS resolver, complements Pi-hole by providing faster DNS resolution and enhanced privacy by reducing reliance on external DNS servers. Docker containerization simplifies the installation, management, and maintenance of both services.

I. Understanding the Components

  • Docker: A platform that uses containerization to package, distribute, and run applications. Containers isolate applications from the underlying operating system, ensuring consistent performance across different environments and simplifying deployment.

  • Pi-hole: A network-wide ad blocker that works at the DNS level. It intercepts DNS queries for known ad domains and redirects them to a blackhole, effectively blocking ads on all devices connected to your network.

  • Unbound: A validating, recursive, and caching DNS resolver. It ensures DNS responses are authentic and provides faster DNS resolution by caching results. Using Unbound with Pi-hole enhances privacy by minimizing reliance on third-party DNS servers like Google Public DNS or Cloudflare DNS.

II. Prerequisites

  • A device capable of running Docker (e.g., Raspberry Pi, server, desktop computer).
  • A working internet connection.
  • Basic understanding of networking concepts like IP addresses, DNS, and port forwarding.
  • Familiarity with using the command line/terminal.

III. Installing Docker and Docker Compose

The installation process for Docker and Docker Compose varies depending on your operating system. Consult the official Docker documentation for detailed instructions for your specific platform:

  • Linux: Most Linux distributions offer Docker in their repositories. You can usually install it using your package manager (e.g., apt-get, yum, dnf). Docker Compose can be installed separately.
  • macOS: Docker Desktop for Mac provides a convenient way to install both Docker and Docker Compose.
  • Windows: Docker Desktop for Windows offers a similar installation experience for Windows users.

IV. Setting Up the Docker Compose File

Create a directory for your Pi-hole and Unbound configuration. Inside this directory, create a file named docker-compose.yml. This file will define the services and their configuration.

Paste the following content into docker-compose.yml:

“`yaml
version: “3.3”

services:
pihole:
image: pihole/pihole:latest
container_name: pihole
ports:
– “53:53/tcp”
– “53:53/udp”
– “67:67/udp” # For DHCP if required
– “8080:80/tcp” # For the web interface
volumes:
– “./pihole/etc-pihole:/etc/pihole”
– “./pihole/etc-dnsmasq.d:/etc/dnsmasq.d”
environment:
– TZ=YOUR_TIMEZONE # Replace with your timezone
– WEBPASSWORD=YOUR_PASSWORD # Set a strong password
– SERVERIP=YOUR_SERVER_IP # Replace with your server’s IP address
– DNS1=127.0.0.1 # Use Unbound for DNS resolution
– DNS2=1.1.1.1 # Fallback DNS (optional)
dns:
– 127.0.0.1
cap_add:
– NET_ADMIN # Required for DNS functionality
restart: unless-stopped

unbound:
image: mvance/unbound:latest
container_name: unbound
ports:
– “5353:53/udp” # For DNS queries from Pi-hole
volumes:
– “./unbound/unbound.conf.d:/config”
restart: unless-stopped
“`

V. Configuring Unbound

Create a directory named unbound within your configuration directory. Inside the unbound directory, create a file named unbound.conf.d. This directory will contain your Unbound configuration files.

Create a file named unbound.conf within the unbound.conf.d directory and paste the following configuration:

“`conf
server:
# Interface to bind to.
interface: 0.0.0.0
# Port to listen on.
port: 5353
# Enable DNSSEC validation.
do-dnssec: yes
# Enable query caching.
cache-min-ttl: 300
cache-max-ttl: 86400
# Enable prefetching.
prefetch: yes
# Verbosity level.
verbosity: 1
# Root hints file.
root-hints: “/config/root.hints”

forward-zone:
name: “.”
forward-addr: 1.1.1.1@853 # Cloudflare DNS over TLS
forward-addr: 1.0.0.1@853 # Cloudflare DNS over TLS
forward-ssl-upstream: yes

include: “/config/stub-resolvers.conf”
“`

You’ll also need a root.hints file in the unbound.conf.d directory. You can download the latest root hints file from the IANA website or use the following command in your terminal:

bash
curl -o ./unbound/unbound.conf.d/root.hints https://www.iana.org/dns/sec/files/named.root

VI. Starting Pi-hole and Unbound

Navigate to your configuration directory in the terminal and run the following command:

bash
docker-compose up -d

This command will build the containers and start them in detached mode.

VII. Configuring Pi-hole

Once the containers are running, access the Pi-hole web interface by navigating to http://YOUR_SERVER_IP:8080/ in your web browser. You’ll be prompted to set an administrator password during the initial setup.

VIII. Configuring Your Router’s DNS Settings

To use Pi-hole and Unbound for network-wide ad blocking, you need to configure your router to use your server’s IP address as its primary DNS server. The IP address should be the same as the one you specified in the SERVERIP environment variable in your docker-compose.yml file. Consult your router’s documentation for instructions on how to change DNS settings.

IX. Adding Blocklists (Optional)

Pi-hole comes with default blocklists, but you can add more for enhanced ad blocking. You can find curated lists of blocklists online. Add them through the Pi-hole web interface under the “Blocklists” section.

X. Whitelisting Domains (Optional)

If you encounter issues with legitimate websites being blocked, you can whitelist specific domains through the Pi-hole web interface under the “Whitelist” section.

XI. Maintaining Pi-hole and Unbound

Regularly updating Pi-hole and Unbound is crucial for maintaining optimal performance and security. You can update the containers by running the following commands in your configuration directory:

bash
docker-compose pull
docker-compose up -d --force-recreate

XII. Troubleshooting

  • Pi-hole web interface is inaccessible: Ensure Docker is running and the containers are started. Check the container logs for any errors using docker-compose logs. Verify the SERVERIP and port mappings in your docker-compose.yml file.

  • Ads are still showing: Double-check your router’s DNS settings. Ensure your devices are using the correct DNS server. Clear your browser cache and DNS cache. Verify that Unbound is resolving DNS queries correctly.

  • Slow DNS resolution: Check Unbound’s logs for errors. Ensure your fallback DNS servers are functioning correctly. Consider adjusting Unbound’s caching settings.

XIII. Security Considerations

  • Strong Password: Use a strong password for the Pi-hole web interface.

  • Regular Updates: Keep your Docker images, Pi-hole, and Unbound updated to patch security vulnerabilities.

  • Firewall: Consider configuring a firewall to limit access to your Pi-hole and Unbound containers.

XIV. Conclusion

This guide provides a comprehensive overview of setting up Pi-hole and Unbound with Docker for network-wide ad blocking. By combining these powerful tools within a containerized environment, you gain a robust, private, and easily manageable ad-blocking solution that significantly improves your browsing experience. Remember to regularly update your containers and blocklists to maintain optimal performance and security. With a little effort, you can reclaim control over your network and enjoy an ad-free internet experience.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top