CONFFLE(5)

NAME

conffile - configuration file for atomdns

DESCRIPTION

A conffile specifies the handlers atomdns should chain. The syntax is as follows:

    ZONE [ZONE]... {
        [HANDLER]...
    }

Such a section is called a handler block. Each block defines the handlers this server should run when it gets a query for one the ZONEs.

The ZONE defines for which zones this handler should be called, multiple zones are allowed and must be white space separated.

When a query comes in, it is matched again all zones of all handlers blocks, the block with the longest match for the query name will receive the query and runs it through it's defined handlers.

HANDLER defines the handlers(s) we want to load. This is optional as well, but a block with no handlers will just return REFUSED for all queries. Each handler can have a number of properties that can have arguments, see the documentation for each handler (atomdns-HANDLER(7)).

The order of the HANDLERs is the order in which they are executed! (If you know CoreDNS, this is different, as which CoreDNS the order is fixed compile time). I.e. putting the log handler (atomdns-log(7)) as last, means no queries are logged.

Comments are allowed and begin with an unquoted hash # and continue to the end of the line. Comments may be started anywhere on a line.

Environment variables are supported and either the Unix or Windows form may be used: {$ENV_VAR_1} or {%ENV_VAR_2%}.

The ~ (tilde) character and path names will be expanded to the home directory of the current user.

As an way to test things Conffile also supports a shorter way of writing things, but this only works for a single handler:

    ZONE [ZONE]...
    [HANDLER]...

I.e.

    example.org
    log
    whoami

Is a valid configuration and is supported by atomdns.

GLOBAL

A Conffile must have a global block, this is a block without a zone and holds server wide options, like how many instances to run, if you want DOH and DOT servers, etc. etc. For each server type (DNS - plain DNS, DOT - DNS over TLS, DOH - DNS over HTTP, and DOU - DNS over Unix sockets) you have a section dns, dot, doh and dou where you can configure the server, most notably the address and port you want to listen on.

    {
        dns {
            addr [::]:1053
        }
        root /var/lib/atomdns
        metrics localhost:9153
    }

Here we say we should only run a DNS server listening on port 1053 on all addresses, set the root directory to "/var/lib/atomdns" and enable metrics. See atomdns-global(7) for more information.

IMPORT

You can use the import "handler" to include parts of other files, or snippets that are defined in the configuration file see atomdns-import(7). To prevent infinite recursion a maximum of a 1000 imports are allowed.

SNIPPETS

If you want to reuse a snippet you can define one with and then use it with import.

    (mysnippet) {
        log
        whoami
    }
    example.org {
        import mysnippet
    }

EXAMPLES

The ZONE is root zone ., the handler is chaos. The chaos handler takes an (optional) argument: atomdns-001. This text is returned on a CH class query: dig CH TXT version.bind @localhost.

    . {
        chaos atomdns-001
    }

When defining a new zone, you either create a new block, or add it to an existing one. Here we define two blocks that each handle a different zone, that potentially chain different handlers:

    example.org {
        whoami
    }
    org {
        whoami
    }

But this is identical to:

    example.org org {
        whoami
    }

Reverse zones can be specified as domain names:

    0.0.10.in-addr.arpa {
        whoami
    }

Or by just using the CIDR notation:

    10.0.0.0/24 {
        whoami
    }

This also works on a non octet boundary:

    10.0.0.0/27 {
        whoami
    }

Doing Let's Encrypt certificates for your DOH servers:

    {
        root /var/lib/atomdns
        dns {
            addr [::]:1053
            limits {
                tcp -1
                run numcpu()*3
            }
        }
        doh {
            addr [::]:10053
            limits {
                run numcpu()*1
            }
        }
        tls lets-encrypt {
            source eth0
            contact miek@miek.nl
            directory lets-encrypt
        }
    }
    example.net {
        log
        dbfile example.net
    }

AUTHORS

atomdns authors.

COPYRIGHT

Apache License 2.0

SEE ALSO

The manual page for atomdns: atomdns(1) and the manual pages for the handlers. Particular atomdns-global(7) for the server parameters.