wiki:ZoneLoadingRequirements

BIND 10 Zone File Loading Requirements

  1. BIND 10 Zone File Loading Requirements
    1. 0. About This Document
    2. 1. Introduction
      1. 1.1 Definitions
    3. 2. Overall description
    4. 3. Specific Requirements
      1. 3.1 External interface requirements
        1. 3.1.1 C++ data source
      2. 3.2 Functional Requirements
        1. 3.2.1 Zone loading any time
        2. 3.2.2 Zone loading from file
        3. 3.2.3 Zone loading from stream
        4. 3.2.4 Determining the target data source
        5. 3.2.5 Overriding the target data source
        6. 3.2.6 Guessing zone name
        7. 3.2.7 Setting origin
        8. 3.2.8 Issues and strictness
        9. 3.2.9 Default strictness profiles
        10. 3.2.10 Handling and reporting of issues
        11. 3.2.11 Content of issue reports
      3. 3.3 RFC implementation requirements: parsing
        1. 3.3.1 White space
        2. 3.3.2 Parenthesis
        3. 3.3.3 CRLF allowed with text literals
        4. 3.3.4 Comments
        5. 3.3.5 Blank lines
        6. 3.3.6 $ORIGIN control entry
        7. 3.3.7 $INCLUDE control entry
        8. 3.3.8 $INCLUDE control entry on streams
        9. 3.3.9 RR owner name handling with name
        10. 3.3.10 RR owner name handling without name
        11. 3.3.10 RR owner name handling without name, missing previous owner name
        12. 3.3.11 RR style
        13. 3.3.12 Domain names with arbitrary characters
        14. 3.3.13 Relative domain names
        15. 3.3.14 Character strings
        16. 3.3.15 At-sign '@' for origin
        17. 3.3.16 Quoted characters
        18. 3.3.17 Octets
        19. 3.3.18 Broken octets
        20. 3.3.19 Parenthesis
        21. 3.3.20 Broken parenthesis
        22. 3.3.21 Semicolon
        23. 3.3.22 Label and name size limits
        24. 3.3.23 TTL limits
        25. 3.3.24 $TTL control entry
        26. 3.3.25 Unspecified TTL
        27. 3.3.26 TYPE#
        28. 3.3.27 Generic RDATA
        29. 3.3.28 Ownername after $INCLUDE file
      4. 3.4 RFC implementation requirements: zone definition
        1. 3.4.1 Class restrictions
        2. 3.4.2 SOA singleton
        3. 3.4.3 Missing glue
        4. 3.4.4 Out-of- bailiwick data
        5. 3.4.5 CNAME unique for ownernames
        6. 3.4.6 CNAME in RDATA values
        7. 3.4.7 CNAME broken
        8. 3.4.8 RR in an RRSet with different TTL
        9. 3.4.9 DNAME vs. DNAME/CNAME
        10. 3.4.10 DNAME no-descendants
      5. 3.5 Requirements based on BIND 9 extensions
        1. 3.5.1 Named TTL values
        2. 3.5.2 $GENERATE directive
      6. 3.6 More Ways to Break Stuff
        1. 3.6.1 Bogus class values
        2. 3.6.2 Missing RDATA
        3. 3.6.3 Bogus RDATA
        4. 3.6.4 Unknown RTYPE, specified as symbol
        5. 3.6.5 Infinite CNAME loops
        6. 3.6.6 Missing A/AAAA referred to by RDATA
        7. 3.6.7 Data source does not support some labels
      7. 3.7 Helpful Hints
        1. 3.7.1 Obsolete RR types
        2. 3.7.2 Hostname checking
        3. 3.7.3 SOA RNAME with @
        4. 3.7.4 SOA expire less than SOA refresh+retry
        5. 3.7.5 Delegation hides data
      8. 3.8 Performance requirements
        1. 3.8.1 Limit memory used when loading
    5. Appendix A. Existing Setup

0. About This Document

This document describes the requirements for loading zone file information into BIND 10. It is roughly based on the SRS documented on the Wikipedia:

http://en.wikipedia.org/wiki/Software_Requirements_Specification

1. Introduction

When acting as an authoritative or master server BIND 10 needs DNS information. At run time, this information is read from a "data source". A data source is an abstract representation of DNS information, which allows BIND 10 to answer queries or serve as a master, using any sort of storage for the data. Currently BIND 10 provides an SQLite-based data source and an in-memory data source.

In principle data can be represented in any way, and loaded into data sources though generic or data-source-specific means. However, DNS provides a standard way to represent the contents of a single DNS zone: the zone file, described in RFC 1034 and RFC 1035.

BIND 10 should have a correct and efficient way of way of loading any zone file into a data source. There may be some data sources that do not support this operation, but it should be available unless there is a specific reason. BIND 10 should provide generic support for loading a zone file into a data source.

1.1 Definitions

issue: an "issue" is either a warning or an error with the zone contents, discovered while loading a zone

2. Overall description

Zones will be loaded into persistent data sources (like the SQLite data source) via a stand-alone program, that can run when the system is inactive or active. The authoritative server, b10-auth, will load transient data sources (like the red/black tree data source) at runtime.

The zone loading deliverable involves providing both the stand-alone program and any changes to b10-auth to support runtime loading.

Zone loading involves a little bit of parsing and a lot of checking.

The zone loader will need to read a zone file, specified either from a file name or from a data stream. The format will be RFC 1034/RFC 1035 with BIND 9 enhancements.

The zone loader will need to perform two basic types of checks:

  • Checks on each resource record (RR) and RR set (RRset) as it is loaded.
  • Checks on the entire zone for consistency.

Some checks across the entire zone may be done during load (for example, looking for multiple SOA values), while some checks may need to be done after the load is complete (for example checking for RR at the same ownername as a CNAME).

Ideally the loader will collect all errors and warnings for the zone file, rather than exiting on the first error.

We assume that the BIND 10 libdns++ library will be used for manipulating zone data.

3. Specific Requirements

3.1 External interface requirements

3.1.1 C++ data source

The loader will use the BIND 10 C++ data source as the location where data is stored.

3.2 Functional Requirements

3.2.1 Zone loading any time

It must be possible to load a zone during runtime. If a data source supports it, it must be possible to load a zone when the system is not running.

3.2.2 Zone loading from file

It must be possible to start zone loading given a file name. Any errors accessing this file should be returned.

3.2.3 Zone loading from stream

It must be possible to load a zone from an input stream.

3.2.4 Determining the target data source

The loader should determine the target data source from the BIND 10 configuration.

3.2.5 Overriding the target data source

It must be possible to override the system-defined target data source.

3.2.6 Guessing zone name

If the name of the zone is not specified, the loader should guess based on the SOA in the zone. A flag indicating that the name was guessed must be set, and a way to get the name provided.

3.2.7 Setting origin

It must be possible to set the origin when loading a zone, or to leave it as unset.

3.2.8 Issues and strictness

It should be possible to set whether any given issue is interpreted as a warning or an error, although some problems must always be errors. It should be possible to control all of these issues by a profile.

3.2.9 Default strictness profiles

Three default profiles are defined:

  1. Full strictness, where any issue found is an error
  2. Normal strictness, where some problems are reported as warnings
  3. "Relaxed" strictness, where many real problems are allowed (this is primarily intended to support zone checking when acting as a secondary, but may be useful in other contexts)

Interpretation of the zone contents under "relaxed" strictness should still be consistent for all data sources.

3.2.10 Handling and reporting of issues

Loading should continue in spite of issues, if possible. For example, an unknown RRTYPE should not break loading. A reasonable approach to continue after an error may be to read until end of line and start parsing again. Issues should be collected and available for review when the load is complete.

3.2.11 Content of issue reports

The following information should be available for each issue:

  • unique issue number for this loading attempt
  • unique issue identifier (like our log message identifiers)
  • description of the error (something like "SSHFO is not a known RRTYPE")
  • file name (if available, especially useful for $INCLUDE files)
  • line number in the file where the error was first discovered
  • byte offset in the file where the error was first discovered

3.3 RFC implementation requirements: parsing

This section covers the specification of zone files based on IETF RFCs. The main reference for this is RFC 1035, section 5, "MASTER FILES".

3.3.1 White space

Both tabs '\t' and spaces ' ' can be used in any amount to separate items that make up an entry.

RFC 1035, section 5.1, paragraph 1

3.3.2 Parenthesis

Parenthesis must be allowed to continue a list of items across a line boundary. (See 3.3.19 and 3.3.20 )

RFC 1035, section 5.1, paragraph 1

3.3.3 CRLF allowed with text literals

Text literals must allow "\r\n" within the text.

RFC 1035, section 5.1, paragraph 1

3.3.4 Comments

Any line may end with a comment. The comment starts with a semicolon ';'. (See 3.3.21)

RFC 1035, section 5.1, paragraph 1

3.3.5 Blank lines

Blank lines, with or without comments, are allowed anywhere in the file.

RFC 1035, section 5.1, paragraph 2

3.3.6 $ORIGIN control entry

The relative domain name is set to the domain name specified.

RFC 1035, section 5.1, paragraph 3

$ORIGIN names that do not with a dot are usually interpreted as a warning, and should be reported. $ORIGIN names that do not end with a dot are interpreted as a normal name, relative to the current origin.

3.3.7 $INCLUDE control entry

The $INCLUDE inserts the named file into the current file, optionally specifying an origin for the included file.

If the named file cannot be loaded it is an issue, and usually treated as an error. If treated as a warning, it is ignored for processing.

RFC 1035, section 5.1, paragraph 3

3.3.8 $INCLUDE control entry on streams

The $INCLUDE control entry on a stream input is an issue usually interpreted as an error, and should be reported. If treated as a warning, it is ignored for processing.

Note: this requirement is probably unnecessary, and may be removed

3.3.9 RR owner name handling with name

If the RR begins with a name, then the owner name is reset to that name.

RFC 1035, section 5.1, paragraph 4

3.3.10 RR owner name handling without name

If the RR begins with a blank, then the owner name is the last stated owner.

RFC 1035, section 5.1, paragraph 4

3.3.10 RR owner name handling without name, missing previous owner name

If there was no previous owner name, this is an issue and usually interpreted as an error. If treated as a warning, the RR can be checked but will not be added to the zone.

3.3.11 RR style

RR may be specified as:

[<TTL>] [<class>] <type> <RDATA>
[<class>] [<TTL>] <type> <RDATA>

TTL and class are optional. By RFC 1035 TTL is a decimal integer, but see 3.5.1 Named TTL Values for our handling.

RFC 1035, section 5.1, paragraph 5

3.3.12 Domain names with arbitrary characters

Domain names can contain arbitrary characters if quoted.

RFC 1035, section 5.1, paragraph 6

3.3.13 Relative domain names

A domain name without an ending dot '.' is relative and has the origin appended to it. If there is no origin, it is an issue that is usually interpreted as an error. If treated as a warning, the domain name is considered absolute.

RFC 1035, section 5.1, paragraph 6

3.3.14 Character strings

A character string (used for either domain names or some RDATA) is either a set of characters without spaces or as a double-quoted string. See 3.3.16 for quoting within a character string.

A missing closing '"' is an issue, and usually treated as an error. If treated as a warning, then the end of file is treated as the closing quote.

RFC 1035, section 5.1, paragraph 7

3.3.15 At-sign '@' for origin

The @ by itself is treated as the origin.

RFC 1035, section 5.1, paragraph 8

3.3.16 Quoted characters

A \X where X is not a digit treats the character as literal. Example from RFC 1035 include inserting a double-quote '"' in a character string, or to insert a dot '.' in a label.

RFC 1035, section 5.1, paragraph 8

3.3.17 Octets

The use of \DDD where each D is a digit means the ASCII character defined by the decimal number DDD. This is not checked for special meaning (so \064 would not be treated as @).

RFC 1035, section 5.1, paragraph 8

3.3.18 Broken octets

Any appearance of \D, \DD are considered issues, and are usually considered warnings. If treated as a warning, they are interpreted as the decimal number D or DD.

\DDD with values more than 255 are considered issues, and are usually considered errors. If treated as a warning, they are interpreted as DDD modulo 255.

3.3.19 Parenthesis

These group data that crosses a line boundary. Line terminations are not recognized within parenthesis.

RFC 1035, section 5.1, paragraph 8

3.3.20 Broken parenthesis

Parenthesis do not nest. A second open paren before a close paren is an issue, and usually considered a warning. If treated as a warning, it is ignored.

A missing closing parenthesis is considered an issue, and usually interpreted as an error. If treated as a warning, the end of file is treated as the closing parenthesis.

3.3.21 Semicolon

Semicolon is used to start a comment, the rest of the line is ignored.

RFC 1035, section 5.1, paragraph 8

3.3.22 Label and name size limits

Labels must be 63 bytes or less. Names must be 255 bytes or less. A violation of either of these is an issue, and usually interpreted as an error. If treated as a warning, then the line with the incorrect value should be skipped.

RFC 1035, section 2.3.4

3.3.23 TTL limits

TTL must be less than 232. A longer TTL is an issue, and usually interpreted as a warning. If treated as a warning, then 232-1 is used for a value.

RFC 1035, section 2.3.4

3.3.24 $TTL control entry

A $TTL directive can be specified at the top of the zone file, before the SOA. It then sets the default TTL for every record without a specific TTL.

NOTE: Use of this directive changes behavior from RFC 1035, which specifies that the last TTL specified is used if none is specified.

NOTE: BIND 9 documentation suggests this must appear at the top of the zone file, however RFC 2308 has no such restriction.

RFC 2308, section 4

3.3.25 Unspecified TTL

If a record has no TTL specified, then the previous $TTL value is used. If no $TTL was specified, then the last TTL previously used is used. If neither was specified, then this is an issue and is usually interpreted as a warning. If interpreted as a warning then the TTL from the last field of the SOA is used, unless the SOA has not yet been seen, in which case must be interpreted as an error.

RFC 1035, section 5.1 paragraph 5
RFC 2308, section 4

3.3.26 TYPE#

RR types not known may be specified using TYPE# and then binary data. See 3.3.27 Generic RDATA for description of the binary data.

The number must be between 0 and 65535. Any other value is interpreted as in 3.6.4 Unknown RTYPE, specified as symbol.

RFC 3597, section 5

3.3.27 Generic RDATA

The encoding is specified as:

The special token \# (a backslash immediately followed by a hash sign), which identifies the RDATA as having the generic encoding defined herein rather than a traditional type-specific encoding.

An unsigned decimal integer specifying the RDATA length in octets.

Zero or more words of hexadecimal data encoding the actual RDATA field, each containing an even number of hexadecimal digits.

This generic RDATA format can be used for ANY RR type, even one with a known format.

Any error with this format, such as not having enough hexadecimal data for the length, is an issue usually considered an error. If considered as a warning, then the RR is skipped.

RFC 3597, section 5

3.3.28 Ownername after $INCLUDE file

The "previous name" after an $INCLUDE is the same as before the $INCLUDE. For example with this:

foo.example.com. IN A 192.0.2.1
$INCLUDE some_file ; which ends with "bar.example.com. IN A 192.0.2.2"
      IN AAAA 2001:db8::1

We use foo.example.com for the AAAA record. Note that this is different from some other implementations, and not fully specified in RFCs.

3.4 RFC implementation requirements: zone definition

3.4.1 Class restrictions

All RR in the zone should have the same class. RR with other classes is an issue, and usually treated as an error. If treated as a warning, then the first class used in the zone is used for the RR.

RFC 1035, section 5.2, paragraph 2, item 1.

3.4.2 SOA singleton

The SOA must only appear once in the zone. If it appears again with the same value, it is considered an issue and usually treated as a warning. If treated as a warning then the second value is ignored.

If it appears again with a different value, it is considered an issue and usually treated as an error. If it is treated as a warning, then the second value is ignored.

RFC 1035, section 5.2, paragraph 2, item 2.

3.4.3 Missing glue

If glue is required for delegations (NS records) then it must be present. If neither an A nor an AAAA record is present, this is an issue and usually treated as a warning. If treated as a warning the zone is loaded without the necessary data and the delegation is broken.

Note that a delegation without any A or AAAA glue is more broken, and will not resolve at all. This is a separate issue, and is usually treated as an error. If treated as a warning the zone is loaded without the necessary data and the delegation is completely broken.

RFC 1035, section 5.2, paragraph 2, item 3.

3.4.4 Out-of- bailiwick data

Information outside of the authority for the zone, other than glue, is an issue, and usually considered an error. If interpreted as a warning, it is ignored.

RFC 1035, section 5.2, paragraph 2, item 4.

3.4.5 CNAME unique for ownernames

If a CNAME is present, no other data should be present except for an RRSIG RR or NSEC/NSEC3 RR. If other data is present, this is an issue, and usually considered an error. If interpreted as a warning, then the data will be loaded, but server operations may be unpredictable.

RFC 1912, section 2.4
RFC 4034, section 3

3.4.6 CNAME in RDATA values

If a CNAME is present in a RR, for example in MX or NS records, it is an issue, and usually considered a warning. If interpreted as a warning, then the data will be loaded and the server should provide correct operations.

RFC 1912, section 2.4

3.4.7 CNAME broken

If a CNAME points to a value in the zone that is missing, this is an issue, and usually considered a warning. If interpreted as a warning, then the data will be loaded and the server should provide correct operations.

RFC 1912, section 2.4

3.4.8 RR in an RRSet with different TTL

If RR in an RRSet have different TTL this is an issue, and usually considered a warning. If interpreted as a warning, then the lowest TTL of any RR in the RRSet is applied to the entire RRSet. Note that if the RRSet is signed, then this must be considered an error.

RFC 2181,section 5.2

3.4.9 DNAME vs. DNAME/CNAME

A DNAME RR must not have another DNAME or a CNAME with the same name. If one is present, this is an issue, and usually considered an error. If interpreted as a warning, then the data will be loaded, but server operations may be unpredictable.

RFC 2672, section 3

3.4.10 DNAME no-descendants

A DNAME RR must not have any descendant data of that name. If descendant data is present, this is an issue, and usually considered a warning. If treated as a warning then the descendant data is removed from the zone when loaded. Note that this may partially break DNSSEC-signed zones.

RFC 2672, section 3

3.5 Requirements based on BIND 9 extensions

This section is informed by the Zone File section of the BIND 9 ARM.

3.5.1 Named TTL values

A zone file may have values specified with the following units:

Character Units
S seconds
M minutes
H hours
D days
W weeks

These may be combined in any way:

2d4W
4h4m16s
2h3h

If combined, then the values are added. If no unit is specified, seconds is used. Values do not need to fit, for example you can use more than 60 minutes:

90m
72h

See also 3.3.23 TTL limits.

3.5.2 $GENERATE directive

The $GENERATE directive looks like this:

$GENERATE range lhs [ttl] [class] type rhs [ comment ]

This will generate set of RR based on a range of numbers. For details of the fields see the BIND 9 ARM section on Zone Files.

Any parsing problems are issues, and should be considered errors by default. If they are considered warnings, then the $GENERATE directive is ignored.

Here are some examples of parsing problems:

  • badly formatted range
  • stop of range < start of range
  • badly formatted lhs or rhs
  • type other than PTR, CNAME, DNAME, A, AAAA, or NS

The use of $$ in the lhs should be considered an issue, and default to a warning. If treated as a warning, $$ is interpreted as a literal $.

3.6 More Ways to Break Stuff

3.6.1 Bogus class values

The only allowed classes are IN, CH, and HS. Other values will not be recognized as a class value, and will be treated as an unknown RR type.

3.6.2 Missing RDATA

If the RDATA is missing, this is an issue usually considered an error. If treated as a warning, then the RR is skipped.

3.6.3 Bogus RDATA

If the RDATA is improperly formatted, this is an issue usually considered an error. If treated as a warning, then the RR is skipped.

3.6.4 Unknown RTYPE, specified as symbol

If the RTYPE is unknown and specified as the symbol, this is an issue usually treated as an error. If treated as a warning, then the RR is skipped.

3.6.5 Infinite CNAME loops

Some infinite CNAME loops can be detected. If one is found, it is an issue and should be considered an error. If interpreted as a warning, then the data will be loaded and the server should provide correct operations.

3.6.6 Missing A/AAAA referred to by RDATA

If RDATA refers to an ownername that expects an IP address but there no A or AAAA RR for that ownername, this is an issue and should be considered a warning. If it is interpreted as a warning, then the data will be loaded and the server should provide correct operations.

This is at least true for MX, SRV, and NS records.

3.6.7 Data source does not support some labels

Some data sources may not support all labels. For example, a file-system based data source might support a limited range of characters. If this is the case, then trying to load a label with a non-supported name is an issue and usually considered an error. If treated as a warning, then the label is ignored. Note that this may break some signed zones.

3.7 Helpful Hints

These items are not actually issues, but may be reported if the administrator asks for it.

3.7.1 Obsolete RR types

Some types are listed as obsolete by IANA, such as MD, MF, or A6. These may be reported.

http://www.iana.org/assignments/dns-parameters

3.7.2 Hostname checking

Labels that are not valid hostnames may be reported, for example if they have an underscore character, like unixy_host.example.com.

RFC 1912, section 2.1, paragraphs 3 to 5

3.7.3 SOA RNAME with @

If someone accidentally includes an @ symbol in the RNAME this is probably a mistake, and can be reported. If reported, it may also be auto-corrected to a '.' instead.

3.7.4 SOA expire less than SOA refresh+retry

If expire is less than the sum of SOA refresh + SOA retry it can become stale.

3.7.5 Delegation hides data

If an NS record causes delegation for a zone, then other records may be hidden:

FOO.EXAMPLE      NS   NS1.FOO.EXAMPLE
                 NS   NS2.FOO.EXAMPLE
BAR.FOO.EXAMPLE  A   192.0.1.2

We can detect this and report it.

3.8 Performance requirements

3.8.1 Limit memory used when loading

The loader MUST NOT require the entire zone file be loaded into memory at any time during reading. Since this means that zone-level checks will require multiple passes across the zone, the loader MAY offer a mode where the entire zone is kept in memory.

Appendix A. Existing Setup

Currently BIND 10 has two independent ways to load zone files, neither of which is complete.

The first method is via the 'b10-loadzone' program. This application was written when the SQLite data source was the only one available, and before an API for modifying data source contents was present. It modifies the SQLite database directly. The parser it uses can best be described as a "quick hack", and it allows a lot of bogus zones to be loaded.

The second method is embedded in the 'b10-auth' program, and is only used when loading zone files to the in-memory data source. It has no knowledge of any directives or even the previous ownername, so is only able to load zones that have been carefully pre-processed with the 'named-checkzone' program from BIND 9.

Last modified 5 years ago Last modified on Jan 2, 2013, 1:53:50 PM