                  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 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 = "/opt/local/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 /opt/local/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 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 preceeding 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 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.

   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 in 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 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 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 because 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.
