Using MaraDNS as an authoritative DNS server

Table of contents


In order to set up an authoritative DNS server, one needs one or more static IP addresses. With most registries, two or more static IP addresses are needed.

In addition, the machine(s) with the static IP addresses need to be running an authoritative DNS server, such as MaraDNS.

What is a domain zone?

A name like is part of the domain zone The name, as another example, is part of the domain zone is part of the domain zone

Setting up a domain with MaraDNS

Compile and install MaraDNS on the system which will act as an authoritative DNS server.

After doing this, the mararc file needs to be changed before MaraDNS will function as an authoritative DNS server.

A mararc file which can be used to serve the domain zones that one wishes to have control over needs to only be four lines long:

ipv4_bind_addresses = ""
chroot_dir = "/etc/maradns"
csv2 = {}
csv2[""] = ""
Lets look at these four lines. The first line, ipv4_bind_addresses, is the IP address (or addresses) this DNS server will have. Since we're running an authoritative DNS server, it is important that this IP address be a routable IP address--an IP address that can be accessed by anyone on the internet. It is also important that any firewall between this machine and the internet at large is able to connect to UDP port 53 of this machine.

The chroot_dir value is the directory that contains all of the files with information for the domain zones (these files are normally called "zone files" by DNS administrators). Here, we place the zone files in the directory /etc/maradns.

The third line, csv2 = {}, tells MaraDNS that we will be acting as an authoritative DNS server. This line must be placed before telling MaraDNS where any zone files are located.

The fourth line, csv2[""] = "" tells MaraDNS that, for the domain zone "", the zone file is called "".

In other words, is the name of the domain zone that the file has data for. Change to the name of the domain zone you wish to serve, and to the filename to be used to serve that domain zone. Important: the domain zone name (e.g. requires a trailing dot.

It is possible to server multiple domain zones, of course. For example:

csv2[""] = ""
csv2[""] = ""
csv2[""] = ""
It is also possible to bind MaraDNS to multiple IP addresses, e.g:
ipv4_bind_addresses = ","

Setting up a domain zone file

Let us suppose that we are setting up a domain for, where we have the following services: The zone file for this setup would be as follows. Note that lines which start with the # symbol are comments (lines ignored by MaraDNS), allowing one to add human-readable notes in the file in question.
# This is an example zone file for the imaginary domain

# We have two records which handle the serving of web pages.  These
# are simple name-to-ip translations.  In other words, we have one
# record which states "The IP for is" and
# another that states "The IP for is" ~ ~

# We also need to set up an IP for the machine that serves email for
#  Because of how DNS is designed, we both need
# a record which states "The machine which handles mail for
# is called" and a record which states
# "The IP address for is": MX 10 ~ ~
Now, to adapt this file to another zone, we need to simply make the following changes: Note that the chroot_dir mararc variable tells MaraDNS which directory contains domain zone files.

The format of a Domain Zone file

Here are some example lines in a domain zone file, which is an example of someone using the same IP multiple times. For example, if one is using as one of the DNS servers, the mail server, and the web server, one would have records like this:      NS ~ ~   ~ ~      MX 10 ~ ~
Translated into English, the above lines say:

A line in a domain zone file contains a single DNS record. The data has multiple fields separated by a whitespace or the | character, and is in this format:

The reason to use different names for different functions is to minimize the number of problems one will encounter, should one need to change their IPs at a later time.

A single name can have multiple records

A single name can have multiple records. This is useful when one wishes to have, for example, multiple machines processing requests for

For example: ~ ~ ~
In this example, a query to will return a list of three IPs. MaraDNS rotates the records so that the first IP given to a client changes each time a query for is made. This can be used as a primitive kind of load balancing.

The % character shortcut

If one is setting up multiple domain zones, all of which have more or less the same data, it is convenient to have a template domain file which different zones can use without needing to modify the file in question.

MaraDNS has support for this by using the % symbol. Whenever MaraDNS sees a % in a csv2 zone file, MaraDNS knows to replace the percent symbol with the name of the zone in question. For example, if the file in question is the zone file for, the % is expanded out to "". If the zone file in question is for, the % is expanded out to "". Hence, we could, provided that the zone file is for, have a zone file like this:

# We have two records which handle the serving of web pages.  These
# are simple name-to-ip translations.
% ~
www.% ~

# We also need to set up an IP for the machine that serves email for
# our zone.  Because of how DNS is designed, we both need
# a record which states "The machine which handles mail for
# out zone is called mail1.<zone name>" and a record which states
# "The IP address for mail1.<zone name> is":
% MX  10 ~
mail1.% ~
This zone file would function identically to the first example zone file above.

Getting connected to the root name servers

An authoritative DNS server will not effectively serve a domain unless the root name servers are aware that a given DNS server serves a given domain name.

When a recursive DNS server attempts to find the IP for, say,, it firsts asks the root nameservers for this IP. The root name servers send out a reply which says "We do not know that answer to this question, but you may contact the DNS server at for the answer". At this point, the recursive DNS server contacts, asking it for the IP for (Actually, the root nameservers give out the .com nameservers, which in turn give out the nameservers, but the principle is the same)

In order that the entire internet community may be aware of a domain, the domain must be registered with the root name servers, so that the root name servers know that IPs of the machines which are authoritative DNS servers for the domain in question. (Again, you're really registering with, say, the .com servers)

The exact policies which one needs to confirm to to register their domain depend on the register in question. To register a domain under the generic domain names (presently .com, .net, .org, and .info) one simply needs to register their name with a register, and follow some guidelines when designing the zone files for their domain.

There are a number of competing registrars which server domain names. One which I have extremely happy with is Net Wizards; domains can be registered at In order to register a domain, you will need to know the zone servers for your domain. You can either set these up yourself (see below for an example), or use the askmara tutorial to find out the name servers for your domain.

To use the askmara tool, make an askmara query like this:

Replace with the name of the domain to be registered, and with the IP of the DNS server. The output of the query will look something like this:
# Querying the server with the IP
# Question: +86400 ns ~ +86400 ns ~
# NS replies:
# AR replies: +86400 a ~ +86400 a ~
The names for the name servers we wish to submit to the registrar are the and names above. These somewhat long names are the names for the nameservers for the (in the above example) domain. At the end of the askmara output, you can see the IPs for these name servers; place these IPs in the field where they ask for the IP of the name servers for your domain.

For example, if the registrar's form looks like this:

Domain name: _________________

Nameserver 1 name: ____________________________________
Nameserver 1 IP:   ____________________________________
Nameserver 2 name: ____________________________________
Nameserver 2 IP:   ____________________________________
Nameserver 3 name: ____________________________________
Nameserver 3 IP:   ____________________________________
Nameserver 4 name: ____________________________________
Nameserver 4 IP:   ____________________________________
Based on the above askmara output, we would fill out the above form thusly:
Domain name:      

Nameserver 1 name:      
Nameserver 1 IP:
Nameserver 2 name:
Nameserver 2 IP:
Nameserver 3 name: ____________________________________
Nameserver 3 IP:   ____________________________________
Nameserver 4 name: ____________________________________
Nameserver 4 IP:   ____________________________________

If you only have one NS server, you may need to get a second one to register a domain. The procedure for doing this is described in the following section.

Getting two IPs

As stated near the beginning of this document, many registries require that one has two IPs to register a domain. If one has a computer with two or more routable IPs assigned to it, it is simple enough to have MaraDNS bind to these IPs. Change the variable ipv4_bind_addresses to include all of the IPs one wishes MaraDNS to have, like the following example:
ipv4_bind_addresses = ","
Naturally, replace "" and "" with the IPs your machine has.

If you have but a single IP, it is necessary to find someone who will provide secondary DNS service for your domain, and set up MaraDNS to be a zoneserver. Information on how to do this is provided in the DNS master document.

Names internal to a network

Sometimes one will have a number of computers in an office, or other small network, with a number of different names. It is desirable to use DNS to give these office machines IP addresses. Let us suppose that we have a company with computers named "Mascota", "Paloma", and "Vela". If we want to have computers in the office be accessible with just the name (such as just "Vela"), we set up what is known as a default domain suffix. Let us suppose that the company in question is a company that sells examples of hard work. Hence, the company is called "". We then give our computers the names "", "", and "". We then tell computers in the office that, when given a name without a suffix, to append the "" suffix when looking for host names.

It is possible to do this in MaraDNS 1.3 in two different ways.

One way is to set up MaraDNS' recursive resolver to use a custom nameserver for a subset of the DNS space. For example, the recursor can be told to go to "" to look up all names that end in ".office". More information about this is in the recursive DNS document.

The other method takes advantage of the fact that MaraDNS first looks up authoritative names before performing recursion. For example, if is defined in a MaraDNS zone file, MaraDNS will use the value in the zone file instead of contacting nameservers on the internet to get the IP for

On UNIX, BSD, and Linux machines in an office, this is done by adding a line like this to the file /etc/resolv.conf:


In Windows XP, go to Control Panel -> Network Connections -> Local Area Connection (or whatever connection the computer uses to get on the LAN) -> Properties -> Internet Protocol (TCP/IP) (this is under "The connection uses the following items" and you may have to scroll down to see it) -> Advanced -> DNS -> "Append these DNS suffixes (in order)" -> Add and type in "" (or whatever) as the Domain suffix.

Once this is done, create a zone for Since we're just giving three computers IPs, the zone file for is added to the mararc file with this line:

csv2[""] = ""
We then place, in the directory pointed to by chroot_dir in the mararc file, the file, which looks like this:
mascota.% ~
paloma.% ~
vela.% ~
See above for an explanation of what the % symbol does.

The above three lines, which is a complete csv2 zone file, is a shorthand for the following:

# The SOA record.  If a zone doesn't have a SOA record, MaraDNS will
# synthesize an appropriate one for a given zone.  This is information
# about who is in charge of the zone; basically the zone
# name "", SOA "It's a Start of Authority record",
# "" (this is the name of the machine in charge of
#, "" (the email address of the
# person in charge of    SOA ~
# The following numbers, part of the SOA record, give some technical
# information about transferring information about this zone to other
# DNS servers.  If you use rsync to share zone files, these numbers
# do not need to be worried about.
                        1 7200 3600 604800 1800 ~

# NS records.  If a zone doesn't have NS record, MaraDNS will, again
# synthesize appropriate NS records for a given zone.  This is a list
# of all of the DNS servers that have the zone file. NS ~ NS ~

# The NS records above need IPs.  Note that "A" (this is an IP) is
# optional  A ~  A ~

# Now that we have the SOA and NS records taken care of (again, MaraDNS
# will automatically take care of these records if they are not in a
# zone), we can add the records for the zone in question

# has the IP address    A ~
# has the IP address     A ~
# has the IP address       A ~
Information on setting up a recursive server so that these names are private network-specific hostnames is available in the private hostname section of the recursive server document.