Installing DNSharness

Version 1.3

This document describes how to install the DNSharness system.

Prerequisites

DNSharness runs on an Intel-based PC running Ubuntu Desktop 12.04 LTS or Xubuntu 12.04 LTS ("Precise Pangolin"). It also runs on Ubuntu Desktop 14.04 LTS and Xubuntu Desktop 14.04 LTS ("Trusty Tahr"). It probably runs equivalently well on other recent Linux distributions but has not been tested on them. The PC must have at least 4 Gigabytes of RAM and a hard drive with at least 100 Gigabytes free. Note that DNSharness needs to run on real hardware, not in a virtual machine, because it lauches VirtualBox itself.

The rest of this document is the set of steps needed to configure the Linux host to load the DNSharness system.

Prepare the host

The host needs to have the network addresses needed for DNSharness. The host server must have at least one NIC, eth0. That NIC must be part of a network that has a gateway to the Internet, and the host needs at least one publicly-routable address (possibly behind a NAT). For the initial setup, there must be a DHCP server available on eth0 (although DHCP is not needed later; all addresses can be assigned.)

Some of the steps below may require that your shell be bash, and that your .bashrc file contain PATH=${PATH}.

Networking

Ubuntu's NetworkManager aggressively, and often wrongly, tries to be helpful with network maintenance. Thus, it needs to be removed and manual network setup is needed. This needs to be done at the console, since it will disconnect the current networking. Uninstall NetworkManager with:

sudo apt-get purge network-manager network-manager-gnome

To assign addresses manually, edit /etc/network/interfaces to contain something like:

auto eth0
iface eth0 inet static
address SOMEADDRESSHERE
netmask 255.255.255.0
gateway SOMEADDRESSHERE
dns-nameservers SOMEADDRESSHERE ANDADIFFERENTADDRESSHERE

To assign addresses with DHCP, instead use something like:

auto eth0
iface eth0 inet dhcp

If Ubuntu and Xubuntu gets confused about which interface to use for eth0, remove the offending file:

sudo rm /etc/udev/rules.d/70-persistent-net.rules

Reboot the system and check the new interace settings using ifconfig.

Needed packages

Installing DNSharness requires a few packages on the host:

sudo apt-get install openssh-server python-pip python-dev curl virtualbox

Add the fabric package to the host to facilitate SSH to VMs:

sudo pip install pip --upgrade
sudo pip install fabric

Configure VirtualBox

Run VirtualBox from the command line (virtualbox) or from the Ubuntu GUI. Add a host-only adapter and set its address:

VBoxManage hostonlyif create

Give this new interface IPv4 and IPv6 addresses of 10.9.1.1 and 2001:0db8:cccc:dddd::1 and make the interface available to Ubuntu:

/usr/bin/VBoxManage hostonlyif ipconfig vboxnet0 --ip 10.9.1.1 --netmask 255.255.255.0
/usr/bin/VBoxManage hostonlyif ipconfig vboxnet0 --ipv6 2001:0db8:cccc:dddd::1 --netmasklengthv6 64

You need to also give these commands each time the host is started, so you should probably add them to your .bashrc or local startup program.

You can make sure vboxnet0 is there and correct:

VBoxManage list hostonlyifs

and also check the output of ifconfig.

Install DNSharness

Get the latest version of the DNSharness software:

cd ~; wget http://www.dnsharness.org/DNSharness.tgz
tar -xzf DNSharness.tgz

Get the needed sources

Get the Debian "squeeze":

cd ~/DNSharness/userdist
wget http://dnsharness.org/third-party/debian-7.0.0-i386-netinst.iso

The rest of the commands are given from inside the new directory.

cd ~/DNSharness

Get the DNS source packages:

./DNSharnessRun.py getsources

Note that this step will take a long time; this step will pull down about 2.5 gigabytes of sources.

Link the sources to the distribution directory:

./DNSharnessRun.py createsrclinks

Create the first VM

The base VM for DNSharness is called "debianbase". This VM is just a bare version of Debian with a few additional packages. First create the VM:

./DNSharnessRun.py makebase

Next, start the VirtualBox GUI. You will see debianbase in the list of active VMs. Start the VM by clicking the "Start" button in the GUI.

Install Debian in the VM

In the first screen, choose "Install". Go through the rest of the installation screens as you would for a normal install, making the following choices:

Note that the root password, the user name of "dns", and the user password of "dnsp" are all required. The user password will be changed when you start using DNSharness.

Initialize debianbase

When the Debian installation is finished, it will automatically reboot. On some recent versions of VirtualBox, when Debian reboots, it thinks that the installation image is still in the drive even though it has been properly ejected by the installer; in this case, simply shut down the machine and start it again.

Log in as "root" with the root password of "rootp". In the VM, temporarily set the networking for eth0 on the VM:

ifconfig eth0 inet 10.9.1.2 netmask 255.255.255.0

Get the needed files from the host using SFTP in the VM:

sftp yourusername@10.9.1.1:DNSharness/rootdist/

Of course, substitute your login on the host for "yourusername" there. At the "sftp>" prompt, give the "get *" command to get all the files into the root user's home directory on the VM. Give the "exit" command to leave the sftp program.

Finally, install some basic packages and fix up a few things:

./root-init.sh | tee initlog.txt

This will shut down the VM when it is finished.

Create the opensource VM for the DNS packages

Create opensource from debianbase drive and create VM:

./DNSharnessRun.py makeclone opensource

The opensource VM will be created and started. Check the VirtualBox VM to make sure the VM has started, and wait about 15 seconds after you see the login prompt.

On the host, change the internal IP addresses on the new clone so that DNSharness knows that it is the opensource VM:

./DNSharnessRun.py setinterfaces opensource

This will cause the VM to reboot. (This command sometimes fails with a timeout; giving the command again should clear up that problem.)

When it is finished rebooting, change the password on opensource:

./DNSharnessRun.py changepass opensource

Build the things needed to make DNS servers on opensource (some of these packages build slowly):

./DNSharnessRun.py preparebuild

Copy the DNS package sources to opensource:

./DNSharnessRun.py copysources

Build the sources on opensource:

./DNSharnessRun.py build all

This last step will probably take at least three hours even on a fast host.

Note that building BIND 8 packages sometimes fails for unknown reasons; if that happens, running the build all command again will attempt to build only the packages that were not built earlier. It may take repeated attempts to build all the BIND 8 packages successfully.

Run Projects

The above steps complete the installation of DNSharness. See the Projects.html file for a description of how to run projects in DNSharness.

Creating clones of the opensource VM

Some projects will need to have more than one copy of the opensource VM running, particularly to test what happens when one type of DNS software is connecting to another DNS package. In such cases, the two software packages should be running on different VMs so that there is no contention on port 53. These clones normally only run one software package, not the sequence of software packages that is typical for the "opensource" VM.

DNSharness makes this easy by allowing up to ten clones of the opensource VM. These clones are called "clone10", "clone11", and so on, up to "clone19". The number in the name indicates the IP address of the clone; clone10 has an IPv4 address of 10.9.1.10 and an IPv6 address of 2001:0db8:cccc:dddd::10.

To create clone10 (for example), be sure that the "opensource" VM is not running, then use the command:

./DNSharnessRun.py makeclone clone10

The clone10 VM will be created and started. Note that it takes quite a while to make the clones because the opensource is over 50 Gb in size.

Check the VirtualBox VM to make sure the VM has started, and wait about 15 seconds after you see the login prompt. On the host, change the internal IP addresses on the new clone so that DNSharness knows that it is the clone VM:

./DNSharnessRun.py setinterfaces clone10

This will cause the VM to reboot. When it is finished rebooting, change the password on the clone:

./DNSharnessRun.py changepass clone10

Creating clones to act as NATs

Some projects test how DNS queries and responses change when the query comes from behind a NAT. DNSHarness makes creating these types of projects easy by allowing the creation of multiple NAT systems.

You can easily create up to ten VMs that act as NATs of the opensource VM. These clones are called "nat20", "nat21", and so on, up to "nat29". The number in the name indicates the IP address of the clone; nat20 has an IPv4 address of 10.9.1.20 and an IPv6 address of 2001:0db8:cccc:dddd::20.

Add a new host-only adapter, "vboxnet1", that will be used for the NAT's inside (private) network:

VBoxManage hostonlyif create

Give this new interface an IPv4 address of 10.10.10.1 and make the interface available to Ubuntu:

/usr/bin/VBoxManage hostonlyif ipconfig vboxnet1 --ip 10.10.10.1 --netmask 255.255.255.0

You need to also give this command each time the host is started, so you should probably add it to your .bashrc or local startup program, as you did earlier for the "vboxnet0" adapter.

To create nat20 (for example), use:

./DNSharnessRun.py makeclone nat20

The nat20 VM will be created and started.

Check the VirtualBox VM to make sure the VM has started, and wait about 15 seconds after you see the login prompt. On the host, change the internal IP addresses on the new clone so that DNSharness knows that it is the NAT VM:

./DNSharnessRun.py setinterfaces nat20

This will cause the VM to shut down, have its eth0 adapter changed to vboxnet1, and then restarted.

When it is finished booting, change the password on the NAT:

./DNSharnessRun.py changepass nat20

Log into the new VM as root, and give the command:

./NATStarter.py

This will set up the VM to be a DHCP server and NAT. It will also cause these settings to be used after future reboots.

Creating a clone to be behind the NAT

You also need to create the "behindnat" VM so that requests can be sent from a VM behind then NAT. Note that the "behindnat" VM has two IP addresses: 10.10.10.5 is used for communicating with the Linux host, and an address assigned by the NAT with DHCP.

Create behindnat from debianbase drive and create VM:

./DNSharnessRun.py makeclone behindnat

The behindnat VM will be created and started. Check the VirtualBox VM to make sure the VM has started, and wait about 15 seconds after you see the login prompt. On the host, change the internal IP addresses on the new clone so that DNSharness knows that it is the behindnat VM:

./DNSharnessRun.py setinterfaces behindnat

This will cause the VM to shut down, have its eth0 adapter changed to vboxnet1, and then restarted.

When it is finished booting, change the password on the new VM:

./DNSharnessRun.py changepass behindnat

Initially, the behindnat box expects the NAT to be one of the NATs described above. Some projects might want to test hosts behind hardware NATs such as home routers. The behindnat VM can be used for that as well. To change the network configuration of the behindnat VM, log in to that VM as root, and give the command:

./BehindNATChanger.py external-nat

This changes the /etc/network/interfaces file and brings all interfaces down and up again. To change back to the configuration for the behindnat VM being behind one of the cloned NATs above, give the command:

./BehindNATChanger.py dnsharness-nat

Installing getdns on the host

The getdns API is a good tool for creating queries on the host that can be sent to the opensource VMs. The API currently works for C, Python, and Node programs. Examples in DNSharness are given for C and Python.

Add the prerequisites:

sudo apt-get install libevent-dev libidn11-dev libldns-dev libunbound-dev unbound-anchor

Get the sources. Note that these two are those that are current at the time of release of this version of DNSharness; there are possibly newer versions available. These instructions work correctly for 0.1.2. Check the getdns implementation web site for future building instuctions.

Download and install getdns:

wget -O getdns-main.tgz https://github.com/getdnsapi/getdns/archive/v0.1.1.tar.gz
cd ~
tar -xzf getdns-main.tgz && cd ~/getdns-0.1.1/
./configure --with-libevent && make && sudo make install
sudo mkdir /etc/unbound
sudo unbound-anchor -a "/etc/unbound/getdns-root.key"

If you want to use getdns through its Python 2.7 interface, get the source and install it:

cd ~
wget -O getdns-python-bindings.tgz https://github.com/getdnsapi/getdns-python-bindings/archive/v0.1.0c-alpha.tar.gz
tar -xzf getdns-python-bindings.tgz && cd ~/getdns-python-bindings-0.1.0c-alpha/
python setup.py build  && sudo python setup.py install