This document has been placed in the public domain by Sam Trenholme

Using MaraDNS as an authoritative DNS server

Requirments

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 www.example.com is part of the domain zone example.com. The name www.yahoo.com, as another example, is part of the domain zone yahoo.com. www.maradns.org is part of the domain zone maradns.org.

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.

How to a make a mararc file which can be used to serve the domain zones that one wishes to have control over:

Copy over the example authoritative mararc over to /etc/mararc
There is a section near the top of the mararc file which looks like this:
csv2["example.com."] = "db.example.com"
Here, example.com. is the name of the domain zone that the file db.example.com has data for. Change example.com. to the name of the domain zone you wish to serve, and db.example.com to the filename to be used to serve that domain zone. Important: the domain zone name requires a trailing dot.
It is possible to server multiple domain zones, of course. For example:
```
csv2["example.com."] = "db.example.com"
csv2["example.org."] = "db.example.org"
csv2["heaven.af.mil."] = "db.heaven.af.mil."
```

The domain zone files which are pointed to in /etc/mararc are, by default, in the directory /etc/maradns (the directory is determined by the value of chroot_dir in the mararc file).

Setting up a domain zone file

Let us suppose that we are setting up a domain for example.com, where we have the following services:

We are running a web server for example.com and www.example.com on the IP 10.10.10.12. In other words, people can view web pages on this machine.
We have a mail server, or mail transport agent for example.com with the IP 10.10.10.15. In other words, the machine with the IP 10.10.10.15 is set up to handle mail addressed to name@example.com, where "name" is any string proceeding the '@' sign.
Both 10.10.10.11 and 10.10.10.17 are running MaraDNS in authoritative mode to serve DNS requests for example.com.

The zone file for this setup would be as follows. Note that lines which start with the # symbol are comments, in other words 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 example.com.

# 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 exmaple.com. is 10.10.10.12" and
# another that states "The IP for www.example.com. is 10.10.10.12"
example.com. 10.10.10.12
www.example.com. 10.10.10.12

# We also need to set up an IP for the machine that serves email for
# example.com.  Becuase of how DNS is designed, we both need
# a record which states "The machine which handles mail for 
# exmaple.com is called mail1.example.com" and a record which states
# "The IP address for mail1.example.com is 10.10.10.15":
example.com. MX 10 mail1.example.com.
mail1.example.com. 10.10.10.15

Now, to adapt this file to another zone, we need to simply make the following changes:

Sustitute the name example.com with the name of the domain one wishes to administer.
Substitute the IP 10.10.10.12 with the IP of the machine running the web server for the domain.
Substitute the IP 10.10.10.15 with the IP of the machine running the mail server for the domain.

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 10.10.10.19 as one of the DNS servers, the mail server, and the web server, one would have records like this:

example.com.      NS    ns1.example.com.
ns1.example.com.        10.10.10.19
example.com.            10.10.10.19
www.example.com.        10.10.10.19
example.com.      MX 10 mail1.example.com.
mail1.example.com.      10.10.10.19

Translated in english, the above lines say:

One name server for example.com, which other DNS servers should remember for one day (86400 seconds), is called ns1.example.com.
The IP for ns1.example.com, which other DNS server should remember for one day, is 10.10.10.19
The IP for example.com (in other words, the machine a web browser should hit if one selects http://example.com/), which other DNS servers should remember for one day, is 10.10.10.19
The IP for www.example.com, which other DNS servers should remember for one day, is 10.10.10.19
The name of the machine which processes incoming mail, which other name servers should remember for one day, which has a priority of ten (lower priority numbers are more important), is called mail1.example.com.
The IP for mail1.example.com, which other name servers should remeber for one day, is 10.10.10.19

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 first portion of the DNS record, up until a | (pipe) character or whitespace, is the DNS node that this record is attached to.
The next portion of a DNS record tells MaraDNS what kind of DNS record this is. A list of DNS records which MaraDNS supports is described here.
The next field of the DNS record is how long, in seconds, other DNS servers should cache (remember) this DNS record. Again, this field is terminated by either whitespace or a |.
The subsequent fields describe the DNS record in question. The format for this data depends on the record type being used, and is described here.

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.

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 csv1 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 example.com, the % is exanded out to "example.com.". If the zone file in question is for maradns.org, the % is expanded out to "maradns.org.". Hence, we could, provided that the zone file is for example.com, have a zone file like this:

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

# We also need to set up an IP for the machine that serves email for
# our zone.  Becuase of how DNS is designed, we both need
# a record which states "The machine which handles mail for 
# out zone is called mail1." and a record which states
# "The IP address for mail1. is 10.10.10.15":
% MX  10 mail1.example.com.
mail1.%  10.10.10.15

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, www.example.com, 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 can contact the DNS server at 10.1.2.3 for the answer". At this point, the recursive DNS server contacts 10.1.2.3, asking it for the IP for www.example.com.

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.

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 reigstered at http://domains.netwiz.net/. In order to register a domain, make sure that:

The zone file in question has NS records for the zone in question, and that those NS records point to the IPs which are authoritative DNS servers for the zone in question (the example zone files above do this).
That the "name server" name field is filled out with a name for the name server in question; that the name server has an IP which agrees with the IP one puts in the "name server IP" field.
Due to limitaitons in the database which the root name servers use, a single IP, unfortunatly, can not have more than one name.