Using MaraDNS as an authoritative DNS server

Table of contents

Requirements

 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.

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 = "10.3.28.79"
chroot_dir = "/etc/maradns"
csv2 = {}
csv2["example.com."] = "db.example.com"
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["example.com."] = "db.example.com" tells MaraDNS that, for the domain zone "example.com.", the zone file is called "db.example.com".

In other words, 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 (e.g. example.com.) 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"
It is also possible to bind MaraDNS to multiple IP addresses, e.g: 
ipv4_bind_addresses = "10.3.28.79, 10.9.87.23"

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: 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 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 example.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.  Because of how DNS is designed, we both need
# a record which states "The machine which handles mail for
# example.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: 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 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 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 www.example.com.

For example: 

www.example.com.	10.10.10.10 ~
www.example.com.	10.10.10.11 ~
www.example.com.	10.10.10.12 ~
In this example, a query to www.example.com 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 www.example.com 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 example.com, the % is expanded 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.  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 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 may 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. (Actually, the root nameservers give out the .com nameservers, which in turn give out the example.com 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 http://domains.netwiz.net/. 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:

askmara Nexample.com. 127.0.0.1
Replace example.com with the name of the domain to be registered, and 127.0.0.1 with the IP of the DNS server. The output of the query will look something like this: 
# Querying the server with the IP 127.0.0.1
# Question: Nexample.com.
example.com. +86400 ns synth-ip-0a010203.example.com. ~
example.com. +86400 ns synth-ip-0a040506.example.com. ~
# NS replies:
# AR replies:
#synth-ip-0a010203.example.com. +86400 a 10.1.2.3 ~
#synth-ip-0a040506.example.com. +86400 a 10.4.5.6 ~
The names for the name servers we wish to submit to the registrar are the synth-ip-0a010203.example.com and synth-ip-0a040506.example.com names above. These somewhat long names are the names for the nameservers for the (in the above example) example.com. 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: example.com      

Nameserver 1 name: synth-ip-0a010203.example.com.      
Nameserver 1 IP:   10.1.2.3
Nameserver 2 name: synth-ip-0a040506.example.com.
Nameserver 2 IP:   10.4.5.6
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 = "10.1.2.3, 10.5.6.7"
Naturally, replace "10.1.2.3" and "10.5.6.7" 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 "example.com". We then give our computers the names "mascota.example.com", "paloma.example.com", and "vela.example.com". We then tell computers in the office that, when given a name without a suffix, to append the "example.com" 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 "192.168.0.7" 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 www.google.com 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 www.google.com.

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

search example.com

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 "example.com" (or whatever) as the Domain suffix.

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

csv2["example.com."] = "db.example.com"
We then place, in the directory pointed to by chroot_dir in the mararc file, the file db.example.com, which looks like this: 
mascota.%       10.1.2.3 ~
paloma.%        10.5.6.7 ~
vela.%          10.9.8.4 ~
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 example.com zone; basically the zone
# name "example.com.", SOA "It's a Start of Authority record",
# "example.com." (this is the name of the machine in charge of
# example.com), "hostmaster@example.com." (the email address of the
# person in charge of example.com.)
example.com.    SOA     example.com. hostmaster@example.com. ~
# 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 example.com zone file.
example.com. NS ns1.example.com. ~
example.com. NS ns2.example.com. ~

# The NS records above need IPs.  Note that "A" (this is an IP) is
# optional
ns1.example.com.  A 10.1.2.3 ~
ns2.example.com.  A 10.4.5.6 ~

# 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

# mascota.example.com. has the IP address 10.1.2.3
mascota.example.com.    A       10.1.2.3 ~
# mascota.example.com. has the IP address 10.5.6.7
paloma.example.com.     A       10.5.6.7 ~
# mascota.example.com. has the IP address 10.9.8.4
vela.example.com.       A       10.9.8.4 ~
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.