If you’re looking to set up a secure and efficient DNS (Domain Name System) resolver, Unbound is an excellent option. This lightweight, high-performance recursive DNS resolver is favored for its security features and speed. With Docker, you can easily run Unbound in a containerized environment, providing flexibility and isolation for DNS services.
In this guide, we’ll walk you through the process of setting up Unbound Recursive DNS Resolver on Docker. Whether you’re running a home network, testing configurations, or managing multiple DNS queries, this setup will improve your DNS performance while providing control over your network’s traffic.
What You Need Before You Start
Before we dive into the technical setup, ensure you have the following:
- A Linux-based machine (Ubuntu, Debian, etc.) or a virtual machine running Docker.
- Docker installed on the system.
- Basic familiarity with terminal commands and configuration files.
If you’re unfamiliar with Docker, it’s a tool used to create, deploy, and run applications in containers. Docker containers are isolated environments that contain everything needed to run an application: code, libraries, dependencies, and configurations.
Step 1: Preparing the Environment
The first step is to create the directory where Unbound will store its configuration files. This is where we’ll mount our Docker container later to share configurations between your host machine and the Unbound container.
Run the following command to create the necessary directory:
mkdir -p /opt/unbound/etc/unbound/
This command creates the unbound directory in the /opt directory, which will house all Unbound-related configurations.
Step 2: Downloading the Unbound Configuration File
Next, you need to download the default Unbound configuration file. This file contains essential settings that allow the DNS resolver to function properly. We’ll fetch the file from a GitHub repository for ease of setup.
Navigate to the unbound directory and download the configuration:
cd /opt/unbound/etc/unbound/
wget https://raw.githubusercontent.com/MatthewVance/unbound-docker/refs/heads/master/unbound.conf
This will fetch the latest version of the Unbound configuration file into the /opt/unbound/etc/unbound/ directory.
server:
###########################################################################
# BASIC SETTINGS
###########################################################################
# Time to live maximum for RRsets and messages in the cache. If the maximum
# kicks in, responses to clients still get decrementing TTLs based on the
# original (larger) values. When the internal TTL expires, the cache item
# has expired. Can be set lower to force the resolver to query for data
# often, and not trust (very large) TTL values.
cache-max-ttl: 86400
# Time to live minimum for RRsets and messages in the cache. If the minimum
# kicks in, the data is cached for longer than the domain owner intended,
# and thus less queries are made to look up the data. Zero makes sure the
# data in the cache is as the domain owner intended, higher values,
# especially more than an hour or so, can lead to trouble as the data in
# the cache does not match up with the actual data any more.
cache-min-ttl: 300
# Set the working directory for the program.
directory: "/opt/unbound/etc/unbound"
# Enable or disable whether IPv4 queries are answered or issued.
# Default: yes
do-ip4: yes
# Enable or disable whether IPv6 queries are answered or issued.
# If disabled, queries are not answered on IPv6, and queries are not sent
# on IPv6 to the internet nameservers. With this option you can disable the
# IPv6 transport for sending DNS traffic, it does not impact the contents
# of the DNS traffic, which may have IPv4 (A) and IPv6 (AAAA) addresses in
# it.
# Default: yes
# May be set to yes if you have IPv6 connectivity
do-ip6: yes
# Enable or disable whether TCP queries are answered or issued.
# Default: yes
do-tcp: yes
# Enable or disable whether UDP queries are answered or issued.
# Default: yes
do-udp: yes
# RFC 6891. Number of bytes size to advertise as the EDNS reassembly buffer
# size. This is the value put into datagrams over UDP towards peers.
# The actual buffer size is determined by msg-buffer-size (both for TCP and
# UDP). Do not set higher than that value.
# Default is 1232 which is the DNS Flag Day 2020 recommendation.
# Setting to 512 bypasses even the most stringent path MTU problems, but
# is seen as extreme, since the amount of TCP fallback generated is
# excessive (probably also for this resolver, consider tuning the outgoing
# tcp number).
edns-buffer-size: 1232
# Listen to for queries from clients and answer from this network interface
# and port.
interface: 0.0.0.0@53
# interface: ::0
port: 53
# If enabled, prefer IPv6 transport for sending DNS queries to internet
# nameservers.
# Default: yes
# 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
# Rotates RRSet order in response (the pseudo-random number is taken from
# the query ID, for speed and thread safety).
rrset-roundrobin: yes
# Drop user privileges after binding the port.
username: "_unbound"
###########################################################################
# LOGGING
###########################################################################
# Do not print log lines to inform about local zone actions
log-local-actions: no
# Do not print one line per query to the log
log-queries: no
# Do not print one line per reply to the log
log-replies: no
# Do not print log lines that say why queries return SERVFAIL to clients
log-servfail: no
# If you want to log to a file, use:
# logfile: /opt/unbound/etc/unbound/unbound.log
# Set log location (using /dev/null further limits logging)
logfile: /dev/null
# Set logging level
# Level 0: No verbosity, only errors.
# Level 1: Gives operational information.
# Level 2: Gives detailed operational information including short information per query.
# Level 3: Gives query level information, output per query.
# Level 4: Gives algorithm level information.
# Level 5: Logs client identification for cache misses.
verbosity: 0
###########################################################################
# PERFORMANCE SETTINGS
###########################################################################
# https://nlnetlabs.nl/documentation/unbound/howto-optimise/
# https://nlnetlabs.nl/news/2019/Feb/05/unbound-1.9.0-released/
# Number of slabs in the infrastructure cache. Slabs reduce lock contention
# by threads. Must be set to a power of 2.
infra-cache-slabs: 4
# Number of incoming TCP buffers to allocate per thread. Default
# is 10. If set to 0, or if do-tcp is "no", no TCP queries from
# clients are accepted. For larger installations increasing this
# value is a good idea.
incoming-num-tcp: 10
# Number of slabs in the key cache. Slabs reduce lock contention by
# threads. Must be set to a power of 2. Setting (close) to the number
# of cpus is a reasonable guess.
key-cache-slabs: 4
# Number of bytes size of the message cache.
# Unbound recommendation is to Use roughly twice as much rrset cache memory
# as you use msg cache memory.
msg-cache-size: 142768128
# Number of slabs in the message cache. Slabs reduce lock contention by
# threads. Must be set to a power of 2. Setting (close) to the number of
# cpus is a reasonable guess.
msg-cache-slabs: 4
# The number of queries that every thread will service simultaneously. If
# more queries arrive that need servicing, and no queries can be jostled
# out (see jostle-timeout), then the queries are dropped.
# This is best set at half the number of the outgoing-range.
# This Unbound instance was compiled with libevent so it can efficiently
# use more than 1024 file descriptors.
num-queries-per-thread: 4096
# The number of threads to create to serve clients.
# This is set dynamically at run time to effectively use available CPUs
# resources
num-threads: 3
# Number of ports to open. This number of file descriptors can be opened
# per thread.
# This Unbound instance was compiled with libevent so it can efficiently
# use more than 1024 file descriptors.
outgoing-range: 8192
# Number of bytes size of the RRset cache.
# Use roughly twice as much rrset cache memory as msg cache memory
rrset-cache-size: 285536256
# Number of slabs in the RRset cache. Slabs reduce lock contention by
# threads. Must be set to a power of 2.
rrset-cache-slabs: 4
# Do no insert authority/additional sections into response messages when
# those sections are not required. This reduces response size
# significantly, and may avoid TCP fallback for some responses. This may
# cause a slight speedup.
minimal-responses: yes
# # Fetch the DNSKEYs earlier in the validation process, when a DS record
# is encountered. This lowers the latency of requests at the expense of
# little more CPU usage.
prefetch: yes
# Fetch the DNSKEYs earlier in the validation process, when a DS record is
# encountered. This lowers the latency of requests at the expense of little
# more CPU usage.
prefetch-key: yes
# Have unbound attempt to serve old responses from cache with a TTL of 0 in
# the response without waiting for the actual resolution to finish. The
# actual resolution answer ends up in the cache later on.
serve-expired: yes
# If not 0, then set the SO_RCVBUF socket option to get more buffer space on
# UDP port 53 incoming queries. So that short spikes on busy servers do not
# drop packets (see counter in netstat -su). Otherwise, the number of bytes
# to ask for, try “4m” on a busy server.
# The OS caps it at a maximum, on linux Unbound needs root permission to
# bypass the limit, or the admin can use sysctl net.core.rmem_max.
# Default: 0 (use system value)
# For example: sysctl -w net.core.rmem_max=4194304
# To persist reboots, edit /etc/sysctl.conf to include:
# net.core.rmem_max=4194304
# Larger socket buffer. OS may need config.
# Ensure kernel buffer is large enough to not lose messages in traffic spikes
#so-rcvbuf: 4m
# Open dedicated listening sockets for incoming queries for each thread and
# try to set the SO_REUSEPORT socket option on each socket. May distribute
# incoming queries to threads more evenly.
so-reuseport: yes
# If not 0, then set the SO_SNDBUF socket option to get more buffer space
# on UDP port 53 outgoing queries.
# Specify the number of bytes to ask for, try “4m” on a very busy server.
# The OS caps it at a maximum, on linux Unbound needs root permission to
# bypass the limit, or the admin can use sysctl net.core.wmem_max.
# For example: sysctl -w net.core.wmem_max=4194304
# To persist reboots, edit /etc/sysctl.conf to include:
# net.core.wmem_max=4194304
# Default: 0 (use system value)
# Larger socket buffer. OS may need config.
# Ensure kernel buffer is large enough to not lose messages in traffic spikes
#so-sndbuf: 4m
###########################################################################
# PRIVACY SETTINGS
###########################################################################
# RFC 8198. Use the DNSSEC NSEC chain to synthesize NXDO-MAIN and other
# denials, using information from previous NXDO-MAINs answers. In other
# words, use cached NSEC records to generate negative answers within a
# range and positive answers from wildcards. This increases performance,
# decreases latency and resource utilization on both authoritative and
# recursive servers, and increases privacy. Also, it may help increase
# resilience to certain DoS attacks in some circumstances.
aggressive-nsec: yes
# Extra delay for timeouted UDP ports before they are closed, in msec.
# This prevents very delayed answer packets from the upstream (recursive)
# servers from bouncing against closed ports and setting off all sort of
# close-port counters, with eg. 1500 msec. When timeouts happen you need
# extra sockets, it checks the ID and remote IP of packets, and unwanted
# packets are added to the unwanted packet counter.
delay-close: 10000
# Prevent the unbound server from forking into the background as a daemon
do-daemonize: no
# Add localhost to the do-not-query-address list.
do-not-query-localhost: no
# Number of bytes size of the aggressive negative cache.
neg-cache-size: 4M
# Send minimum amount of information to upstream servers to enhance
# privacy (best privacy).
qname-minimisation: yes
###########################################################################
# SECURITY SETTINGS
###########################################################################
# Only give access to recursion clients from LAN IPs
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
access-control: fc00::/7 allow
access-control: ::1/128 allow
# File with trust anchor for one zone, which is tracked with RFC5011
# probes.
auto-trust-anchor-file: "var/root.key"
# Enable chroot (i.e, change apparent root directory for the current
# running process and its children)
chroot: "/opt/unbound/etc/unbound"
# Deny queries of type ANY with an empty response.
deny-any: yes
# Harden against algorithm downgrade when multiple algorithms are
# advertised in the DS record.
harden-algo-downgrade: yes
# RFC 8020. returns nxdomain to queries for a name below another name that
# is already known to be nxdomain.
harden-below-nxdomain: yes
# Require DNSSEC data for trust-anchored zones, if such data is absent, the
# zone becomes bogus. If turned off you run the risk of a downgrade attack
# that disables security for a zone.
harden-dnssec-stripped: yes
# Only trust glue if it is within the servers authority.
harden-glue: yes
# Ignore very large queries.
harden-large-queries: yes
# Perform additional queries for infrastructure data to harden the referral
# path. Validates the replies if trust anchors are configured and the zones
# are signed. This enforces DNSSEC validation on nameserver NS sets and the
# nameserver addresses that are encountered on the referral path to the
# answer. Experimental option.
harden-referral-path: no
# Ignore very small EDNS buffer sizes from queries.
harden-short-bufsize: yes
# If enabled the HTTP header User-Agent is not set. Use with caution
# as some webserver configurations may reject HTTP requests lacking
# this header. If needed, it is better to explicitly set the
# the http-user-agent.
hide-http-user-agent: no
# Refuse id.server and hostname.bind queries
hide-identity: yes
# Refuse version.server and version.bind queries
hide-version: yes
# Set the HTTP User-Agent header for outgoing HTTP requests. If
# set to "", the default, then the package name and version are
# used.
http-user-agent: "DNS"
# Report this identity rather than the hostname of the server.
identity: "DNS"
# These private network addresses are not allowed to be returned for public
# internet names. Any occurrence of such addresses are removed from DNS
# answers. Additionally, the DNSSEC validator may mark the answers bogus.
# This protects against DNS Rebinding
private-address: 10.0.0.0/8
private-address: 172.16.0.0/12
private-address: 192.168.0.0/16
private-address: 169.254.0.0/16
private-address: fd00::/8
private-address: fe80::/10
private-address: ::ffff:0:0/96
# Enable ratelimiting of queries (per second) sent to nameserver for
# performing recursion. More queries are turned away with an error
# (servfail). This stops recursive floods (e.g., random query names), but
# not spoofed reflection floods. Cached responses are not rate limited by
# this setting. Experimental option.
ratelimit: 1000
# Use this certificate bundle for authenticating connections made to
# outside peers (e.g., auth-zone urls, DNS over TLS connections).
tls-cert-bundle: /etc/ssl/certs/ca-certificates.crt
# Set the total number of unwanted replies to eep track of in every thread.
# When it reaches the threshold, a defensive action of clearing the rrset
# and message caches is taken, hopefully flushing away any poison.
# Unbound suggests a value of 10 million.
unwanted-reply-threshold: 10000
# Use 0x20-encoded random bits in the query to foil spoof attempts. This
# perturbs the lowercase and uppercase of query names sent to authority
# servers and checks if the reply still has the correct casing.
# This feature is an experimental implementation of draft dns-0x20.
# Experimental option.
# Don't use Capitalization randomization as it known to cause DNSSEC issues
# see https://discourse.pi-hole.net/t/unbound-stubby-or-dnscrypt-proxy/9378
use-caps-for-id: yes
# Help protect users that rely on this validator for authentication from
# potentially bad data in the additional section. Instruct the validator to
# remove data from the additional section of secure messages that are not
# signed properly. Messages that are insecure, bogus, indeterminate or
# unchecked are not affected.
val-clean-additional: yes
###########################################################################
# FORWARD ZONE
###########################################################################
# include: /opt/unbound/etc/unbound/forward-records.conf
###########################################################################
# LOCAL ZONE
###########################################################################
# Include file for local-data and local-data-ptr
include: /opt/unbound/etc/unbound/a-records.conf
include: /opt/unbound/etc/unbound/srv-records.conf
###########################################################################
# WILDCARD INCLUDE
###########################################################################
#include: "/opt/unbound/etc/unbound/*.conf"
remote-control:
control-enable: noStep 3: Configuring Custom DNS Records
Once the base configuration is in place, you may want to add some custom DNS records for your internal network. This is where you can define A records, PTR records, and even SRV records to customize how your DNS resolver handles requests.
Let’s start by adding A records (Address records) to define the mappings between domain names and IP addresses.
Adding A Records
Use a text editor to open the configuration file:
vim a-records.conf
Inside the file, add the following lines for your custom A records:
# A Record
#local-data: "somecomputer.local. A 192.168.1.1"
local-data: "laptop.local. A 192.168.1.2"
In this case, we’re mapping laptop.local to the IP address 192.168.1.2. Feel free to modify this based on your network’s IP addresses.
Adding PTR Records
Next, open the PTR records configuration file:
vim srv-records.conf
For PTR records (Reverse DNS), add the following:
# PTR Record
#local-data-ptr: "192.168.1.1 somecomputer.local."
local-data-ptr: "192.168.1.2 laptop.local."
These reverse DNS mappings allow you to resolve IP addresses back to hostnames, useful for troubleshooting and network diagnostics.
Step 4: Configuring SRV Records
For some services, like LDAP or SIP, you might want to define SRV records (Service records) to specify the location of services within your domain. These records provide information such as the port number, target host, and the priority/weight of each service.
Open the SRV records configuration:
vim srv-records.conf
Add the following example SRV records:
# SRV records
# _service._proto.name. | TTL | class | SRV | priority | weight | port | target.
Here, you can define the services your DNS resolver should handle. Customize this file based on the specific services you’re offering.
Step 5: Running Unbound in Docker
Now that the configuration files are in place, you’re ready to run Unbound in a Docker container. This process allows you to isolate your DNS resolver while still providing full control over its settings and performance.
Run the following Docker command to start Unbound:
docker run --name=my-unbound \
--detach=true \
--publish=5553:53/tcp \
--publish=5553:53/udp \
--restart=unless-stopped \
--volume=/opt/unbound/etc/unbound/:/opt/unbound/etc/unbound/ \
mvance/unbound:latest
Let’s break down what’s happening here:
--name=my-unbound: This gives your Docker container a name, making it easier to reference later.--detach=true: Runs the container in detached mode, meaning it runs in the background.--publish=5553:53/tcpand--publish=5553:53/udp: Exposes port 53 (DNS) on the container to port 5553 on your host. DNS typically operates on port 53, but we’re mapping it to port 5553 for ease of testing.--restart=unless-stopped: Ensures the container automatically restarts if it crashes or the system reboots.--volume=/opt/unbound/etc/unbound/:/opt/unbound/etc/unbound/: This mounts the configuration directory you created earlier to the container, so the container uses your custom settings.
With this command, your Unbound DNS resolver will be up and running, ready to handle DNS queries.
Step 6: Verifying Unbound’s DNS Status
After running the Docker container, it’s crucial to verify that the DNS resolver is working correctly. Use the following command to check if the service is listening on the appropriate port:
sudo ss -lnptu | grep 5553If everything is set up correctly, you should see output indicating that Unbound is actively listening for DNS queries on port 5553.
Step 7: Configuring Your System to Use Unbound
At this point, your Unbound recursive DNS resolver is running inside a Docker container, but to make use of it, you’ll need to configure your system or network to point to your Docker container for DNS resolution.
To use the newly set up Unbound resolver, you must configure the DNS settings of your machine or router to point to the Docker container’s IP address and port.
For example, on a Linux machine, you would update the /etc/resolv.conf file:
nameserver 127.0.0.1This directs your machine to query your local Unbound container for DNS resolution.
The /etc/resolv.conf config file doesn’t support any form of alternative port number, so will only connect natively via port 53.
The only way to achieve what you’re looking for is to have something in the middle to take the port 53 request from the client, change it to use another port and then deliver that request to the server.
The way is to use iptables to reroute that internal request as needed:
iptables -t nat -A OUTPUT -p tcp -d 127.0.0.1 --dport 53 -j DNAT --to-destination 127.0.0.1:5553
iptables -t nat -A OUTPUT -p udp -d 127.0.0.1 --dport 53 -j DNAT --to-destination 127.0.0.1:5553Troubleshooting
If you encounter any issues with Unbound, here are a few tips:
- Check Docker logs: If Unbound isn’t responding, check the logs of the Docker container for errors:
docker logs my-unbound - Check firewall settings: Ensure that your firewall is not blocking DNS traffic on port 5553.
- Test with
digornslookup: Use tools likedigornslookupto test DNS queries:
dig @127.0.0.1 -p 5553 example.comConclusion
In summary, setting up a recursive DNS resolver with Unbound on Docker is a simple and effective way to improve the speed and security of your DNS queries. The Docker container isolates the DNS resolver, offering flexibility and scalability, while the Unbound configuration gives you full control over the DNS process.
Now that you’ve followed the steps to configure Unbound and Docker, you can confidently manage DNS queries in your network. If you run into any issues, the troubleshooting tips should help resolve them.
As we move forward, the demand for fast and secure DNS resolution will continue to grow. This setup ensures you stay ahead by providing a robust and customizable solution for your DNS needs.
Leave a Reply