Installation guide

Installing DNS2db 2.2.1

Table of contents

1. Introduction
2. Build and Install the DNS2db binaries
3. Configure and run DNS2db
4. Run DNS2db from start/stop script
5. Run DNS2db from commandline
6. Install and configuring the Flex GUI
7. Requirements for the GUI
8. Install the php-xml backend on a collector node
9. Install the Flex GUI frontend

1. Introduction.

This document describes how to install and configure the complete set of tools provided by .SE to collect DNS traffic and present statistics on traffic to and from a DNS server. The instructions are split into three parts where we begin with building and installing the DNS2db binaries. The second part is for configuring DNS2db. And finally we will set up the scripts and applications for the presenter.

2. Build and install the DNS2db binaries

Currently DNS2db is known to work on Linux (Tested on Debian and RedHat), OpenBSD and possibly OSX (no promises on OSX). This document covers installation on Linux and OpenBSD.

Requirements

Sqlite3 >=3.4.0 libtrace >=3.0.4 ldns >=1.3.0 Sqlite3 can be found at http://www.sqlite.org/ libtrace can be found at http://research.wand.net.nz/software/libtrace.php ldns can be found at http://www.nlnetlabs.nl/ldns/

Build on Linux

In the dns2db directory run ./configure && make && make install

cd dns2db
./configure && make && make install

Build on OpenBSD

On OpenBSD >4.4 configure should figure out everything by itself but you may have to add environment variables for autoconf and automake. On OpenBSD 4.3, you may need to run aclocal before ./configure

cd dns2db
export AUTOCONF_VERSION=2.61
export AUTOMAKE_VERSION=1.9
./configure
make
sudo make install

Various tricks

On some systems you may need to run automake or autoconf to make a configure script that works for your platform before running ./configure .

In some cases configure won't find the correct version of ldns even though it has been compiled and installed this is usually due to the fact that /usr/local/lib is not in your library path. In this case either install ldns and libtrace to somewhere in your path or add /usr/local/lib to /etc/ld.so.conf and run ldconfig.

3. Configure DNS2db

When running the dns2db or dns2db.pl script, tracedns and dns2sqlite is started with parameters from /etc/dns2db.conf. The configuration file /etc/dns2db.conf should be the only file necessary to edit. dns2db.conf is well documented in itself and should need no explaining here.

4. Run DNS2db from start/stop script

On systems with the /etc/init.d/ catalog: The process is started by the /etc/init.d/dns2db script. Setup your system to run this script on boot. (depends on distribution, check your system docs)

On systems with /etc/rc: The process is started with /usr/local/bin/dns2db.pl

Edit /etc/rc.local and add the lines

if [ -f /etc/dns2db.conf ]; then
   /usr/local/bin/dns2db.pl start
fi

5. Run DNS2db from commandline

Invoking the tracedns and dns2sqlite with the parameter -h gives a quick help on configurable commandline parameters.

tracedns -h                                                                  
usage: tracedns [ --filter | -f bpfexp ]  [ --snaplen | -s snap ]
                [ --promisc | -p flag] [ --help | -h ] [ --libtrace-help | -H ] libtraceuri...
 
dns2sqlite -h                                                                
usage: dns2sqlite [options]
--help | -h             shows this help
--version | -v          show dns2sqlite version
--show_schema | -s      shows the queries that generate the sql tables
--queries_only | -q     only log dns queries
--replies_only | -r     only log dns replies
--database | -d dbf     database filename
--append | -a           append to existing databasefiles
--db_overwrite | -o     overwrite existing databasefiles
--interval | -i min     split interval
--db_folder | -f dir    database folder

Since tracedns is using libtrace it can read several different types of packetcapturing formats. Run tracedns -H for details.

Example reading from network interface where max packet size is 65535, port is 53, the interface is em1 and creating databases in /tmp/db where database names will be DNS2db-'datetime' and split in 5 minute intervals.

tracedns -s 65535 -f "port 53" pcapint:em1 | dns2sqlite -t /tmp/dns2db_template -d DNS2db- -f /tmp/ -i 5

Example as above but now reading from pcap file on disk

tracedns -s 65535 -f "port 53" pcapfile:/tmp/file.pcap | dns2sqlite -t /tmp/dns2db_template -d DNS2db- -f /tmp/db -i 5

6. Install and configure the Flex GUI

The GUI is provided as a precompiled binary and also in source format. The binary is platform-independent and will run on any Flash player with version 9 or later. Since DNS2db is capable of using several collector servers and aggregate the results in the GUI. The GUI code is split in two parts, one simple script on each collector node for accessing the databases and one set of scripts for querying the collector nodes and presenting the Flash GUI. The naming of the files are fairly simple. All files beginning with dns2dbnode* should be installed on each collector server and the rest of the files is for the GUI server.

The PHP files are available in the folder dns2db/www

7. Requirements for the GUI

Collector Server

SQLite3 >=3.4.x Apache webserver (any recent version) PHP (version that supports PDO_sqlite) PDO_sqlite >=1.0.1 (for PHP to use sqlite3 databases) GUI Server

SQLite3 >=3.4.x Apache webserver (any recent version) PHP (version that supports PDO_sqlite) PDO_sqlite >=1.0.1 (for PHP to use sqlite3 databases) PHP cURL

8. Install the php-xml backend on a collector node

Copy the files dns2dbnode.php and dns2dbnode_conf.php.example to a directory served by the webserver on the collector node.

If /etc/dns2db.conf can't be reached from the webserver you need to copy dns2dbnode_conf.php.example to dns2dbnode_conf.php and edit the file.

If you use this file you must change the path and the beginning of filename to match parameters configured in /etc/dns2db.conf. Example dns2dbnode_conf.php:

// Change the DNS2db path to your db-files and the filename prefix (SERVER in example below).

$database = "/tmp/DNS2db/".$day."/SERVER-".$day."".$time.".db";

If all is well you should now be able to reach the xml backend on the collector node. dns2dbnode.php does not produce xml when called without parameters. If you would like to test the script without the GUI use this URL: (Replace the date & time)

http://servername/dns2dbnode.php?function=topresolvers&day=20090324&time=1500&count=2 You should recieve XML output if all went well. This must work before we install the GUI. Since you most likely do not have data for 20090324 you should receive

<error>
    no database
</error>

which is normal.

9. Install the Flex GUI frontend

All the needed GUI files are distributed with DNS2db in the www directory.

Below commands will set up the GUI directly under the webserver document root. You may want to install in a separate directory eg, dns2db. Adjust accordingly.

cd dns2db/www
cp dns2db.php $DOCUMENTROOT/
cp dns2db_conf.php.example $DOCUMENTROOT/dns2db_conf.php
cp dns2db.swf $DOCUMENTROOT/
cp index.php $DOCUMENTROOT/
cp reversedb.db3 $DOCUMENTROOT/
chmod 755 $DOCUMENTROOT/reversedb.db3
chown httpd:httpd $DOCUMENTROOT/reversedb.db3

(where httpd is the user the webserver runs as) In dns2db_conf.php, edit the nodelist to include the URL of the collector nodes. (If you are not running http will need to change this as well) If everything is well, you should be able ro reach the GUI from:

http://SERVER/index.php

DONE!!!