Navigation

You are here: Home > Projects > Eagle DNS > Documentation for Eagle DNS 1.0

Documentation for Eagle DNS 1.0

Configuration
Logging
Secondary zones and zone transfers (AXFR)
1. AXFR security
ZoneProvider interface
FileZoneProvider
DBZoneProvider
1. Importing zones to database from zone files
2. Adding secondary zones
Remote Management Interface

Configuration

Eagle DNS uses a XML based configuration file. The configuration file that ships with Eagle DNS is ready to use and configured for loading plain zone files from the "zones" folder.

Below is a copy of the default configuration file:

<Config>
    <System>
        <Port>53</Port>
        <TCPThreadPoolSize>20</TCPThreadPoolSize>
        <TCPThreadPoolShutdownTimeout>60</TCPThreadPoolShutdownTimeout>
        <UDPThreadPoolSize>20</UDPThreadPoolSize>
        <UDPThreadPoolShutdownTimeout>60</UDPThreadPoolShutdownTimeout>
        <AXFRTimeout>30</AXFRTimeout>
        <RemoteManagementPort>5353</RemoteManagementPort>
        <RemoteManagementPassword>secret</RemoteManagementPassword>
    </System>
    <ZoneProviders>
        <ZoneProvider>
            <Name>Default file zone provider</Name>
            <Class>se.unlogic.eagledns.zoneproviders.file.FileZoneProvider</Class>
            <Properties>
                <Property name="zoneFileDirectory">zones</Property>
                <Property name="autoReloadZones">false</Property>
                <Property name="pollingInterval">10000</Property>
            </Properties>
        </ZoneProvider>

        

        
    </ZoneProviders>
</Config>

The path to the configuration file can be given as a command line parameter to Eagle DNS upon startup. If no parameter is given Eagle DNS defaults to using the following default path to configuration file "conf/config.xml".

The configuration file is divided into two main sections, <System> and <ZoneProviders>. The <System> section contains global configuration entries that are specific to Eagle DNS while the <ZoneProviders> section contains the zone providers and their specific configuration properties.

The <System> section may/must contains the following settings:

Name	Value	Required	occurrence
Address	Valid IP address	no, defaults to 0.0.0.0 (listens to all interfaces)	0..*
Port	0-65535	no, defaults to 53	0..*
TCPThreadPoolSize	1-2147483647	no, defaults to 20	0..1
TCPThreadPoolShutdownTimeout	1-2147483647 (seconds)	no, defaults to 60	0..1
TCPThreadPoolSize	1-2147483647	no, defaults to 20	0..1
UDPThreadPoolShutdownTimeout	1-2147483647 (seconds)	no, defaults to 60	0..1
AXFRTimeout	1-2147483647 (seconds)	no, defaults to 60	0..1
RemoteManagementPort	0-65535	yes	1
RemoteManagementPassword	String	yes	1

The <ZoneProviders> section must contain at least one <ZoneProvider> element, containing the following settings:

Name	Value	Required	occurrence
Name	The name of the zone provider (used for logging)	yes	1
Class	Full path to class	yes	1

Each <ZoneProvider> element may contain a <Properties> element which in turn may contain one to many <Property name="somesetting"> elements. The value of the name attribute of the <Property> element should match a valid setter method in the zone provider class. The name of the method should be specified without the "set" part and the method should take a String as input parameter. The properties of each zone provider is set after the class is instantiated but before the init(String name) method is called on the zone provider.

Logging

Eagle DNS uses the very popular and widespread log4j logging library. The logging is configured using the following file "conf/log4j.xml". For more information about how to use and configure log4j, head over to the log4j website.

By default Eagle DNS is configured to log events on level "INFO" or higher and place the log file at "logs/eagledns.log".

Secondary zones and zone transfers (AXFR)

Eagle DNS supports AXFR zone transfers which is a method of replication zones between DNS servers. Secondary zones in Eagle DNS are automatically updated from the primary DNS server. The delay between updates and the expiry of the zone data in case of failure to contact the primary DNS server is controlled by the refresh and expiration values in the zones SOA record.

AXFR security

AXFR security is a very common topic when it comes to DNS servers these days. Most likely you don't want everyone on the Internet to be able to download you whole zones so therefore AXFR needs to be secured. Eagle DNS does this by only allowing the DNS servers listed each zone to do a AXFR transfer of the zone.

ZoneProvider interface

Zones in Eagle DNS can be loaded from multiple different sources. By default Eagle DNS ships with a zone provider for loading plain zone files and a more advanced zone provider that stores zones in a database.

If you wish to develop your own zone provider it must implement the ZoneProvider interface, shown below:

package se.unlogic.eagledns;

import java.util.Collection;
import org.xbill.DNS.Zone;

public interface ZoneProvider {

    public void init(String name) throws Exception;

    public Collection<Zone> getPrimaryZones();

    public Collection<SecondaryZone> getSecondaryZones();

    public void zoneUpdated(SecondaryZone secondaryZone);

    public void zoneChecked(SecondaryZone secondaryZone);

    public void unload();
}

For information about this interface check out the source code of Eagle DNS, and have a look at the Javadoc in the class file.

FileZoneProvider

This zone provider is used to read plain zone files from the file system. Currently it only supports primary zones.

It has the following configuration properties:

Name	Value	Required	Description
zoneFileDirectory	Full or relative path	yes	Must be set so that the zone provider knows which directory to look for zones in
autoReloadZones	true/false	no (defaults to false)	Controls whether or not the zone provider should monitor the zone directory for any changes and reload the zone cache automatically
pollingInterval	1-2147483647 (milliseconds)	no (defaults to null)	Controls how often the zone provider should look for changes in the zone directory (needs to be set if the autoReloadZones property is set to true)

See the default configuration file for more information.

DBZoneProvider

This zone provider stores it's zone in a database and it supports both primary and secondary zones. It is the recommended zone provider to use with Eagle DNS since it supports all features of the ZoneProvider interface and uses transactions for all it's updates to database.

The zones are stored in a two database tables called zones and records which have the following structure:

Eagle DNS ships with a SQL script for creating the table structure. The script is called "dbtables.sql" and is located in the "docs" folder.

The following SQL script called "dbtables.sql" found in the "docs" folder is used to create the table structure above.

CREATE TABLE `zones` (
`zoneID` int(10) unsigned NOT NULL auto_increment,
`name` varchar(255) NOT NULL,
`dclass` varchar(6) NOT NULL,
`primaryDNS` varchar(255) NOT NULL,
`adminEmail` varchar(255) default NULL,
`serial` int(10) unsigned default NULL,
`refresh` int(10) unsigned default NULL,
`retry` int(10) unsigned default NULL,
`expire` int(10) unsigned default NULL,
`minimum` int(10) unsigned default NULL,
`secondary` tinyint(1) NOT NULL,
`ttl` int(10) unsigned default NULL,
`downloaded` timestamp NULL,
PRIMARY KEY (`zoneID`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1;

CREATE TABLE `records` (
`recordID` int(10) unsigned NOT NULL auto_increment,
`zoneID` int(10) unsigned NOT NULL,
`name` varchar(255) NOT NULL,
`type` varchar(6) NOT NULL,
`content` varchar(255) NOT NULL,
`ttl` int(10) unsigned default NULL,
`dclass` varchar(6) NOT NULL,
PRIMARY KEY (`recordID`),
KEY `FK_records_1` (`zoneID`),
CONSTRAINT `FK_records_1` FOREIGN KEY (`zoneID`) REFERENCES `zones` (`zoneID`) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=latin1;

The SQL script above has only been tested on MySQL 5.0 but the DBZoneProvider should work with most databases that have JDBC driver available if you create a similar table structure to the one above.

If you create a SQL script for any another database type please send it to me and I'll include it in Eagle DNS.

Importing zones to database from zone files

Importing zones from zone files manually to the database can be very time consuming, Eagle DNS therefore includes a small application that does this for you (this application only supports primary zones).

To invoke the application run the included zonefiles2db script that is included both in batch and shell script formats.

The scripts expects the following five arguments on the command line when invoked:

Path to zone directory
Qualified class name of the JDBC driver to use
Database URL
Username
Password

Below is an example of how this script is used:

./zonefiles2db.sh /var/named/zones com.mysql.jdbc.Driver jdbc:mysql://localhost:3306/eagledns user password

Adding secondary zones

To add a secondary zone, add a new row in the zones table but only set the following columns:

name
dclass
primarydns
secondary (set it to true)

Eagle DNS will then automatically download the zone from the primary DNS server and keep it updated.

Remote Management Interface

Eagle DNS has a remote management interface so that it can managed remotely over tcp/ip. The interface is based on RMI and it is currently it's very simple providing only the following features:

Login (password protected)
Reload all zones
Shutdown

Technically speaking the remote management interface consists of two Java interfaces, one for login and one for the actual administration. The interfaces are displayed below:

package se.unlogic.eagledns;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface EagleLogin extends Remote{

public EagleManager login(String password) throws RemoteException;
}

package se.unlogic.eagledns;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface EagleManager extends Remote{

public void shutdown() throws RemoteException;

public void reloadZones() throws RemoteException;

}