dso

dso - implements RFC 8490 DNS Stateful Operations and RFC 8765 DNS Push Notifications.

To include the plugin in another CoreDNS build, add this entry to plugin.cfg after tls:

dso:github.com/kentzo/coredns-dso

Then build CoreDNS:

go get github.com/kentzo/coredns-dso@latest
go generate
go build -o coredns .

See also Dockerfile .

The dso plugin allows clients to establish DNS Stateful Operations sessions. The service runs alongside the DNS server of its server block, on its own ports (TCP and/or TLS). It reuses the listen hosts of that server block, so bind applies to it as well and only the ports differ.

A DSO service belongs to exactly one DNS server. While a single DNS server may be defined by several server blocks, only one full form is allowed. The remaining blocks may repeat bare dso so that traffic to any of them pairs the service, see Examples.

If push is enabled, RFC 8765 DNS Push Notification service is provided over TLS that notifies subscribed clients about changes in resource records. The plugin then also responds authoritatively to queries received over a session for names within the push zones; other names are answered with NOTAUTH and without push such queries are refused. TLS and TSIG configurations are taken from tls and tsig respectively, see Bugs.

Discovery of DSO services is performed by clients and is outside of the plugin's responsibilities. Typically for DNS Push Notifications the main DNS server must respond to _dns-push-tls._tcp.<ZONE> SRV query.

Bare form:

dso

The bare form installs the handler only and starts no service. It supplements the full form which must still be defined but at least once server block of a DNS server.

Full form:

dso {
    tcp_port PORT
    tls_port PORT
    keepalive KEEPALIVE [INACTIVITY]
    reconnect ONRESTART ONSHUTDOWN
    log
    push [ZONES...] {
        classes CLASS...
        types TYPES...
        refresh DURATION
        debounce DURATION
    }
}

• tcp_port PORT and tls_port PORT are the ports the service listens on. At least one of the two must be specified.
• keepalive KEEPALIVE [INACTIVITY] sets keep alive and inactivity timeouts. KEEPALIVE must be at least 10s. If INACTIVITY is omitted, it is set to KEEPALIVE. Since server is a passive observer, requests for shorter timeouts are granted as it allows to shed dead connections sooner. Defaults to 1h and 1m respectively.
• reconnect ONRESTART ONSHUTDOWN is the retry delay sent to clients when CoreDNS configuration is reloaded or the process is gracefully shut down. Defaults to 5s and 15s respectively, set to negative to disable.
• log enables use of CoreDNS logging system to print incoming and outgoing DSO messages. If the debug plugin is enabled, malformed messages are hex dumped.
• push [ZONES...] enables RFC 8765 DNS Push Notifications; requires tls_port. ZONES are the zones subscriptions are allowed for. If empty, the zones from the server block are used.
• push.classes CLASS... configures list of RR classes that Class: ANY subscriptions resolve to. Defaults to IN.
• push.types TYPE... configures list of RR types that Type: ANY subscriptions resolve to. Defaults to A, AAAA, PTR, TXT and SRV.
• push.refresh DURATION sets delay between lookups. Defaults to 1m, set to 0 to disable.
• push.debounce DURATION tames subscription burst by waiting before performing the first lookup. Defaults to 1s, set to 0 to disable.

If monitoring is enabled (via the prometheus plugin) then the following metrics are exported:

• coredns_dso_session_duration_seconds{server} - histogram of session durations.
• coredns_dso_push_subscription_entries{server,rrtype} - if push is enabled, number of active push subscriptions.
• coredns_dso_push_subscription_requests_total{server,rrtype} - if push is enabled, number of push subscription requests.
• coredns_dso_push_subscription_hits_total{server,rrtype} - if push is enabled, number of successful push subscription requests.

Minimal DSO service:

example.org {
    dso {
        tcp_port 8053
    }
}

Minimal DSO service with DNS Push Notifications:

example.org {
    dso {
        tls_port 8853
        push
    }
    tls ...
}

Minimal DSO service for a DNS server defined by two server blocks:

example.org {
    dso {
        tls_port 8853
        push example.org example.net
    }
    tls ...
}

example.net {
    dso
}

DSO service is deferred until handler installed by the plugin sees at least one message from its parent DNS server.

CoreDNS does not (and often cannot) notify plugins of changes in the zones. Thus Push must periodically poll upstream. These lookup queries can be distinguished as their local address is set to DSO's endpoint.

Since a DSO service belongs to exactly one DNS server, the Corefile is constrained in three ways:

• dso can be used at most once per server block.
• All keys of a server block using dso must listen on the same port.
• At most one server block per DNS server may carry the full dso form; the others must use the bare dso form.

Per RFC 8765, push server must respond to DNS queries for served zones. However, it's possible to define a plugin stack such that additional information present in client's DNS queries may result in answers that differ from push lookups.

RFC 8490 for DNS Stateful Operations and RFC 8765 for DNS Push Notifications. See the tls plugin for configuring certificates and the tsig plugin for configuring TSIG secrets.