==== Authoritative DNS serving ====

=== Using MaraDNS as an authoritative DNS server ===

== Table of contents ==

* Requirements

* What is a domain zone?

* Setting up a domain with MaraDNS

* Setting up a domain zone file

* The format of a Domain Zone file

* A single name can have multiple records

* The % character shortcut

* Getting connected to the root name servers

* Getting two IPs

* Names internal to a network

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

== Setting up a domain with MaraDNS ==

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

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

A mararc file which can be used to servethe domain zonesthat 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: 

* 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 agentfor 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 preceding 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 (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: 

* Substitute 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.

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: 

* One name server for example.com is called ns1.example.com.

* The IP for ns1.example.com 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/) is 10.10.10.19

* The IP for www.example.com is 10.10.10.19

* The name of the machine which processes incoming mail, which has a 
  priority of ten (lower priority numbers are more important), is 
  called mail1.example.com.

* The IP for mail1.example.com 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, is the DNS node that this 
  record is attached to.

* The next portion of a DNS record, which is optional, tells MaraDNS 
  what kind of DNS record this is. A list of DNS records which 
  MaraDNS supports is described here. If this field is absent, 
  MaraDNS assumes that the record is an "A" (32-bit IP address) 
  record, and that the second portion is the IP address in 
  question.

* If the record is not an "A" record, the subsequent fields describe 
  the DNS record in question. The format for this data depends on 
  the DNS 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. 

== 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 belowfor 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 
masterdocument. 

== 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 abovefor 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.  

