Gordon Rowell
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.
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 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.
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.
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.
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
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
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.
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.
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 }
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).
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.
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.
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.
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.
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.
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.
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.
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.
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
OLDBASEDIR
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'
This setting specifies the location of the previous DNStool installation. You can then run make compare to see if the output has changed.
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.
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 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
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.
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
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 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.
TODO: Secondary external nameservers are not complete in this release of DNStool 2.0
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 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
The public nameservers for all domains are controlled by the db/options.generic file. Change this file and then autoconfigure.
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.
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.
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.
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.
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.
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.
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
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 = "
None known at this time.
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 Gordon Rowell