DEV Community


Posted on

Setting Up a Recursive DNS Resolver Using Unbound on Docker

In this article, I'll walk through the steps to set up a recursive DNS resolver using Unbound on Docker. This resolver will handle DNS queries for a local domain by forwarding them to an authoritative nameserver while forwarding queries for other domains to external DNS servers like Google DNS.

This post is one part of building a local DNS service using docker-compose and the authoritative nameserver for is already built by this article.

I'll write the other remaining parts later.


  • Docker installed and running
  • A Docker network named internal-dns with subnet
  • An authoritative nameserver at for the domain

Directory Structure

Please ensure that you execute all the following commands within the internal-dns directory.

├── authoritative
│   └── ...
└── resolver
    ├── Dockerfile
    └── unbound.conf
Enter fullscreen mode Exit fullscreen mode

Create a Dockerfile

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y unbound && rm -rf /var/lib/apt/lists/*

COPY unbound.conf /etc/unbound/unbound.conf

CMD ["/usr/sbin/unbound", "-d", "-c", "/etc/unbound/unbound.conf"]
Enter fullscreen mode Exit fullscreen mode

This Dockerfile installs Unbound on an Ubuntu 22.04 base image and copies the unbound.conf configuration file, then setting the default command to run unbound with the -d flag (to run in the foreground) and the -c flag to specify the configuration file.

Create an unbound.conf

    access-control: allow
        control-enable: no
    name: ""
    name: "."
    forward-addr: # google DNS
    # forward-addr: # ISP provided DNS
Enter fullscreen mode Exit fullscreen mode

This configuration file sets up the following:

  • server section configures the Unbound server to listen on all interfaces ( on port 53 and allows queries from the subnet.
  • stub-zone section configures a stub zone for the domain, forwarding queries to the authoritative nameserver at
  • forward-zone section configures forwarding for all other domains to Google DNS ( You can also use your ISP's DNS server if preferred.

Building and Running

Build the Docker image:

sudo docker image build -t unbound-resolver resolver/
Enter fullscreen mode Exit fullscreen mode

Run the container for testing the configuration:

sudo docker container run --rm --name resolver-test --network internal-dns --ip unbound-resolver unbound-checkconf
Enter fullscreen mode Exit fullscreen mode

If the output shows unbound-checkconf: no errors in /etc/unbound/unbound.conf, then the configuration is valid.

Stop the resolver-test container and run a Unbound resolver container:

sudo docker container run --rm -d --name resolver --network internal-dns --ip unbound-resolver
Enter fullscreen mode Exit fullscreen mode


You can test the resolver by querying for a record in the domain:

dig @
Enter fullscreen mode Exit fullscreen mode

This should return the IP address configured for in the authoritative nameserver.

; <<>> DiG 9.18.18-0ubuntu0.22.04.2-Ubuntu <<>> @
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 64714
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

; EDNS: version: 0, flags:; udp: 1232
;        IN  A

;; ANSWER SECTION: 86400   IN  A

;; Query time: 0 msec
;; WHEN: Thu Mar 21 07:52:43 JST 2024
;; MSG SIZE  rcvd: 63
Enter fullscreen mode Exit fullscreen mode

With this setup, your devices on the subnet can use the resolver at to resolve DNS queries. The resolver will handle queries for by forwarding them to the authoritative nameserver while forwarding queries for other domains to external DNS servers.

What's Next

next, I'll use docker compose to build the authoritative nameserver container I set up in the previous article and the recursive resolver container I set up in this article.

It is necessary to configure networking in order to access these containers from other devices on the home network. (Yes, indeed currently these containers can only be accessed from the Ubuntu server on the host machine.)


Top comments (0)