Zone file format

From Avuna
Jump to: navigation, search

Zones

Zones are a system of organization by domain and domain level, used in different formats on almost all DNS servers. In Avuna, the files are read sequentially, line-by-line down the file, in completion to serve a request.

Format

The Avuna Zone file is a list of entries (directives or records), one per line. Comments are started by a pound sign (#).

Domains

Domains can have a variety of modifiers and wildcards to filter requests.

  • If the entire domain is a '@' or a '*', all requests of the type of the record will be returned.
  • At any subdomain section in a domain, there can be a '*' or '**' to indicate partial wildcards. The double-star will match a variable-length amount of subdomains.
    *.test.com # matches cat.test.com, dog.test.com, but not test.com or dog.cat.test.com.
    **.test.com # matches cat.test.com, dog.test.com, test.com, and dog.cat.test.com
    cat*.test.com # matches strictly cat*.test.com, not a wildcard
  • Any domains, including pure wildcards ('@' or '*'), can begin with a tilde (~) to signify that they are only to be matched if no other record of the same type has been returned yet in the request. This can be used for default or fallback records.
    ~@ # at the top of the master zone, is equivalent to '@', but anywhere else will not return if any other record of the same type has yet been returned for the domain
    #separate example below
    test.com A 3600 1.2.3.4
    ~@ A 3600 5.6.7.8 # A request for cat.test.com would return only 5.6.7.8, but a request for just test.com would return only 1.2.3.4

Directives & Records

In Avuna Zones, there are two types of entries, directives and records.

Directives

The directives currently supported by Avuna are:

  • $zone - Zones define a subzone, there are two arguments: the path to the file relative to the current zone file or the system root, and the domain that the zone matches. Only searches that match the domain will look for records under the zone.
  • $roundstart - Roundstart starts a round-robin zone, there is one argument: the maximum number of records to be returned. If there are fewer or equal records in the round-robin as this number, then all will be returned.
  • $roundstop - Ends a round-robin zone, takes no arguments.

Records

An example of a record:
domain.com A 3600 1.2.3.4
Which is of the format:
domain record-type TTL(in seconds) data(ip address, domain, MX record, etc)

Domains

See the domains section above.

Record Types

Record types can be all of the commonly used non-DNSSEC DNS record types. Supported DNS Types:

  • A
  • NS
  • CNAME
  • SOA
  • PTR
  • MX
  • TXT
  • AAAA
  • SRV
  • DNAME

Time-To-Live

Avuna can accept a single number in seconds, or a range of the format
1800-7200
for which a random TTL will be chosen for each request.

This is how long other DNS servers may cache the record.

Data

The format of the data part is dependent on the record type. A list of formats is below:

  • A - A single IPv4 address.
  • NS - A single domain name.
  • CNAME - A single domain name.
  • SOA - MNAME, RNAME, SERIAL, REFRESH, RETRY, EXPIRE, MINIMUM (technical)
  • PTR - A single domain name.
  • MX - a priority number from 0->65535, space, domain name.
  • TXT - a quote bounded string, "my TXT record"
  • AAAA - a single IPv6 address.
  • SRV - Space separated, priority, weight, port, target(domain)
  • DNAME - A single domain name.

MySQL Zones

Zones can be sourced from a MySql database as configured in the configuration file.

Format

There is one table, 'records' which is structured as such:

records
Field Type Attributes Default Value Description
id int(10) unsigned Non-null primary key with auto increment set Bookkeeping ID
domain varchar(256) Non-null @ Same as defined above.
priority bigint(10) Non-null 0 Similar to line numbers in a text file, describes the priority for each record. Local to each zone.
zoneid int(11) Non-null 0 Parent zone id, can only be 0 for the master zone record.
rr_count int(11) Non-null 0 The number of round-robin records to return for this zone, 0 to disable.
rec_type varchar(8) A Same as defined above.
rec_ttl varchar(32) Non-null 3600 Same as TTL defined above.
rec_data text Non-null NULL Text value of record as you would use in the file.

Round-robin in MySQL

Round-robin must be done for an entire zone in the database, all must have the 'rr_count' field set higher than zero and equal to each other. They must all also have the same priority (you must never have the same priority elsewhere).

Creating Zones Under The Master Zone

In order to mark a record as a new zone, set its 'rec_type' to NULL (MySQL NULL). The zone record itself has its priority in the priority namespace of its parent.