GENDNS(1)

NAME
gendns - update the DNS zone files from flat relational tables

SYNOPSIS
gendns [ -d dbdirectory ] [ -l dhcp_lease_file [ -v ] [ -F ]

DESCRIPTION
Updates the DNS zone files.

gendns is a back end to the updatehosts command. It should normally only be invoked from the updatehosts command.

gendns converts a set of flat (relational) files into the standard DNS zone file format. All input files are kept in the dbdirectory which can be specified by the -d command line option. All output is placed in the current directory. When run under updatehosts the current directory is normally /var/named and the input directory is normally /var/named/db. However, these defaults may be overridden. See the updatehosts(1) manual page for details.

The -l option specifies the location of the dhcp_lease file. It defaults to /etc/dhcpd.leases. gendns has the capability of reading the lease file information and generating name to IP address mappings when the IP address of a host is set to "dynamic".

The -v option generates additional output on the progress of the zone file generation.

The -F option forces a zone files serial number to be updated even though no changes were made to the zone file. This was the default behavior before updatehosts 1.0.2. Now if the information in a zone file does not change, the zone file's serial number is not not updated. This saves slave zone transfers when updatehosts handles a large number of zone files.

Input File Formats

gendns uses readinfo (see readinfo(1)) to preprocess the input files. The format of each file consists of a set of records separated into fields. Care should be taken to insure the field names are not altered. Otherwise gendns will complain. Each fields attributes should be examined carefully when editing the input files. Usually, default suffixes and prefixes are added so domain names and IP addresses can be written in a shorthand fashion. However, the output from readinfo read by gendns is expected to have fully qualified domain names and full dotted quad IP addresses. Each file's record structure is described as follows:

main:
    Contains information about each host. The fields in this file are as follows:

    host:
        The domain name of the host.

    ip: The IP address of the host. May be set to "dynamic" when the dynamic addressing of DHCP is in use.

    ether:
        The hardware MAC address of the host.

    hard:
        The hardware type of the host.

    os: The operating system of the host.

    contact:
        The name of a contact person or user of the host.

    ptr:
        Either "yes" or "no". Tells gendns whether to generate the reverse zone entry for the host (e.g.the IP address to domain mapping zone). The default (empty) value is "yes".

    ttl:
        Specifies the time to live field for both the address (A record type) and the reverse PTR record if generated. Time is specified in seconds. If this field is empty the default ttl for the zone (specified in the SOA record) is used.

gendns only needs entries for the domain and ip fields. The other fields may be empty.

cname:
    Species information about hosts and their aliases. The fields are:

    host:
        The domain name of a host

    alias:
        The alias for the host

    ttl:
        The time to live for this record

mx: Specifies information about MX (mail exchanger) records.

    domain:
        The mail domain name

    priority:
        The MX record priority

    host:
        The domain name of the mail forwarder

    ttl:
        The time to live for this record

ns: Specifies information about nameserver records.

    domain:
        The nameserver domain

    server:
        The domain name of the server for each domain

    ttl:
        The time to live for this record

soa:
The SOA (start of authority)  record information for each domain served.

    domain:
        The domain (zone) this server is authoritative for

    server:
        The domain name of the primary server for this domain

    contact:
        Email address of domain contact. Per DNS format rules the '@' in the address is specified as a ".".

    refresh:
        The refresh interval for this zone in seconds

    retry:
        The retry interval for this zone in seconds

    expire:
        The authoritative expiration time in seconds for secondary servers which have not been refreshed within the interval specified.

    min:
        The minimum time to live for resource records within this zone without a ttl.

    checknames:
        Specifies how illegal domain names are treated within this zone. Only works with version 8 of bind. The 3 legal values of this field are:

        warn:
            Warns about illegal names, but allows the names within a zone. Emits an error message about the name.

        ignore:
            Ignores illegal names within the zone.

        fail:
            Emits error messages about illegal names and does not load the zone.

    notify:
        If this field is "yes", all secondary servers are notified about updates. Only works with Version 8 of bind.

secondary
    Specifies zones this server will act as a secondary server for. In bind version 8 a secondary server is known as a slave server.

    domain:
        The name of the domain being served.

    ip: The IP address of an authoritative server for this zone. Multiple servers may be specified by separating the IP address with commas.

    checknames:
        Same values as the checknames field in the soa records.

global:
    Contains global parameters applicable to all zones.

    directory:
        The name of the directory containing the generated zone files.

    cache:
        Name of the root cache file

    forwarders:
        list of optional forwarders for this server. This field is usually empty

    checknames:
        Same as the checknames field found in each zone, but applies to all zones. Individual zones may override this value.

    slave:
        Sets up this server as a slave server (stub in bind version 8 parlance). Can be either "yes" or "no". The default is "no".

Zone File Generation

Zone file generation is driven off of the soa file. Each domain specified in the soa file generates a separate DNS zone file. The name of the zone file is the same as the name of the domain field for forward zones. For a zone under in-addr.arpa (e.g. IP address to name mapping), the name of the zone file is the IP network address of the zone with an "f." prefix. For classless in-addr.arpa delegation of Class C addresses, the assumption is the delegation is done per RFC2317. The zone file name replaces the "/" in the delegation reference with a "-". For example delegating the subnet of 199.10.2.0/28 means delegating the zone 2/28.0.10.199.in-addr.arpa. The zone file in this case would be named f.199.10.2.0-28. A zone file is only generated if it appears in the soa file. Records in the other input files which are not members of a generated zone are silently ignored.

The program scans all the input files for domain records within each zone and generates all the records for the zone.

The serial number field is updated automatically for each new zone. The serial number is encoded from the real time clock value as yyyymmddxx, where yyyy is the 4 digit year, mm is the 2 digit month, dd is the 2 digit day, and xx is a 2 digit number between 00 and 99. This gives a granularity between updates of about 15 minutes.

Bootstrap File Generation

gendns also generates the bootstrap file for either version 4 or version 8 of the bind nameserver. The generated bootstrap file is put in the current directory (usually /var/named). To allow the nameserver to use the newly generated bootstrap file it is customary to link it to either /etc/named.boot for a version 4 nameserver or /etc/named.conf for a version 8 nameserver.

Error Handling

An error message is issued for any CNAME (alias) record which is illegal. A CNAME record must only appear at a leaf node in the DNS hierarchy. Any record which violates this rule is dropped. A warning message is issued for any duplicate IP address or duplicate A records. These are warnings only, since duplication of domain names or IP addressed may be desirable.

See also

updatehosts(1)