For unbound users: add remote control to your configuration

A lot of users have implemented the unbound solution, described here.
You can add a section to the configuration file ( the example configuration only has a server: section). Add the following lines to tour configuration:

# Remote control config section.
	control-enable: yes

and sudo service unbound stop && sudo service unbound start (sudo service unbound restart also works - it’s a habit)

After this change, you will be able to send instructions to unbound from the command line.
First find unbound-control, the location will depend on the version you have implemented (I’m using the compiled (latest) version of unbound.

sudo find / -name unbound-control

Running unbound-control without any options will give you a list of commands you can use.

A useful command would be sudo /usr/sbin/unbound-control verbosity 1, this to increase the increase the logging level. You could increase the log level to identify a problem.
From the unbound man page:

verbosity: <number>
	The verbosity number, level 0 means no verbosity,  only  errors.
	Level  1  gives  operational information. Level 2 gives detailed
	operational information. Level 3 gives query level  information,
	output  per  query.   Level 4 gives algorithm level information.
	Level 5 logs client identification for cache misses.  Default is
 	level  1.  The verbosity can also be increased from the command-
 	line, see unbound(8).

Don’t forget to decrease the log level, when your done!!!

On systems with a lot of users, stopping and starting unbound has a severe impact on unbound’s performance.


There is a way to save / restore the unbound cache.
save: sudo /usr/sbin/unbound-control dump_cache > /etc/unbound/unbound_cache.dmp
restore: sudo /usr/sbin/unbound-control load_cache > /etc/unbound/unbound_cache.dmp

There is even solution to automate this, available in the contrib folder of the latest download. It contains a file
To push saving / restoring the cache to the limit, you could add the following to the service file (/lib/systemd/system/unbound.service):

ExecStartPost=-/etc/unbound/ -l /etc/unbound/unbound_cache.dmp
ExecStop=-/etc/unbound/ -s /etc/unbound/unbound_cache.dmp

and run sudo systemctl daemon-reload to inform the system about the changes.
The - sign in front of the path is a way to tell systemctl to continue, even if this command would fail. All commands in a service file are executed as root.

For these lines to work, you need to download and extract to /etc/unbound.
Don’t forget to edit, you need to edit the location of CONF and BASE

This might lead to a confusing status message, sudo service unbound status says:

 Active: active (running) since Fri 2018-12-28

but also says:

Process: 1222 ExecStartPost=/etc/unbound/ -l /etc/unbound/unbound_cache.dmp (code=exited, status=1/FAILURE)
  • Saving and restoring doesn’t seem to work if you reboot the system.
  • If unbound fails to start after a reboot, just delete the cache file (/etc/unbound/unbound_cache.dmp)

have fun…

1 Like

Is there a way to view the cache? That would be a good way to verify it's working.

/etc/unbound/unbound_cache.dmp is plain text, you can look at the content, using a simple text editor, parse it with a custom made script to get details.

example script code, get the NS records from the unbound dump

mapfile -t NSArray < <(sudo /usr/sbin/unbound-control dump_cache |  grep -P "IN\tNS" | sed '/NSEC/d')
for (( i=0; i<${#NSArray[@]}; i++ )); do
   IFS=$'\t' read -r zone ttl ignore2 ignore3 nameserver  <<< "${NSArray[i]}"
   if [[ $(echo "${zone::-1}" | grep '\.') ]]; then  
      echo "${nameserver}"

every time you run this, the ttl will be lower, until the ttl is zero, the entry will than simply disappear from the dump (and the cache)

I downloaded contrib/ from the latest link,

Edited CONF to /etc/unbound/and BASE to /usr in
copied to /etc/unbound/
but when I run from /etc/unbound/

$ sudo ./ -s /etc/unbound/unbound_cache.dmp
sudo: unable to execute ./ No such file or directory

chmod +x ./ ?

yea already did it

reran i get this error now

$ ./ 
-bash: ./ /sbin/sh: bad interpreter: No such file or directory

change the first line of the script from #!/sbin/sh into #!/bin/bash (tested on Raspbian (=Debian)

Good thanks,

$ sudo ./ 
Loading cache from saved /etc/unbound//unbound_cache.dmp...
-rw-r--r-- 1 root root 0 Aug 16 16:16 /etc/unbound//unbound_cache.dmp

but why is it taking forever ?

restarting the service is also taking forever

$ sudo systemctl restart unbound

probably depends on the content of the cache, check the filesize, on my (fresh installed 4 hours ago) system, it takes less than a 20 seconds.

it finished executing got this error:

error: could not SSL_read

part of my unbound config (remote control section, required to run unbound-control)

	# Remote control config section.
		control-enable: yes
		control-port: 8953
		server-key-file: "/etc/unbound/unbound_server.key"
		server-cert-file: "/etc/unbound/unbound_server.pem"
		control-key-file: "/etc/unbound/unbound_control.key"
		control-cert-file: "/etc/unbound/unbound_control.pem"

to get the keys (if I remember this correctly)

  1. get the icannbundle
sudo wget -O /etc/unbound/icannbundle.pem
  1. setup unbound-control
sudo /usr/sbin/unbound-control-setup

is icannbundle.pem same as unbound_control.pem or
is icannbundle.pem same as unbound_server.pem ?

I followed the steps and still getting the same error:

$ sudo ./ 
Loading cache from saved /etc/unbound//unbound_cache.dmp...
-rw-r--r-- 1 root root 0 Aug 16 16:17 /etc/unbound//unbound_cache.dmp
error: SSL handshake failed

I have the following files in /etc/unbound, files are all different

why don't you first try to run the config and command I mentioned in the first post of the topic, before trying to get the contrib script to work. Remember to restart unbound when you change the config.
I've never encountered SSL problems, so this is new territory.

$ sudo /usr/sbin/unbound-control-setup
setup in directory /etc/unbound
unbound_server.key exists
unbound_control.key exists
create unbound_server.pem (self signed certificate)
create unbound_control.pem (signed client certificate)
Signature ok
subject=CN = unbound-control
Getting CA Private Key
Setup success. Certificates created.

Could it be my pihole is behind ssl ?

I too have this :slight_smile:

$ ls -l /etc/unbound/
total 48

my system:

uname -a
Linux raspberrypi 5.4.51-v7+ #1333 SMP Mon Aug 10 16:45:19 BST 2020 armv7l GNU/Linux

run sudo apt-get update && sudo apt-get -y upgrade

I am not using raspberry pi I am using rockpi

$ uname -a
Linux rockpi 4.4.154-95-rockchip-gd2ab1f26e1b3 #1 SMP Mon Oct 21 06:42:35 UTC 2019 aarch64 aarch64 aarch64 GNU/Linux


I setup the unbound dns server on ubuntu 20.01 in a virtual box .
everything worked fine until I added these two lines in unbound.service.

ExecStartPost=-/etc/unbound/ -l /etc/unbound/unbound_cache.dmp
ExecStop=-/etc/unbound/ -s /etc/unbound/unbound_cache.dmp

now I started getting the same error as I was getting in my other ubuntu rockpi:

Aug 17 15:19:49 osboxes[74493]: Loading cache from saved /etc/unbound/unbound_cache.dmp...
Aug 17 15:19:50 osboxes[74494]: -rw-r--r-- 1 root root 0 Aug 17 15:16 /etc/unbound/unbound_cache.dmp
Aug 17 15:21:19 osboxes systemd[1]: unbound.service: Start-post operation timed out. Stopping.
Aug 17 15:21:19 osboxes unbound[74478]: [74478:0] error: could not SSL_read crypto error:00000000:lib(0):func(0):reason(0)

try this (control-use-cert: no). Untested, never had any SSL problems myself.

remember what I said in the first post: