DNStool 2.2 administration guide

Gordon.Rowell@gormand.com.au

Inline Index

Introduction
Changes from version 2.0"
The host database
- File structure
Clone Domains
Special Files
Installing DNStool
Running DNStool
Appendix A: h2n options files
Appendix B: h2n manual page
Appendix C: Host database grammar
Appendix D: Known limitations
Appendix E: Credits

Introduction

The Domain Name Service (DNS) auto-configuration system (DNStool) is designed to take the pain out of managing DNS. It does this by automatically generating DNS files from a small number of configuration files. DNS files are in a complex and repetitious format; mistakes or omissions often creep in when manually maintained. In general, it reduces the task of maintaining DNS to 3 steps:

for each domain, maintain a database describing its hosts
maintain a description of the common features across domains
run the configuration programs to generate DNS configuration files and install them.

This document is aimed at DNS administrators and is a description of these three steps in modifying the configuration. The DNS autoconfiguration system does not remove the need to understand the basics of DNS (and the DNS auto-configurer) in order to make major changes to the DNS configuration.

However it does simplify the common tedious error-prone parts of maintaining a DNS installation, such as:

adding or deleting a host
adding or deleting an alias for a host
changing the IP address of a host
adding or deleting a domain
standardising information for all domains or all hosts in a domain
supplying interface-specific hostnames for every host with multiple ip addresses (these are auto-generated)
providing reverse-lookups for domains (which are auto-generated)
updating SOA serial number to apply changes: this is done automatically

For a complete description of the Domain Name Service and named, refer to the excellent book by Paul Albitz and Cricket Liu DNS and BIND. Full details are provided in the Credits section.

Changes from version2.0 BIND8 named.conf files are generated and installed automatically as well as the BIND4 named.boot files

The program bin/hosts2db.pl is provided to convert from /etc/hosts format to the host database format.

A simple method for creating cloned domains is provided. This is useful for sites which need to support large number of virtual hosts and virtual domains. See Clone Domains.

A few variables in the Makefile have been renamed in line with the change of the database directory structure. You no longer need to set OURSUBDOMAINS

Another welcome change is the removal of the restriction which meant that a subnet could not be split across domains. Many thanks to Dave Roberts for the changes to fix this.

In accordance with correct DNS practice, underscores are no longer allowed in hostnames by default. The section Installing DNStool tells you how to change this if you really must support underscores.

The major change from version 2.0 to version 2.1 is the ability to handle multiple top-level domains. In version 2.0, the host database files were stored in the db directory. In version 2.1 and later, separate directories are created in the db directory, one per entry in the variable OURFQDNS in the Makefile. For example, if we dealt with the DNS for gormand.com.au, frog.pond and swamp.net, we would create a minimu of three files, db/gormand.com.au/src.gormand, db/frog.pond/src.frog and db/swamp.net/src.swamp. Each of these files is in the format described in the section describing the host database.

The host database

The host database is a repository of information about the hosts in a domain, of which a subset is of interest to DNS. The other fields are used for other network administration purposes - e.g. building the ethers map, and for keeping machine information such as location, owner, hostid. The current implementation is based on structured ascii files, although future implementations could use, for example, a relational database.

The host database does not contain information about the domain (such as its name servers) or information that is not tied to a host in the domain. It only describes individual hosts in the domain.

The current version allows global aliases to be created for hosts - this alias will be generated in all domains managed by the DNStool. This can be useful to deal with software which does not properly handle domain structures, such as some license packages, and older versions of Sun's rpc.lockd.

File structure

For a semi-formal description of the file syntax, please refer to Host database grammar. For each domain, there is an ASCII host database file consisting of a series of host records. The general structure of the host database is a set of host records, each of which starts with an opening brace { and ends with a closing brace }. Within each host record are a number of clauses, each of which is of the form

    keyword = value

Note: The syntax has been tightened slightly from that allowed in the previous version of this tool. This is due to the simplicity of the current PERL parser when compared with the previous Lex/YACC parser.

Automatically generated names are now created with hyphens instead of underscores (e.g. rarp-110-99 instead of rarp_110_99). This is to comply with RFC952.
There is no line-continuation character
Comments may start with either ; or # and continue to the end of the line. Blank lines and lines containing only comments are ignored. For more details, see the example Value fields may contain comments
Keywords, and opening and closing braces must appear on lines by themselves (with optional trailing comments).
Whitespace is mandatory around the equals sign on keyword = value clauses.
Values for keyword = value clauses may span multiple lines, but the first part of the value must appear on the same line as the keyword. For more details, see the example Multiline value fields
String values must be surrounded by double-quotes " and may not extend across lines
Keywords may be in upper, lower or mixed case, but it is recommended that a consistent use of lower case for keywords is used
A host may have multiple IP addresses on the same subnet. This generates a warning, but is no longer an error. For more details, refer to Multi-homed hosts
The DNS-reverse generation programs in dns2host generate lines which start with the words NS, MX and Nickname. These lines are not inside the braces which delimit host entries and do not have the mandatory = separating the key and value. These lines refer to domain (rather than host) features and are irrelevant in the host database. These were previously ignored, but now cause syntax errors. They will need to be removed manually if the dns2host generation programs are used.

Host record examples

A minimal host record looks like

{
   host = banana
   ip   = 192.168.42.20
}

while an enlarged host record looks like

{
    host     = banana
    ip       = 192.168.42.20
               192.168.15.20
	       192.168.27.20
    aliases  = mailhost loghost
    location = "Level 4 machine room"
    owner    = "Gormand Pty Ltd"
    hostid   = 0xaabbccddeeff
    ether    = AA:BB:CC:DD:EE:FF
    server   = "banana"
    mx       = 5 banana
    os       = "Linux"
    hardware = "AMD K6"
    comment  = "random bit of additional text"
}

The equals sign between a keyword and its value is mandatory and it must be surrounded by whitespace. The host and ip clauses are mandatory and must appear in that order. The rest of the clauses are optional and can appear in any order. So

{
    host  = banana
    ip    = 192.168.42.20
    alias = www proxy mail
    ether = AA:BB:CC:DD:EE:FF
}

and

{
    host  = banana
    ip    = 192.168.42.20
    ether = AA:BB:CC:DD:EE:FF
    alias = www proxy mail
}

are both legal and equivalent.

Readability

For readability

Give a new line to each opening and closing brace. This is mandatory in this version of the DNStool.
Place each clause on its own line
Indent each line of a host record
Line up the equals signs

Keywords

The keywords can be in either upper or lower case, although lower case keywords are recommended. Here is the list of valid keywords

alias <list>: Alternate name(s) for host
barcode <string>: Barcode tag - quoted string
comment <string>: Free form comment - quoted string
ether <etheraddress>: Ethernet address - colon separated
globalalias[es] <list>: Alternate name(s) in all domains
global <list>: Synonym for globalalias
hardware <string>: Hardware type - quote string
hw <string>: Synonym for hardware
host <word>: Hostname
hostid <word>: Hostid or other host key
ip[s] <list>: IP address(es) for host
location <string>: Physical location - quoted string
mx[es] <mxlist>: Mail exchanger records
os <string>: Operating system - quoted string
owner <string>: Owner/maintainer - quoted string
serial <string>: Serial number - quoted string
server <word>: Server for this host

Keywords accepting list values

Some clauses take a list as the value

alias aliases
global globalalias globals globalaliases
ip ips
mx mxes

This is reflected in the keyword syntax : where it sounds sensible, the plural is allowed as a keyword (e.g. ips and aliases). List values are separated by spaces. For example

    alias = mailhost loghost

The syntax of the mail exchanger value is that of the DNS Resource Record, separated by one or more spaces. For example

    mx    = 10 mail 50 mail2

The syntax of the ether value is the conventional representation of ethernet addresses: six groups of one or two hex digits, separated by colons. The letters A-F may be in upper or lower case. For example, all of the following are legal and equivalent

    ether = 1b:2c:3d:04:0c:05
    ether = 1b:2C:3D:44:0C:05
    ether = 1b:2c:3d:44:c:5

There is no requirement to have both a hardware and os clause: you can use either, both or neither. If only one is included, the other will be given the static value blank. This avoids a bug in some early versions of named, which could not handle empty fields in the HINFO resource records.

Multiline value fields

Value fields may extend over multiple lines, and are terminated by the closing } of a host record or another

keyword =
value

clause. The first part of the value field must appear on the same line as the keyword. For example

{
    host = ahost
    ip   = 192.168.8.33
           192.168.10.33
}

is equivalent to

{
    host = ahost
    ip   = 192.168.8.33 192.168.10.33
}

but

{
    host = ahost
    ip   = 
           192.168.8.33
           192.168.10.33
}

is illegal and will produce a syntax error from the parser.

Value fields may contain comments

Comment lines do not terminate value fields. The comment line is skipped in the input. This allows single values from multi-valued fields to be commented out if required. For example


{
    host = ahost
    ip   = 192.168.8.33
	   # 192.168.10.33
           192.168.12.33
}

is equivalent to

{
    host = ahost
    ip   = 192.168.8.33 192.168.12.133
}

Multi-homed hosts

DNStool supports a DNS configuration where a multi-homed host (one with multiple IP addresses) can be referred to by a name which is associated with only one IP address, as well as by a name associated with all the IP addresses. The normal hostname, defined in the host = hostname clause, is a handle referring to all possible IP addresses, and interface-specific hostnames are generated for each of the IP addresses.

For example, given a host padwft1 which has three IP addresses

{
    host = router-1
    ip   = 192.168.10.1 192.168.20.1 192.168.30.1
}

DNStool will automatically produce DNS information for four hosts

router-1 with IP addresses 192.168.10.1, 192.168.20.1, 192.168.30.1
router-1-10 with IP address 192.168.10.1
router-1-20 with IP address 192.168.20.1
router-1-30 with IP address 192.168.30.1

Note that the names of the generated hosts are the hostname, with the subnet number appended (after a hyphen).

Multi-homed on one subnet

In the previous version of the tool, it was illegal to define a host with two IP addresses on the same subnet. There are a few examples where this is required, notably rotary definitions on Annex terminal servers. It is possible to define a rotary on an Annex box whereby a telnet to a specified name will try ports on one Annex, and if all are in use, will move on to trying ports on successive Annex boxes. The Annex boxes may be located on the same subnet. For example

{
    host    = rotary1
    ip      = 192.168.110.199 192.168.110.198
    hw      = "MicroAnnex Annex XL"
    comment = "Annex Rotary"
}

will result in a DNS name rotary1 with two IP addresses, 192.168.110,199 and 192.168.110.198. Once the rotary is defined on the two Annex boxes at these addresses, it is possible to type telnet rotary1, and telnet will try all available ports on one terminal server, followed by the ports on the other terminal server. The above example generates three hostnames

rotary1 with IP addresses 192.168.110.199 and 192.168.110.198
rotary1-110-199 with IP address 192.168.110.199
rotary1-110-198 with IP address 192.168.110.198

The host number part of the address is appended to generate unique names for the two IP addresses on the same subnet. The normal name generation rules for multi-homed hosts would result in two rotary1-110 hosts, which is illegal. The dnstool generates a warning whenever a host record has two distinct IP address entries on the same subnet. See also IP address ranges.

IP address ranges

A host can possess a range of IP addresses, for example

{
    host = rarp
    ip   = 192.168.220.1 .. 192.168.220.4
}

In this situation, DNStool automatically generates DNS information for 4 hosts, named by appending the last two IP components to the host name

rarp-220-1 with IP address 192.168.220.1
rarp-220-2 with IP address 192.168.220.2
rarp-220-3 with IP address 192.168.220.3
rarp-220-4 with IP address 192.186.220.4

Note that, in the case of a range, the host rarp is not generated. IP ranges may contain tens, or hundreds of hosts, whereas DNS resolver queries may only return less than 16 IP addresses per host. These range hosts are only useful in case such as bootp and rarp addresses, where the actual name is not important, just the existance of a name to ip address mapping. IP ranges cannot span subnets, i.e. only the last field of the IP address is allowed to vary in the range. A range specification such as

    ip = 192.168.220.1 .. 192.168.221.12

is illegal. More complex specifications can be constructed using sets of IP addresses, IP ranges, or both. Checks are performed to ensure that a range does not overlap with other IP addresses in the host record or with other IP addresses in the domain. There are two consequences of multiple IP address specifications

It is unnecessary to maintain such hostnames in the host database. In fact you should not do so, as dnstool will exit complaining that hostnames are not unique when it tries to generate the interface-specific hostnames.
You should not create other names for a specific network interface for a host.

For example, the following is illegal

{
    host = foo
    ip   = 192.168.10.1
           192.168.11.1
}

{
    host = foo-le1
    ip   = 192.168.11.1
}

as the ip address 192.168.11.1 appears in two host records. The recommended way to represent this information is to make use of the mechanism provided for multi-homed hosts. That is, use

{
    host = foo
    ip   = 192.168.10.1 
           192.168.11.1
}

and make use of the generated names foo-10 and foo-11 instead of foo-le1.

Clone Domains

Most customers in a web and domain-hosting environment have essentially identical configuration. It is possible to automatically clone domains from a prototype. This is especially useful when the clients domains are all hosted as virtual domains on a single IP address.

Create db/PROTO/src.PROTO and db/PROTO/special.PROTO which list the standard configuration for the domains. Examples are provided in the db/samples directory.
List the domain in PROTODOMAINS. It should also be listed in OURFQDNS, but this is done automatically in the standard Makefile.
Type make as usual. The domains listed in PROTODOMAINS will be linked to the appropriate files in the db/PROTO directory before the domains are generated, and then treated as for any other domain.
If one of the cloned domains requires special configuration and is thus no longer a true clone, just delete the appropriate symlinks in the db/{DOMAIN} directory and replace it with a file with the correct information.

Special Files

Certain DNS features change only rarely and are handled by entering the data into special.${domain} files in the db directory. These features are information such as site-based MX records, delegated sub-domains and delegated sub-networks. These files are copied verbatim into the appropriate output file, and are inserted after the first blank line in the h2n generated output file, i.e. directly after the SOA record.

As these files are copied directly into the output files, it is vital that they are checked for correctness as they will not be checked by the tool. Most importantly, ensure that all lines which should be terminated with full-stops are, as this is the most common error in editing DNS files. Refer to DNS and BIND for full details.

Special files can now be added to any domain file. If a special file exists, it is automatically included just after the SOA of the generated zone file. The files are optional. Some common special files are:

special.${OURDOM}: This file contains any information related to the Fully Qualified Domain name which cannot be described in the host database. Typically this file contains delegations of sub-domains and MX records for the top-level domain. Note that delegation of sub-networks is not done here, but must be performed in db.${OURNET} (or possibly db.iroot if you are using an internal root).
The file is named special.${topdomain}, i.e. the first part of ${OURFQDN}. For example, for gormand.com.au, this file is db/special.gormand and is provided as an example in db/samples/special.gormand. It provides for delegation of the research.gormand.com.au sub-domain.
special.iroot: This file contains any delegations, MX records, etc. which apply to the internal root domain, if an internal root is generated. This file contains delegation of the top-level domain from the internal root and delegation of the in-addr.arpa. domain for the network numbers from the internal root. An example is provided in db/samples/special.iroot
special.${OURNET}: This file can be used to provide delegation of subnets from the top-level network to other nameservers if some subnets are managed by other nameservers.

Installing DNStool

The following steps must be performed before DNStool can generate DNS databases for your domain.

Choose and create a Base directory. This is the root of the DNStool directories, and will contain the tools, the host database files and the output files
Unpack the DNStool tar file into this directory. Various files and subdirectories will be created.
Read the README file for any late breaking news (and a version of these installation instructions).
Edit the Makefile to set the following variables

PERL5
The path to your PERL5 executable. For example, /usr/bin/perl. Note: The DNStool package is based on PERL5, and PERL4 will not work
BASEDIR
The full path to the Base directory, chosen above. For example, /usr/local/domain/src
ALLOW_UNDERSCORES

Underscores are no longer allowed by default, as they are illegal in DNS hostnames. If you really must use underscores, you will need to set ALLOW_UNDERSCORES in the Makefile. For those using BIND8, you will also need to configure your named.conf file to allow underscores. Now would be a good time to change the underscores to hyphens.

OURFQNS
The list fully qualified domains managed by this copy of DNStool. For example, gormand.com.au frog.pond swamp.net.
OURNETS

The root of your top-level network numbers for each of the domains in OURFQDNS. This would usually be a Class B or Class C IP network address, without the trailing zeroes. For example, 192.168. The format of this line is described in the Makefile.

IROOT

Set this to -i if you want to generate an internal root for your network. This should only be used if you are not connected to the Internet or any other external network. Many corporations run internal roots, and you should check whether a corporate internal root exists before you create your own. Nameservers running internal roots must not be directly connnected to the Internet.

PRIMHOST and SECHOSTS

These nominate the name of the primary and secondary DNS hosts and are passed to the Distfile for the make release target.
OLDBASEDIR
This setting specifies the location of the previous DNStool installation. You can then run make compare to see if the output has changed.
Create the db/options.generic file, describing the h2n options for your domain. See db/samples/options.generic for an example, and see Appendix A: h2n options files for full details.
Create a db/src.domain file for the top-level domain. For example, if the OURFQDN is gormand.com.au, there needs to be a db/gormand.com.au/src.gormand file.
Create special.domain files for the top-level domain and internal root domain, if required. See Special Files for full details.
Create db/src.domain files for each domain listed in OURSUBDOMAINS listed above.





Running DNStool

The following explanations assume that the DNStool is installed in
some directory referred to as the base directory. The master Makefile
lives in the base directory. For gormand.com.au, the base directory is
/usr/local/domain.


DNStool directory layout

The DNStool is divided into subprograms. The overall process is
managed by a Makefile in the base directory (the master
Makefile) which sets up the input and output for the relevant
program and runs it. Major configuration variables appear at the start
of the master Makefile.

The following subdirectories exist under the base directory



  bin - This contains the executables for the DNStool, including
       h2, dnsparse. It also includes other tools
       for processing the host databases, such ipsfree for
       finding free IP addresses in a domain and ipsused for
       displaying the IP addresses used in a domain.

  
data - This is for STRICTLY GENERATED FILES
       ONLY. No changes should be made to these files as they will
       be lost on the next run of DNStool. The files can be removed with the
       make clean target. These files can be removed at any time.

  
db - This is the host database. The files in this directory
       describe the various domains in the DNS world managed by this
       DNStool. Each domain should appear in a separate
       src.domain file.

  
dns2host - This contains some tools for generating the host
       database from the installed DNS files. They are not complete,
       will probably require customisation for your site, and work is
       required to turn the output into complete host database
       files. Note that the host database contains a superset of the
       information in DNS, and so these tools should not be used once
       the host database has become the primary source of host
       information as extra details will be lost.

  
install - Generated files are copied from the data
       directory to hierarchies under the install directory as part
       of DNStool's actions. The make release and make
       copy targets copy these
       files to the appropriate directories on the local
       nameserver. The make release target also updates the
       other nameservers throughout your network. These files can be
       removed at any time. 


Making changes

In general there are three actions


  Modify the host database files to add, modify, delete hosts. 
       This should be performed under your normal userid, and not as root

  
Generate the modifed DNS (and other) configuration files - type
       make in the base directory.  
       This should be performed under your normal userid, and not as root.

       Note: The DNStool maintains a lock file (dns.lock) to stop
       people performing concurrent makes on the DNS directories. If a
       make fails, the lock is left to ensure the files are not
       installed and to allow the person doing the make to fix the
       problem. For example

gordonr@wheel[228] make
/usr/local/src/dns/test/dns.lock exists - DNS files are being generated by:
gordonr    pts/29       Nov 27 09:07
*** Error code 1
make: Fatal error: Command failed for target `CheckLock'


       To remove the lock, use the make CleanLock target of the
       Makefile


  
Release the modified files to the network - type make
       release in the base directory.
       This action must be performed as root


Autoconfigure is used below as a shorthand for these
steps.


Modifying the host database

Assume the change is for one domain only - say Ceduna. We want to add
an alias for one of the hosts in the Ceduna domain.

 
   Edit the host database file for Ceduna, called
  hostdb/src.ced. Add an alias to one of the host
  records.

  
Type make in the base directory to use the default
  target. This updates the information for all domains.

  
Check the db.ced and spcl.ced files in the
  data directory to ensure that the alias has been added. The
  db.ced and spcl.ced files are the DNS
  configuration files describing the Ceduna hosts and aliases,
  respectively.

  
If there were errors, these will have been displayed onscreen
  and copied to the err.ced file in the data
  directory.
       
  
If there were no errors in the parsing, the freshly updated
  output files will also be copied to the install
  subdirectory. The install directory is not modified if any
  errors occur, to ensure that the install directory contains
  valid and up-to-date DNS configuration files.

  
 
  In the base directory, in an appropriate root account, run
  make release. This calls rdist -f Distfile
  which distributes the files to all servers and signals their named
  process. Over time the information will propogate to the secondary
  zone servers automatically.
  

  
  If you are unable to run rdist, you can use the make copy
  target instead. This will not update the named.boot or named.conf
  files on the secondary nameservers - you will need to do this manually.
  




Add a new subdomain


  Add the name of the subdomain to the OURSUBDOMAINS
  line in the master Makefile
  
  
Create a src.dar file in the db directory, and add
  host information for the Darwin domain to it

  
Auto-configure as usual



Changing nameservers

DNStool supports two classes of DNS nameserver

  Public - These nameservers appear in the SOA record for the
  domain and will be queried by "foreign" nameservers -
  nameservers outside your domain.

  
Private - These nameservers do not get added to the SOA
  record. They are still valid nameservers, and may contain identical
  information to the public namservers, but they will not be queried
  by "foreign" nameservers.


Within the two classes, there are a number of types of nameserver



   Primary - The central point of authority for DNS
  information. This is typically the host which has the host database,
  and on which DNStool is run. Secondary nameservers are updated from
  this nameserver.
  

  Secondary - These nameservers are updated by DNS zone transfers
  from the primary nameservers. They are still authoritative
  nameservers, although their information may be slightly out of date
  with respect to the information on the primary. The make
  release target informs all of the secondary nameservers when
  changes are made to the host database, asking them to update their
  databases as soon as they are able.
  



Cache only and forwarding nameservers are not supported by DNStool.

Now, assume you want to add some host foo.gormand.com.au
as another secondary nameserver for your domains.


  
  Add foo.gormand.com.au to the list of secondary hosts
  to whom DNS files are distributed by rdist by listing the host in
  the SECHOSTS variable in the Makefile.
  

  If the nameserver is to be public, add another -s
  nameserver statement to the db/options.generic file,
  i.e. -s gormand.com.au. This is not required for
  private nameservers.


Now, as usual, auto-configure to apply your changes.

Note: If you add/change/delete public nameservers, you
must inform your parent domain and any delegated
subdomains of the new list of nameservers.


Name all interfaces of multi-homed host

Nothing to do. DNStool automatically generates a name for each
interface on a `multi-homed' host, in the form name-subnet. For
example, padwft1-20 is the interface of the host padwft1
on the 20 subnet.

For details, see Multi-homed hosts


Create new subnet

Nothing to do. Describe the host in the host database, then
auto-configure as usual. The reverse lookup information for the new
subnet, and for the host in particular, will be automatically
generated.


Add or modify a cross-domain alias

Add a global clause to the host record for the host in
question. The global alias will appear in all domains managed by this
copy of DNStool.


Modify external domain nameservers

TODO: Secondary external nameservers are not complete in this
  release of DNStool 2.0


Clean all strictly generated data files

Use the make clean target of the master Makefile. This only
cleans strictly generated data files, which live in the data
subdirectory.

It is also possible to use the make veryclean target to
clean both the data and install subdirectories,
although this is not normally required.


Modify name servers for the delegated subdomains


  Modify the db/special.topdomain file to change the
  nameservers. Remember, this file is included directly into a DNS
  output file, and must be syntactically correct.
       
  
Auto-configure



Modify top-level domain public nameservers

The public nameservers for all domains are controlled by the
db/options.generic file. Change this file and then
autoconfigure.


Initialise the host database

The host database is produced in the db subdirectory, where it can be
edited and installed. The host database can be initially produced by
reverse-engineering the installed DNS files. This is done by a Perl
program, called srcgen.perl, which reads the installed
DNS files and translates them into the simpler format of the host
database. This program, and an example Makefile, live in the
hostdb subdirectory. These are examples, and will need
massaging for your particular DNS setup.


There is also a program in bin/host2db.pl which will
convert /etc/hosts files to the host database format.

Having performed the "reverse-engineering" once to
initialise the database with the existing information, the host
database will be manually maintained (as it will grow to contain a
superset of the DNS data and will be used for additional
purposes). 


The program and its subsidiary files are in the dns2host
subdirectory, and the host database lives in the db
subdirectory. The host database is isolated from other strictly
generated data files. The hosts database consists of a group of
structured ascii files (one per domain), called
src.domain. For example, src.bwy is
the section for the bwy domain.



The process in detail

A program, called dnsparse, reads the host database,
checks its syntax and translates it to an intermediate form. If any
syntax errors are found in the file for a certain domain, dnsparse
will not produce output files for this domain. Errors are written to a
file in the data directory of the form
err.domain as well as displayed on the
screen.

Limited semantic checking is done - semantic checks show that the file
is `sensible' as well as syntactically correct. An error is produced
for duplicate hostname or IP addresses within one domain (but not
cross-domain). A warning message is produced for multiple occurrences
of an ethernet address, but this does not affect dnsparse's
output. Other checks - nonsensical mail exchanger info and so on - are
not currently made.


Produce the /etc/hosts intermediate format

The host database is translated by dnsparse into a format
accepted by the DNS configuration file builder,
h2n. This format is that of the /etc/hosts file, with some subsidiary
files (known as comment and spcl files).

The output files are written to the data subdirectory
(where all strictly generated files are placed). They are called



  hosts.domain

  
Contains the normal IP address to hostname mappings of the
  /etc/hosts file. Hostnames may appear with multiple IP addresses.
       
  The comment field starts with a #, immediately followed by a
  number. This number is used as a key in the
  resources.domain file. If the comment field
  contains the string [no smtp], h2n will not
  generate a default MX record for this host.


  The default MX record is an MX record of weight 10, directed at this
  host. This default MX record is suppressed for all hosts generated
  by dnsparse. Extra MX records to override the -m
  weight:host options to h2n should be entered using
  the mx = weight host clause in the host database.

       
  
resources.domain
       
  
Contains BIND resource records, such as HINFO, TXT, WKS and MX
  records. Each line consists of a number, followed by a colon,
  followed by the resource record. For example
       
       10: IN HINFO "SUN" "UNIX"
       10: IN MX 10 mail.gormand.com.au
       

       would generate HINFO and MX records as above for the host
       number 10 in the hosts.domain file.
       
  
spcl.domain
       
  
Contains any CNAME (alias) resource records. For example
       
       me      IN CNAME myself.gormand.com.au
       

       would generate the CNAME record for the host me. Note
       that the spcl.domain files are included
       in the final output using $INCLUDE
       spcl.domain directives to BIND.

  
globals.domain
       
  
Contains a list of global aliases from the host database
  file. The format is identical to the spcl.domain file. This
  file is not directly used by h2n, but its contents are
  appended to the spcl.domain files before
  calling h2n.

  
nets.domain

  
Contains a list of network numbers discovered in the host
  database file. Each line is of the form -n a.b.c.d,
  ready to be passed into h2n.

  
ethers.domain
       
  
Contains a list of ethernet address to hostname mappings found
  in the host database file. The hostnames are entered as fully
  qualified domain names. If duplicate Ethernet addresses are found in
  the host database file, only the first will be written to the
  ethers.domain file. This file is not used by
  h2n but can be used to generate the ethers NIS
  maps.

  
dbg.domain

  
Contains the debugging output of the parser. It is not normally
  used except for debugging parsing errors.
       
  
err.domain

  
Contains the stderr output of the parser. This may contain
  errors, which cause the parser to stop, and/or warnings, which allow
  the parser to continue. Warnings are generated for non-fatal
  problems , such as duplicate Ethernet addresses, whereas errors are
  generated for fatal problems such as duplicate IP addresses or
  hostnames.


During the conversion process the syntax, and some semantics, of the
host database are checked. No output files, except for
dbg.domain and err.domain are maintained in the event
of syntactical or semantic errors and the parser exits with an error
status, causing the make to fail.


Produce the DNS configuration files

This step runs h2n, the DNS configuration file builder, on the files
produced in the previous step. h2n takes a set of parameters
(described above as the h2n options files) and host information in the
form of the /etc/hosts file and subsidiary files. It produces DNS
files: the boot files and data files.

h2n assumes that its input files are in the current directory, and
puts its output files there, and so h2n is run from the
data directory.

Therefore h2n is run from the data
directory.  h2n is a Perl program, by Liu and Albitz.  It has been
modified to


Some changes have been made to h2n, to properly deal with large sites
and internal root domain



  use the system time as the serial number in the SOA record
  instead of incrementing the pre-existing serial number. The change
  means that the output files from h2n can be removed at any time
  without causing problems.
       
  
 the primary zone server is made to be a secondary for certain
       external domains

  
 the boot file directory statement (which specifies the location
       of the DNS files) is changed to /var/named by default, from h2n's
       preference for the directory in which it was run

  
 a directory hierarchy has been imposed on the output files,
  with zone files placed in the /var/named/zone
  subdirectory, reverse files in the /var/named/rev
  directory and any secondary backup files in /var/named/bak.
       
  
 file names for the internal root are made less error-prone
       (db. changed to db.iroot).


A trap for the unwary: h2n will reuse SOA time values from an existing
h2n-produced file in preference to SOA values given to it in the
option file. So to ensure a change to SOA time values takes effect,
remove existing files (by using the make clean target of
the master Makefile). This means the relevant
db.domain files will be removed (as well as
others) and h2n will start with a fresh slate.

There is another consequence of h2n's desire to read existing h2n
output files if any exist. h2n assumes that the first few lines of a
file of the form db.domain contain a SOA
record. This means we do not customise all files with a header comment
that warns that the file is machine generated as it would break
h2n. The only files which have this warning are the boot files however
the warning applies to all the files generated by DNStool.



Install DNS configuration files

Three sets of DNS configuration files are produced - those for


  a primary zone nameserver
       
  
a secondary zone nameserver

  
a secondary external zone nameserver (one which has connectivity
  to domains outside the zone)


Secondary servers are secondary for all domains except the internal
root for which they are primary. This is because secondary root
servers are not (officially) supported.


Appendix A: h2n options files

Common features across domains are specified in a file called
db/options.generic. This file is in the format of
the parameters file for DNS configuration file builder, h2n. See Appendix B: h2n manual
page for a complete description of these options.

It is also possible to create options.${domain} files
for extra options pertaining to a particular domain. These options
are currently appended to the options specified in the
options.generic file.


This file enables features to be readily standardized across domains,
such as the name servers, the time-to-live values of data, and contact
information. The more standard the domains, the simpler the task of
the DNStool (its sysadmin and programmer). At present the domains are
made to be as uniform as possible. They have a common set of name
servers, contact information, time-to-live data and default mx records.


Here is the current options.generic for the gormand.com.au domain


-h banana.gormand.com.au
-u hostmaster@gormand.com.au
-o 10800:3600:3600000:86400
-z 192.168.13.1
-s banana.gormand.com.au
-s bigted.gormand.com.au
-s hambyl.gormand.com.au
-m 10:mail.gormand.com.au


In brief, there are three public name servers
banana.gormand.com.au, bigted.gormand.com.au
and hambyl.gormand.com.au. Refer to Changing nameservers for more detail about
namserver types.

The Start of Authority record (the -u/o options to h2n) defines the
specified helpful person and authoritative host and time-to-live
periods. Secondary servers consult a certain host (specified by IP
address in the -z option) for data.


This file is used to generate an option file for each domain, which is
given to h2n. The auto-configuration deduces additional options:



   the domain name 
  
 the network numbers in the domain
  
 whether the domain has a `hosts' file or a `resources' file to be
       passed to h2n


Note that the network numbers are deduced from the host database
dynamically: the addition of a host on a new network in a domain will
be reflected automatically in the list of network numbers. 

The network numbers are assumed to be those of subnets of a Class B
network (in the form N.N.S), except for the internal root and top
level domains which have a constant value.


Note that options.generic does not include the serial number in the
SOA field. Instead, every time the DNStool is run, it generates a new
serial number for the generated files (from the system time) ensuring
that the information will propogate correctly.



Appendix B: h2n manual page

NAME
 h2n - Translate host table to name server file format

SYNOPSIS

 h2n -d DOMAIN -n NET [options]

DESCRIPTION


h2n translates /etc/hosts to DNS files and creates a BIND boot
file. This tool can be run once or many times. After converting your
host table to DNS format, you can manually maintain the DNS files, or
you can maintain the host table and run h2n each time you modify
/etc/hosts. h2n automatically increments the serial number in each DNS
file when it makes a new one.


h2n generates files starting with the prefix "db." These are
called "db files." The domain data is stored in a file
called db.DOMAIN, where DOMAIN is the first label in your domain name
(given with the -d option). The address-to-name data is stored in
files named db.NET, where NET is a network number (given with the -n
option).


Each time h2n is run, it generates the DNS files from scratch. Any
changes you manually made to the DNS files are lost. If you'd like to
add resource records to a db file generated by h2n, put your RRs in a
file prefixed with "spcl" instead of "db". h2n
will include this file's data by adding a $INCLUDE directive to the
end of the db file.


By default, h2n will generate an MX record with a weight of 10 that
points to the host itself as the mail exchanger. MX records can be
suppressed with -M. Additional MX records can be added with -m. To
suppress generating the default MX record for a host, include
"[no smtp]" in that host's host table comment. By default,
h2n will create a boot file, ./boot.cacheonly, for a caching only name
server. If either of the -z or -Z options are used, h2n creates a boot
file, named ./boot.sec.save or ./boot.sec respectively, for a
secondary name server.


Options are:


  -b BOOTFILE Use BOOTFILE instead of the default: ./named.boot

  
-c DOMAIN Create CNAME records in the default domain for all the
       hosts in DOMAIN. Including more than one -c option is allowed

  
-d DOMAIN Your domain name is DOMAIN

  
-e DOMAIN Eliminate all lines from the host table with names in
       DOMAIN. Including more than one -e option is allowed

  
 -f FILE Command line options are in a file called FILE. This
       option cannot be used within FILE

  
 -h HOST Use HOST in the fields of the SOA record that require a
       hostname. The default is the host on which you run h2n

  
 -m WEIGHT:MX-HOST Include an MX record for each host in your
       domain pointing to MX-HOST at WEIGHT. Including more than one -m
       option is allowed. Example: -m 10:terminator.movie.edu
       -m20:wormhole

  
 -n NET[:SUBNETMASK] NET is your network number without the
       trailing zeros. Including more than one -n option is allowed. If
       SUBNETMASK is provided, create data for each subnet of NET

       Example: -n 192.249.249 -n 15.15.16:255.255.248.0


  
 -o REFRESH:RETRY:EXPIRE:MINIMUM Change the default SOA values
       (10800:3600:604800:86400) to the values provided

  
 -s SERVER List SERVER in each domain's NS records. Including more
       than one -s option is allowed

  
 -t Generate TXT records from the host table comments. If
       [no smtp] appears in a comment, it is ignored

  
 -u USER Use USER in the SOA mail address instead of root. USER
       can be a complete mail address as in: me@a.b.c.

  
 -w Generate WKS records that list the SMTP service over the TCP
       protocol if an MX record is also created

  
 -z ADDRESS Create a boot file, ./boot.sec.save, for a secondary
       name server that lists ADDRESS as the master to load from. Save a copy
       of the domain data in a backup file. (This option is similar to the -Z
       option.)

  
 -C COMMENT-FILE Create resource records by using keys in the host
       table comment field as indices into COMMENT-FILE. COMMENT-FILE
       contains "key:resource record" pairs like: "720:IN
       HINFO hp9000s720 hp-ux". When h2n encounters "720" in
       the comment section of the host table, it creates a resource record by
       replacing the "720:" with the host's canonicalname.

  
 -H HOSTFILE Use HOSTFILE instead of /etc/hosts

  
-M Don't generate MX records

  
 -N SUBNETMASK Apply SUBNETMASK to all network numbers instead of
       listing each subnet with -n. Specifying a subnet mask with -n
       overrides the -N subnet mask for that network only.

  
 -Z ADDRESS Create a boot file, ./boot.sec, for a secondary name
       server that lists ADDRESS as the master to load from. Do not save a
       copy of the data in a backup file. (This option is similar to the -z
       option.)


EXAMPLES


  Create name server data for networks 192.249.249 and
       192.253.253 in movie.edu.

        h2n -d movie.edu -n 192.249.249 -n 192.253.253


  
 Create name server data for networks 192.249.249 and
       192.253.253 in movie.edu. Eliminate lines in the host table that
       contain fx.movie.edu and include MX records for all hosts pointing
       to the mail hub, postmanrings2x.movie.edu. Include all of the
       options in a file.

       h2n -f option_file


       where option_file contains the following lines:

       
       -d movie.edu
       -n 192.249.249
       -n 192.253.253
       -e fx.movie.edu
       -m 50:postmanrings2x.movie.edu
       



Appendix C: Host database grammar

This section provides a semi-formal description of the grammar (in a
mixture of EBNF/PERL)

file         = blank* (record | blank)*

blank        = (^\s*$ | ^\s*[#;].*)

record       = OPEN hostclause ipclause clause* CLOSE

hostclause   = HOST EQUAL \w+

ipclause     = IP EQUAL ipaddress+

ipaddress    = \d+.\d+.\d+.\d+

clause       = etherclause  | 
	       hostidclause |
	       listclause   | 
               quotedclause |
               wordclause


etherclause  = ETHER EQUAL etheraddr

wordclause   = plainkeyword EQUAL word

listclause   = listkeyword EQUAL word+

quotedclause = quotekeyword EQUAL QUOTE .* QUOTE

etheraddr    = hex:hex:hex:hex:hex:hex

word         = \w+

hex	     = [A-Fa-z\d][A-Fa-z\d]?

listkeyword  = ALIAS    |
	       GLOBAL   |
               IP       |
               MX       

quotekeyword = BARCODE  |
               COMMENT  | 
               HARDWARE |
	       LOCATION | 
	       OWNER    |
               OS       |
               SERIAL

plainkeyword = HOST     |
               HOSTID   |
               SERVER

ALIAS        = alias  | aliases
BARCODE      = barcode
COMMENT      = comment
ETHER        = ether
GLOBAL       = global | globals | globalalias | globalalias
HARDWARE     = hw     | hardware
IP           = ip     | ips
LOCATION     = location
MX           = mx
OWNER        = owner
OS           = os
SERVER       = server

OPEN         = {
CLOSE        = }
EQUAL        = =
QUOTE        = "



 Appendix D: Known limitations

None known at this time.


Appendix E: Credits

Original version of DNStool and documentation by Jennifer Brown and
Gordon Rowell. This has been in use since 1993.


Modifications by Dave Roberts to remove the restriction of one domain
per subnet by running h2n in subdirectories. Many thanks Dave.


Additional tools in the bin directory from Peter Samuel and Mark Probert


h2n was written by Paul Albitz and Cricket Liu. Thanks
also for their excellent book DNS and BIND, O'Reilly and
Associates, ISBN 1-56592-010-4. Anyone managing a site using DNS
should have a copy of this book.


Testing, use and suggestions by system administrators from Telstra IBU
Information Systems and Telstra Intelligent Network Development.


Additional feedback from Marc Jolly, Charles Butcher, Mark Pfeiffer
and Peter Samuel.


Bugs, comments and suggestions to me: 
<Gordon Rowell>