dns_zone (dns_erlang v4.8.1)

DNS Zone File Parser

This module provides functionality to parse DNS zone files according to RFC 1035 and related specifications.

Specification Compliance

RFC-Defined Features (Standard):

RFC 1035 §5: Master file format, resource record syntax
RFC 1034 §3.6.1: Resource record conceptual model
RFC 2308 §4: $TTL directive and time unit syntax

Supported RFC Features:

All DNS record types supported by this library
Zone file directives: $ORIGIN, $TTL, $INCLUDE (RFC 1035)
Multi-line records using parentheses (RFC 1035 §5.1)
Comments (semicolon to end-of-line, RFC 1035 §5.1)
Relative and absolute domain names (RFC 1035 §5.1)
Time values with units: w, d, h, m, s (RFC 2308 §4)
All DNS classes: IN, CH, HS, CS (RFC 1035)
@ symbol for current origin (RFC 1035 §5.1)
Blank owner names inheriting from previous RR (RFC 1035 §5.1)

BIND Extensions (Non-Standard):

$GENERATE: BIND-specific directive for generating multiple similar RRs
- Status: Parsed but NOT implemented (template expansion TODO)
- Warning: Not portable to all DNS software
- See: https://bind9.readthedocs.io/en/latest/chapter3.html

The parser uses Erlang's parsetools (leex and yecc) for lexical analysis and parsing.

Examples

% Parse a zone file from disk
{ok, Records} = dns_zone:parse_file("example.com.zone").

% Parse zone data from a string
ZoneData = <<\"
example.com. 3600 IN SOA ns1.example.com. admin.example.com. (
                      2024010101 ; serial
                      3600       ; refresh
                      1800       ; retry
                      604800     ; expire
                      86400 )    ; minimum
example.com. 3600 IN NS ns1.example.com.
www 3600 IN A 192.0.2.1
\">>,
{ok, Records} = dns_zone:parse_string(ZoneData).

Summary

Types

error_detail()

Detailed error information with context and suggestions.

error_location()

Error location information.

error_type()

Error type classification.

parse_options()

Options for parsing zone files.

Functions

format_error/1

Format a parse error into a human-readable string.

parse_file(Filename)

Parse a zone file from disk.

parse_file(Filename, Options)

Parse a zone file from disk with options.

parse_string(Data)

Parse zone file content from a string or binary.

parse_string/2

Parse zone file content from a string or binary with options.

Types

error_detail()

-type error_detail() ::
          #{type := error_type(),
            message := unicode:unicode_binary(),
            location => error_location(),
            context => binary(),
            suggestion => unicode:unicode_binary(),
            details => term()}.

Detailed error information with context and suggestions.

type - Classification of the error
location - Where the error occurred (line, column, file)
message - Human-readable error description
context - The line of text where error occurred (if available)
suggestion - Helpful suggestion for fixing the error (if available)
details - Original technical error details

error_location()

-type error_location() ::
          #{line => pos_integer(),
            column => pos_integer() | undefined,
            file => file:filename() | undefined}.

Error location information.

line - Line number where error occurred (1-indexed)
column - Column number if available (1-indexed)
file - Filename if parsing from file

error_type()

-type error_type() :: file | lexer | parser | semantic.

Error type classification.

file - File I/O error (e.g., file not found)
lexer - Lexical analysis error (invalid tokens)
parser - Syntax parsing error (grammar violation)
semantic - Semantic validation error (invalid data)

parse_options()

-type parse_options() ::
          #{origin => dns:dname(),
            default_ttl => dns:ttl(),
            default_class => dns:class(),
            base_dir => file:name_all(),
            filename => file:name_all(),
            chunk_size => non_neg_integer()}.

Options for parsing zone files.

origin - Initial $ORIGIN for relative domain names (default: <<>>)
default_ttl - Default TTL for records without explicit TTL (default: 0)
default_class - Default DNS class (default: ?DNS_CLASS_IN)
base_dir - Base directory for $INCLUDE directives (default: "")
filename - Source filename for error reporting (internal, set by parse_file)

Functions

format_error/1

-spec format_error(error_detail()) -> iolist().

Format a parse error into a human-readable string.

Takes an error from parse_file/1,2 or parse_string/1,2 and returns a formatted string suitable for display to users.

Examples

case dns_zone:parse_file("bad.zone") of
    {ok, Records} -> ok;
    {error, Error} ->
        io:format("~s", [dns_zone:format_error(Error)])
end.

parse_file(Filename)

-spec parse_file(file:filename()) -> {ok, [dns:rr()]} | {error, error_detail()}.

Parse a zone file from disk.

Returns {ok, Records} where Records is a list of #dns_rr{} records, or {error, Reason} if parsing fails.

Examples

{ok, Records} = dns_zone:parse_file("/path/to/zone.db").

parse_file(Filename, Options)

-spec parse_file(file:filename(), parse_options()) -> {ok, [dns:rr()]} | {error, error_detail()}.

Parse a zone file from disk with options.

Options (all optional):

origin => Domain - Set the initial $ORIGIN
default_ttl => TTL - Set the default TTL
default_class => Class - Set the default class (defaults to IN)
base_dir => Dir - Set base directory for $INCLUDE directives

Examples

{ok, Records} = dns_zone:parse_file("zone.db", #{origin => <<"example.com.">>}).

{ok, Records} = dns_zone:parse_file("zone.db", #{
    origin => <<"example.com.">>,
    default_ttl => 3600
}).

parse_string(Data)

-spec parse_string(binary() | string()) -> {ok, [dns:rr()]} | {error, error_detail()}.

Parse zone file content from a string or binary.

Examples

ZoneData = <<\"example.com. IN A 192.0.2.1\">>,
{ok, Records} = dns_zone:parse_string(ZoneData).

parse_string/2

-spec parse_string(binary() | string(), parse_options()) -> {ok, [dns:rr()]} | {error, error_detail()}.

Parse zone file content from a string or binary with options.