Zone file format
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.
The Avuna Zone file is a list of entries (directives or records), one per line. Comments are started by a pound sign (#).
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 220.127.116.11 ~@ A 3600 18.104.22.168 # A request for cat.test.com would return only 22.214.171.124, but a request for just test.com would return only 126.96.36.199
Directives & Records
In Avuna Zones, there are two types of entries, directives and records.
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.
RecordsAn example of a record:
domain.com A 3600 188.8.131.52Which is of the format:
domain record-type TTL(in seconds) data(ip address, domain, MX record, etc)
See the domains section above.
Record types can be all of the commonly used non-DNSSEC DNS record types. Supported DNS Types:
Time-To-LiveAvuna can accept a single number in seconds, or a range of the format
1800-7200for which a random TTL will be chosen for each request.
This is how long other DNS servers may cache the record.
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.
Zones can be sourced from a MySql database as configured in the configuration file.
There is one table, 'records' which is structured as such:
|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.