dnsredir

coredns-dnsredir auto build Platform Corefile License

Name

dnsredir - yet another seems better forward/proxy plugin for CoreDNS, mainly focused on speed and reliable.

dnsredir plugin works just like the forward plugin which re-uses already opened sockets to the upstreams. Currently, it supports UDP, TCP, DNS-over-TLS, and DNS-over-HTTPS and uses in continuous health checking.

Like the proxy plugin, it also supports multiple backends, which each upstream also supports multiple TLS server names. Load balancing features including multiple policies, health checks and failovers.

The health check works by sending . IN NS to upstream host. Any response that is not a network error(for example, REFUSED, SERVFAIL, etc.) is taken as a healthy upstream.

When all upstream hosts are down this plugin can opt fallback to randomly selecting an upstream host and sending the requests to it as last resort.

Syntax

The phrase redirect and forward can be used interchangeably, unless explicitly stated otherwise.

In its most basic form, a simple DNS redirecter uses the following syntax:

dnsredir FROM... {
    to TO...
}

An expanded syntax can be utilized to unleash of the power of dnsredir plugin:

dnsredir FROM... {
    path_reload DURATION
    url_reload DURATION [read_timeout]

    [INLINE]
    except IGNORED_NAME...

    spray
    policy random|round_robin|sequential
    health_check DURATION [no_rec]
    max_fails INTEGER

    to TO...
    expire DURATION
    tls CERT KEY CA
    tls_servername NAME
    bootstrap BOOTSTRAP...
    no_ipv6

    ipset SETNAME...
    pf [+OPTION...] NAME[:ANCHOR]...
}

Some of the options take a DURATION as argument, zero time(i.e. 0) duration to disable corresponding feature unless it’s explicitly stated otherwise. Valid time duration examples: 0, 500ms, 3s, 1h, 2h15m, etc.

Metrics

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

Where server is the Server Block address responsible for the request(and metric). matched is the match flag, "1" is it’s in any name list, "0" otherwise.

Caveats

Bugs

Sometimes you modified Corefile and yet Caddy server failed to reload the new config with the error “Error during parsing”, dnsredir will do sanity check during parsing, if you misconfiged the Corefile, you’re out of lock:

Also note that some of the properties are cumulative: INLINE, except, to, ipset, in which case INLINE domains should be put one domain per line.

Rationale: Strict checking to ensure that user can detect errors ASAP, and make the Corefile less confusing.

If you think you found a bug in dnsredir, please issue a bug report. Enhancements are also welcomed.

Acknowledgments

Implementation and documentation of this plugin mainly inspired by forward, proxy, hosts plugin.

Part of the code inspired by m13253/dns-over-https, missdeer/ipset.

Examples

Redirect all requests to Cloudflare DNS:

dnsredir . {
    to tls://1.1.1.1 tls://1.0.0.1
    tls_servername one.one.one.one

    # Or use domain name directly, which we don't need to specify TLS server name any more
    to tls://one.one.one.one
    # Bootstrap DNS server used to resolve one.one.one.one
    bootstrap 192.168.10.1
}

Redirect all requests to with different upstreams:

dnsredir . {
    # 1.1.1.1 uses the global TLS server name
    # 8.8.8.8 and 9.9.9.9 uses its own TLS server name
    to tls://1.1.1.1 tls://8.8.8.8@dns.google tls://9.9.9.9@quad9.net
    tls_servername cloudflare-dns.com
}

Redirect domains listed in file and fallback to Google DNS:

dnsredir accelerated-domains.china.conf {
    path_reload 3s
    max_fails 0
    to 114.114.114.114 223.5.5.5 udp://119.29.29.29
    policy round_robin

    # INLINE domain
    example.org
    example.net
}

dnsredir google.china.conf apple.china.conf {
    path_reload 10s
    to tls://dns.rubyfish.cn dns://101.6.6.6
    except adservice.google.com doubleclick.net
}

dnsredir . {
    to tls://8.8.8.8@8888.google tls://2001:4860:4860::64@dns.google
    policy sequential
    spray
}

Add resolved domain name IPs in list file to ipset cn4 and cn6:

dnsredir user_custom.conf {
    to 192.168.10.1 192.168.20.1
    ipset cn4 cn6
}

Sample Corefile for dnsredir plugin contain a full-featured Corefile, although it mainly targets for China mainland users, you can also use it as a cross reference to write your own Corefile.

LICENSE

dnsredir uses the same LICENSE as with CoreDNS.