Table of content

Setup
unbound-control

Setup

$ apt install unbound

unbound-control

With unbound-control you can interact with the cache of unbound, like flushing zones, dump the full cache or even load a full cache.

Setup and preperation for unbound-control

To use unbound-control you have to fist initialise it. unbound-control requiers an authentication over certificate. To generate local authentication files, you can run the command unbound-control-setup

This will give you an output like that:

$ unbound-control-setup
setup in directory /etc/unbound
Generating RSA private key, 3072 bit long modulus (2 primes)
...........................................++++
.................++++
e is 65537 (0x010001)
Signature ok
subject=CN = unbound-control
Getting CA Private Key
removing artifacts
Setup success. Certificates created. Enable in unbound.conf file to use

Inside of your unbound.conf the control function needs to be enabled now by adding the lines:

remote-control:
    control-enable: yes
    server-cert-file: "/etc/unbound/unbound_server.pem"
    control-key-file: "/etc/unbound/unbound_control.key"
    control-cert-file: "/etc/unbound/unbound_control.pem"

if you are only using the controler from localhost, you can also think about adding the parameter controle-use-cert with value no, like this:

remote-control:
    control-enable: yes
    control-use-cert: no
    server-cert-file: "/etc/unbound/unbound_server.pem"
    control-key-file: "/etc/unbound/unbound_control.key"
    control-cert-file: "/etc/unbound/unbound_control.pem"

Than you dont need to take care about the certificates, but recomended is to is than to have the access-control inside of your server: section limited to localhost

server:
access-control: 127.0.0.0/24 allow

Add data to cache

Using DNS to block ad servers is a pretty common tactic nowadays. Entries can be added to return ‘0.0.0.0’ instead the actual ad server IP - preventing communication with the ad servers:

$ unbound-control local_zone "random-ad-server.com" redirect
$ unbound-control local_data "random-ad-server.com A 0.0.0.0"

Show cache

Unbound will allow you to interrogate it’s cache in multiple ways, one of which is by simply dumping the cache:

$ unbound-control dump_cache

Import cache

You may already have been wondering if Unbound would allow cache data to be imported: Yes, it does.

Simply dump the cache to a file:

$ unbound-control dump_cache > unbound.dump

Then, import the dump:

$ cat unbound.dump | unbound-control load_cache

Flush cache

Flush all data for zone

Suppose you wanted to clear all cache data for google.com. The following command will clear everything related to google.com from the cache:

$ unbound-control flush_zone google.com

This command has the potential to be slow especially for a zone like google.com. Chances are, there are many entries for google.com in your cache and Unbound needs to go looking for every one of them in the cache.

You may want to drill or dig for multiple record types related to google.com before running this command. You should notice that the TTLs start decrementing before running the command. After running the command, you should notice that the TTLs jump back up.

Flush partial zone data

Maybe you only want to clear instances of ‘www’ from the google.com zone in the cache and not others such as ‘maps’ or ‘mail’. The following will delete A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV and NAPTR records associated with www.google.com:

$ unbound-control flush www.google.com

Flush specific data for zone

A specific record type can also be specified in case you want clear one type and not others. For example, if you wanted to remove AAAA records but keep A records for www.google.com:

$ unbound-control flush_type name www.google.com

Error mesages

Error setting up SSL_CTXX client cert - key too small

This error refers to your local key generated by unbound-control-setup. Just remove the files /etc/unbound/unbound_control.{key,pem} and re-run the unbound-control-setup

Sharing is caring