Introduction
This tutorial explains how to set up our DNSvizor solution.
If you find typos, or find parts difficult to understand, please report an issue or pull request at the source repository.
The DNSvizor unikernel provides a recursive DNS resolver, and a DHCP server. Its configuration is close to dnsmasq.
Installation
You can download the unikernel binary from our reproducible build infrastructure. Download the bin/dnsvizor.hvt artifact.
You need as well solo5-hvt which our reproducible build infrastructure builds for select platforms.
If we don't build for your platform you need to build it yourself.
If you did all of that, skip to "DNSvizor Configuration".
Building from source (alternative)
Here we document how to build the unikernel from source.
Prerequisites
First, make sure to have "opam" and "mirage" installed on your system.
Git repository
Do a git clone https://github.com/robur-coop/dnsvizor.git to retrieve the
source code of DNSvizor.
Building
Inside of the cloned repository, execute mirage configure (other targets are
available, please check the mirage documentation):
$ cd dnsvizor/mirage
$ mirage configure -t hvt
$ make
The result is a binary, dist/dnsvizor.hvt, which we will use later.
You can as well configure it with metrics which are reported to InfluxDB by using mirage configure -t hvt --enable-monitoring.
If this is built, there are several command line options available:
--net:management=tapXand--net-mac:management=MACthe TAP device and mac address of the management interface--ipv4-management=192.168.0.42/24the IPv4 address for the management interface--monitor=<IP>the IP address of the InfluxDB server--syslog=<IP>the IP address of the syslog server
Building solo5 from source (alternative)
See the instructions in doc/building.md in the Solo5 source tree.
DNSvizor Configuration
The configuration is passed via command-line arguments. If you're lacking configuration options here, please open an issue at the dnsvizor repository.
Network configuration for the unikernel
All you need is a tap interface to run the unikernel on. You also need your unikernel to be reachable from the outside (on the listening port), and be able to communicate to the outside. There are multiple approaches to achieve this, we will focus on setting up your firewall for this:
$ sysctl -w net.ipv4.ip_forward=1
$ ip route list default | cut -d' ' -f5
eth0
# allow the server to communicate to the outside
$ sudo iptables -t nat -A POSTROUTING -s 10.0.0.0/24 -j MASQUERADE
# redirect port 80, 443 to the unikernel
$ sudo iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j DNAT \
--to-destination 10.0.0.2:80
$ sudo iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j DNAT \
--to-destination 10.0.0.2:443
Setting up the network interface:
$ sudo ip tuntap add mode tap tap0
$ sudo ip link set dev tap0 up
$ sudo ip addr add tap0 10.0.0.1/24
We're all set now: the unikernel is allowed to communicate to the outside, ports 80 and 443 are forwarded to the unikernel IP address, and a tap0 interface exists where the host system has the IP address 10.0.0.1 configured.
Launching DNSvizor
To launch the unikernel, you need a solo5 tender (that the Building section already installed).
$ solo5-hvt --mem=96--net:service=tap0 --net-mac:service=00:80:41:ad:30:5e -- \
dnsvizor.hvt --ipv4=10.0.0.2/24 --ipv4-gateway=10.0.0.1 --name=dnsvizor \
--ca-seed=my-random-seed --password='my password'
Solo5-hvt options
The solo5-hvt arguments follow the overall pattern $ solo5-hvt <solo5-options> -- <kernel> <dnsvizor-arguments>.
The relevant solo5-options are:
--mem 96which allocates 96 MB of memory to dnsvizor. It can be omitted with a default allocation of 512 MB.--net:service=tap0tellssolo5-hvtto use the TAP interfacetap0for the unikernel networkservice. This is required for DNSvizor as it expects exactly one network namedservice.--net-mac:service=00:80:41:ad:30:5etellssolo5-hvtto assign the MAC address00:80:41:ad:30:5eto the unikernel networkservice. This is optional; if omitted a random MAC address is generated. Note that this may cause issues with ARP tables in the network.
DNSvizor options
In the above example DNSvizor gets the arguments --ipv4, --ipv4-gateway, --name, --ca-seed and --password.
For more information about DNSvizor arguments see DNSvizor options.
DNSvizor options
The options we pass to DNSvizor can be put into three overall categories:
All options with a description can be listed by running DNSvizor with --help as argument.
The options are then printed to stdout.
Note that you still need to pass a network device to solo5-hvt.
Mirage options
These options relate to MirageOS, the library operating system used to build DNSvizor.
Important options are --help, network options and log options:
Mirage network options
Notable options are:
--ipv4=<PREFIX>--ipv4-gateway=<IP>--ipv4-only={true|false}There are as well IPv6 options. See the--helpoutput for more information.
DNSvizor options
DNSvizor strives for a degree of compatibility with Dnsmasq. Thus most options are Dnsmasq-compatible. See the section further down for information on those. The non-dnsmasq-compatible options are:
--name=<name>which would be equivalent of the hostname of a Dnsmasq setup - that is, the hostname you would find in /etc/hostname on a *NIX system.--https-port=<port>the port for the DNSvizor https web interface.--ca-seed=<base64-seed>is the seed to generate the self-signed certificate from for the DNSvizor web interface.--dns-block=<hostname>addshostnameto the DNS block list.--dns-blocklist-url=<url>addsurlto the list of DNS block list sources to fetch.--dns-cache=<size>the size of the DNS cache.
Dnsmasq-comaptible options
The following options are compatible with Dnsmasq. If you use Dnsmasq and are missing any options in DNSvizor please reach out to us.
--dnssecvalidate DNS replies and cache DNSSEC data.--dhcp-range=<start>[,<end>|<mode>[,<netmask>[,<broadcast>]]][,<lease-time>]enable the DHCP server.