Skip to content
Fiction Becomes Fact

Unbound container setup

Introduction

Pi-hole is a network-level ad blocker that acts as a DNS sinkhole, filtering out unwanted advertisements and tracking domains to enhance privacy and improve browsing speed. Using Unbound in combination with Pi-hole allows you to run a recursive DNS server, adding an extra layer of privacy by ensuring DNS queries are resolved locally without relying on third-party DNS providers.

Setup

  1. Create the network dns-net

    You need to create a Docker network first, this will also allow Pi-hole to communicate with Unbound.

    Run the following command:

    # Open your terminal application
    sudo docker network create --driver=bridge --subnet=172.19.0.0/16 --gateway=172.19.0.1 dns-net
  2. Create the folders needed by the container

    Run the following commands inside your home folder:

    # Open your terminal application
    cd ~
    mkdir -p unbound/etc-unbound
    cd unbound
  3. Download root.hints

    The root.hints file is not often changed but you can run the command below (or use the crontab) every 6 months to be sure. Run the following command:

    # Open your terminal application
    sudo wget -O root.hints https://www.internic.net/domain/named.root
  4. Create unbound.conf

    Save the following configuration as unbound.conf:

    Terminal window
    # unbound.conf
    # To create this script use your text editor application, for example Nano
    server:
      ## To listen on all interfaces use:
      interface: 0.0.0.0@5053
    

      do-ip4: yes
      do-udp: yes
      do-tcp: yes
    

      # May be set to yes if you have IPv6 connectivity
      do-ip6: no
    

      # You want to leave this to no unless you have *native* IPv6. With 6to4 and
      # Terredo tunnels your web browser should favor IPv4 for the same reasons
      prefer-ip6: no
    

      do-daemonize: no
    

      access-control: 127.0.0.1/32 allow
      access-control: 192.168.0.0/16 allow
      access-control: 172.16.0.0/12 allow
      access-control: 10.0.0.0/8 allow
    

      logfile: ""
    

      # If no logfile is specified, syslog is used
      # logfile: "/var/log/unbound/unbound.log"
      verbosity: 0
    

      # Use this only when you downloaded the list of primary root servers!
      root-hints: "/opt/unbound/etc/unbound/root.hints"
    

      # Trust glue only if it is within the servers authority
      harden-glue: yes
    

      # Require DNSSEC data for trust-anchored zones, if such data is absent, the zone becomes BOGUS
      harden-dnssec-stripped: yes
    

      # Don't use Capitalization randomization as it known to cause DNSSEC issues sometimes
      # see https://discourse.pi-hole.net/t/unbound-stubby-or-dnscrypt-proxy/9378 for further details
      use-caps-for-id: no
    

      # Reduce EDNS reassembly buffer size.
      # Suggested by the unbound man page to reduce fragmentation reassembly problems
      edns-buffer-size: 1472
    

      # TTL bounds for cache
      cache-min-ttl: 3600
      cache-max-ttl: 86400
    

      # Perform prefetching of close to expired message cache entries
      # This only applies to domains that have been frequently queried
      prefetch: yes
    

      # One thread should be sufficient, can be increased on beefy machines
      num-threads: 1
    

      # Ensure kernel buffer is large enough to not loose messages in traffic spikes
      #so-rcvbuf: 1m
      # Ensure privacy of local IP ranges
      private-address: 192.168.0.0/16
      private-address: 169.254.0.0/16
      private-address: 172.16.0.0/12
      private-address: 10.0.0.0/8
      private-address: fd00::/8
      private-address: fe80::/10
  5. Create the script needed to run the container

    Save the following script as unbound_run.sh:

    unbound_run.sh
    # To create this script use your text editor application, for example Nano
    docker run -d \
    --name=unbound \
    --hostname=unbound \
    --network=dns-net \
    --ip=172.19.0.5 \
    -p 5053:5053/tcp \
    -p 5053:5053/udp \
    -v $PWD/etc-unbound:/opt/unbound/etc/unbound \
    --restart=unless-stopped \
    klutchell/unbound
    # IMPORTANT: Please read the instructions below
    Instructions:
    • Optional Replace docker with podman if needed
    • Optional The setting --ip=172.19.0.5 contains the fixed IP address of the container in the range of the dns-net network, you can change this if needed
    • Optional The settings -p 5053:5053/tcp and -p 5053:5053/udp contains the ports used by Unbound. The port number is for example used by Pi-hole as part of the custom upstream DNS server. Do not forget to also change the interface in the configuration file unbound.conf
  6. Run the script to create the container

    Run the following command:

    # Open your terminal application
    sudo sh unbound_run.sh

    The image klutchell/unbound is automatically pulled and the container is created.

  7. Check the results

    If needed you can check if the container is running properly.

    Run the following command to check if Unbound is working properly:

    # Test Pi-hole with dig
    dig pi-hole.net @127.0.0.1 -p 5053

    If you want to use Unbound with Pi-hole make sure Unbound is configured within Pi-hole as Upstream DNS server. There you can add the IP and port 172.19.0.5#5053 as Custom 1 (IPv4).

Comments

    No comments found for this note.

    Join the discussion for this note on Github. Comments appear on this page instantly.

    Tags:
    Copyright 2021- Fiction Becomes Fact