A simple DNS proxy server that supports all existing DNS protocols including
DNS-over-TLS
,DNS-over-HTTPS
,DNSCrypt
,andDNS-over-QUIC
.Moreover,
it can work as aDNS-over-HTTPS
,DNS-over-TLS
orDNS-over-QUIC
server.
There are several options how to installdnsproxy
.
- Grab the binary for your device/OS from theReleasespage.
- Use theofficial Docker image.
- Build it yourself (see the instruction below).
You will need Go v1.21 or later.
$ make build
Usage:
dnsproxy [OPTIONS]
Application Options:
--config-path= yaml configuration file. Minimal working configuration in config.yaml.dist. Options passed through command
line will override the ones from this file.
-o, --output= Path to the log file. If not set, write to stdout.
-c, --tls-crt= Path to a file with the certificate chain
-k, --tls-key= Path to a file with the private key
--https-server-name= Set the Server header for the responses from the HTTPS server. (default: dnsproxy)
--https-userinfo= If set, all DoH queries are required to have this basic authentication information.
-g, --dnscrypt-config= Path to a file with DNSCrypt configuration. You can generate one using https://github /ameshkov/dnscrypt
--edns-addr= Send EDNS Client Address
--upstream-mode= Defines the upstreams logic mode, possible values: load_balance, parallel, fastest_addr (default:
load_balance)
-l, --listen= Listening addresses
-p, --port= Listening ports. Zero value disables TCP and UDP listeners
-s, --https-port= Listening ports for DNS-over-HTTPS
-t, --tls-port= Listening ports for DNS-over-TLS
-q, --quic-port= Listening ports for DNS-over-QUIC
-y, --dnscrypt-port= Listening ports for DNSCrypt
-u, --upstream= An upstream to be used (can be specified multiple times). You can also specify path to a file with the
list of servers
-b, --bootstrap= Bootstrap DNS for DoH and DoT, can be specified multiple times (default: use system-provided)
-f, --fallback= Fallback resolvers to use when regular ones are unavailable, can be specified multiple times. You can also
specify path to a file with the list of servers
--private-rdns-upstream= Private DNS upstreams to use for reverse DNS lookups of private addresses, can be specified multiple times
--dns64-prefix= Prefix used to handle DNS64. If not specified, dnsproxy uses the 'Well-Known Prefix' 64:ff9b::. Can be
specified multiple times
--private-subnets= Private subnets to use for reverse DNS lookups of private addresses
--bogus-nxdomain= Transform the responses containing at least a single IP that matches specified addresses and CIDRs into
NXDOMAIN. Can be specified multiple times.
--hosts-files= List of paths to the hosts files relative to the root, can be specified multiple times
--timeout= Timeout for outbound DNS queries to remote upstream servers in a human-readable form (default: 10s)
--cache-min-ttl= Minimum TTL value for DNS entries, in seconds. Capped at 3600. Artificially extending TTLs should only be
done with careful consideration.
--cache-max-ttl= Maximum TTL value for DNS entries, in seconds.
--cache-size= Cache size (in bytes). Default: 64k
-r, --ratelimit= Ratelimit (requests per second)
--ratelimit-subnet-len-ipv4= Ratelimit subnet length for IPv4. (default: 24)
--ratelimit-subnet-len-ipv6= Ratelimit subnet length for IPv6. (default: 56)
--udp-buf-size= Set the size of the UDP buffer in bytes. A value <= 0 will use the system default.
--max-go-routines= Set the maximum number of go routines. A zero value will not not set a maximum.
--tls-min-version= Minimum TLS version, for example 1.0
--tls-max-version= Maximum TLS version, for example 1.3
--pprof If present, exposes pprof information on localhost:6060.
--version Prints the program version
-v, --verbose Verbose output (optional)
--insecure Disable secure TLS certificate validation
--ipv6-disabled If specified, all AAAA requests will be replied with NoError RCode and empty answer
--http3 Enable HTTP/3 support
--cache-optimistic If specified, optimistic DNS cache is enabled
--cache If specified, DNS cache is enabled
--refuse-any If specified, refuse ANY requests
--edns Use EDNS Client Subnet extension
--dns64 If specified, dnsproxy will act as a DNS64 server
--use-private-rdns If specified, use private upstreams for reverse DNS lookups of private addresses
--hosts-file-enabled= If specified, use hosts files for resolving (default: true)
Help Options:
-h, --help Show this help message
Runs a DNS proxy on0.0.0.0:53
with a single upstream - Google DNS.
./dnsproxy -u 8.8.8.8:53
The same proxy with verbose logging enabled writing it to the filelog.txt
.
./dnsproxy -u 8.8.8.8:53 -v -o log.txt
Runs a DNS proxy on127.0.0.1:5353
with multiple upstreams.
./dnsproxy -l 127.0.0.1 -p 5353 -u 8.8.8.8:53 -u 1.1.1.1:53
Listen on multiple interfaces and ports:
./dnsproxy -l 127.0.0.1 -l 192.168.1.10 -p 5353 -p 5354 -u 1.1.1.1
The plain DNS upstream server may be specified in several ways:
-
With a plain IP address:
./dnsproxy -l 127.0.0.1 -u 8.8.8.8:53
-
With a hostname or plain IP address and the
udp://
scheme:./dnsproxy -l 127.0.0.1 -u udp://dns.google -u udp://1.1.1.1
-
With a hostname or plain IP address and the
tcp://
scheme to force using TCP:./dnsproxy -l 127.0.0.1 -u tcp://dns.google -u tcp://1.1.1.1
DNS-over-TLS upstream:
./dnsproxy -u tls://dns.adguard
DNS-over-HTTPS upstream with specified bootstrap DNS:
./dnsproxy -u https://dns.adguard /dns-query -b 1.1.1.1:53
DNS-over-QUIC upstream:
./dnsproxy -u quic://dns.adguard
DNS-over-HTTPS upstream with enabled HTTP/3 support (chooses it if it's faster):
./dnsproxy -u https://dns.google/dns-query --http3
DNS-over-HTTPS upstream with forced HTTP/3 (no fallback to other protocol):
./dnsproxy -u h3://dns.google/dns-query
DNSCrypt upstream (DNS Stampof AdGuard DNS):
./dnsproxy -u sdns://AQMAAAAAAAAAETk0LjE0MC4xNC4xNDo1NDQzINErR_JS3PLCu_iZEIbq95zkSV2LFsigxDIuUso_OQhzIjIuZG5zY3J5cHQuZGVmYXVsdC5uczEuYWRndWFyZC5jb20
DNS-over-HTTPS upstream (DNS Stampof Cloudflare DNS):
./dnsproxy -u sdns://AgcAAAAAAAAABzEuMC4wLjGgENk8mGSlIfMGXMOlIlCcKvq7AVgcrZxtjon911-ep0cg63Ul-I8NlFj4GplQGb_TTLiczclX57DvMV8Q-JdjgRgSZG5zLmNsb3VkZmxhcmUuY29tCi9kbnMtcXVlcnk
DNS-over-TLS upstream with two fallback servers (to be used when the main upstream is not available):
./dnsproxy -u tls://dns.adguard -f 8.8.8.8:53 -f 1.1.1.1:53
Runs a DNS-over-TLS proxy on127.0.0.1:853
.
./dnsproxy -l 127.0.0.1 --tls-port=853 --tls-crt=example.crt --tls-key=example.key -u 8.8.8.8:53 -p 0
Runs a DNS-over-HTTPS proxy on127.0.0.1:443
.
./dnsproxy -l 127.0.0.1 --https-port=443 --tls-crt=example.crt --tls-key=example.key -u 8.8.8.8:53 -p 0
Runs a DNS-over-HTTPS proxy on127.0.0.1:443
with HTTP/3 support.
./dnsproxy -l 127.0.0.1 --https-port=443 --http3 --tls-crt=example.crt --tls-key=example.key -u 8.8.8.8:53 -p 0
Runs a DNS-over-QUIC proxy on127.0.0.1:853
.
./dnsproxy -l 127.0.0.1 --quic-port=853 --tls-crt=example.crt --tls-key=example.key -u 8.8.8.8:53 -p 0
Runs a DNSCrypt proxy on127.0.0.1:443
.
./dnsproxy -l 127.0.0.1 --dnscrypt-config=./dnscrypt-config.yaml --dnscrypt-port=443 --upstream=8.8.8.8:53 -p 0
Please note that in order to run a DNSCrypt proxy, you need to obtain DNSCrypt configuration first. You can usehttps://github /ameshkov/dnscryptcommand-line tool to do that with a command like this
./dnscrypt generate --provider-name=2.dnscrypt-cert.example.org --out=dnscrypt-config.yaml
Runs a DNS proxy on0.0.0.0:53
with rate limit set to10 rps
,enabled DNS cache, and that refuses type=ANY requests.
./dnsproxy -u 8.8.8.8:53 -r 10 --cache --refuse-any
Runs a DNS proxy on 127.0.0.1:5353 with multiple upstreams and enable parallel queries to all configured upstream servers.
./dnsproxy -l 127.0.0.1 -p 5353 -u 8.8.8.8:53 -u 1.1.1.1:53 -u tls://dns.adguard --upstream-mode parallel
Loads upstreams list from a file.
./dnsproxy -l 127.0.0.1 -p 5353 -u./upstreams.txt
dnsproxy
is capable of working as a DNS64 server.
What is DNS64/NAT64 This is a mechanism of providing IPv6 access to IPv4. Using a NAT64 gateway with IPv4-IPv6 translation capability lets IPv6-only clients connect to IPv4-only services via synthetic IPv6 addresses starting with a prefix that routes them to the NAT64 gateway. DNS64 is a DNS service that returns AAAA records with these synthetic IPv6 addresses for IPv4-only destinations (with A but not AAAA records in the DNS). This lets IPv6-only clients use NAT64 gateways without any other configuration.
See alsoRFC 6147.
Enables DNS64 with the defaultWell-Known Prefix:
./dnsproxy -l 127.0.0.1 -p 5353 -u 8.8.8.8 --use-private-rdns --private-rdns-upstream=127.0.0.1 --dns64
You can also specify any number of custom DNS64 prefixes:
./dnsproxy -l 127.0.0.1 -p 5353 -u 8.8.8.8 --use-private-rdns --private-rdns-upstream=127.0.0.1 --dns64 --dns64-prefix=64:ffff:: --dns64-prefix=32:ffff::
Note that only the first specified prefix will be used for synthesis.
PTR queries for addresses within the specified ranges or the Well-Known onecould only be answered with locally appropriate data, so dnsproxy will route those to the local upstream servers. Those should be specified and enabled if DNS64 is enabled.
This option would be useful to the users with problematic network connection.
In this mode,dnsproxy
would detect the fastest IP address among all that were
returned, and it will return only it.
Additionally, for those with problematic network connection, it makes sense to
overridecache-min-ttl
.In this case,dnsproxy
will make sure that DNS
responses are cached for at least the specified amount of time.
It makes sense to run it with multiple upstream servers only.
Run a DNS proxy with two upstreams, min-TTL set to 10 minutes, fastest address detection is enabled:
./dnsproxy -u 8.8.8.8 -u 1.1.1.1 --cache --cache-min-ttl=600 --upstream-mode=fastest_addr
who rundnsproxy
with multiple upstreams
You can specify upstreams that will be used for a specific domain(s). We use the
dnsmasq-like syntax, decorating domains with brackets (see--server
description).
Syntax:[/[domain1][/../domainN]/]upstreamString
WhereupstreamString
is one or many upstreams separated by space (e.g.
1.1.1.1
or1.1.1.1 2.2.2.2
).
If one or more domains are specified, that upstream (upstreamString
) is used
only for those domains. Usually, it is used for private nameservers. For
instance, if you have a nameserver on your network which deals with
xxx.internal.local
at192.168.0.1
then you can specify
[/internal.local/]192.168.0.1
,and dnsproxy will send all queries to that
nameserver. Everything else will be sent to the default upstreams (which are
mandatory!).
- An empty domain specification,
//
has the special meaning of "unqualified names only", which will be used to resolve names with a single label in them, or with exactly two labels in case ofDS
requests. - More specific domains take precedence over less specific domains, so:
--upstream=[/host /]1.2.3.4 --upstream=[/ host /]2.3.4.5
will send queries for*.host
to1.2.3.4
,except*. host
,which will go to2.3.4.5
. - The special server address
#
means, "use the common servers", so:--upstream=[/host /]1.2.3.4 --upstream=[/ host /]#
will send queries for*.host
to1.2.3.4
,except*. host
which will be forwarded as usual. - The wildcard
*
has special meaning of "any sub-domain", so:--upstream=[/*.host /]1.2.3.4
will send queries for*.host
to1.2.3.4
,buthost
will be forwarded to default upstreams.
Examples
Sends requests for*.local
domains to192.168.0.1:53
.Other requests are
sent to8.8.8.8:53
:
./dnsproxy\
-u"8.8.8.8:53"\
-u"[/local/]192.168.0.1:53"
Sends requests for*.host
to1.1.1.1:53
except for*.maps.host
which are sent to8.8.8.8:53
(along with other requests):
./dnsproxy\
-u"8.8.8.8:53"\
-u"[/host /]1.1.1.1:53"\
-u"[/maps.host /]#"
Sends requests for*.host
to1.1.1.1:53
except forhost
which is
sent to9.9.9.10:53
,and all other requests are sent to8.8.8.8:53
:
./dnsproxy\
-u"8.8.8.8:53"\
-u"[/host /]9.9.9.10:53"\
-u"[/*.host /]1.1.1.1:53"
Sends requests forcom
(and its subdomains) to1.2.3.4:53
,requests for
other top-level domains to1.1.1.1:53
,and all other requests to8.8.8.8:53
:
./dnsproxy\
-u"8.8.8.8:53"\
-u"[//]1.1.1.1:53"\
-u"[/com/]1.2.3.4:53"
You can specify upstreams that will be used for reverse DNS requests of type PTR
for private addresses. Same applies to the authority requests of types SOA and
NS. The set of private addresses is defined by the--private-rdns-upstream
,
and the set fromRFC 6303is used by default.
The additional requirement to the domains specified for upstreams is to be
in-addr.arpa
,ip6.arpa
,or its subdomain. Addresses encoded in the domains
should also be private.
Examples
Sends queries for*.168.192.in-addr.arpa
to192.168.1.2
,if requested by
client from192.168.0.0/16
subnet. Other queries answered withNXDOMAIN
:
./dnsproxy\
-l"0.0.0.0"\
-u"8.8.8.8"\
--use-private-rdns\
--private-subnets="192.168.0.0/16"
--private-rdns-upstream="192.168.1.2"\
Sends queries for*.in-addr.arpa
to192.168.1.2
,*.ip6.arpa
tofe80::1
,
if requested by client within the defaultRFC 6303subnet set. Other
queries answered withNXDOMAIN
:
./dnsproxy\
-l"0.0.0.0"\
-u 8.8.8.8\
--use-private-rdns\
--private-rdns-upstream="192.168.1.2"\
--private-rdns-upstream="[/ip6.arpa/]fe80::1"
To enable support for EDNS Client Subnet extension you should run dnsproxy with--edns
flag:
./dnsproxy -u 8.8.8.8:53 --edns
Now if you connect to the proxy from the Internet - it will pass through your original IP address's prefix to the upstream server. This way the upstream server may respond with IP addresses of the servers that are located near you to minimize latency.
If you want to use EDNS CS feature when you're connecting to the proxy from a local network, you need to set--edns-addr=PUBLIC_IP
argument:
./dnsproxy -u 8.8.8.8:53 --edns --edns-addr=72.72.72.72
Now even if your IP address is 192.168.0.1 and it's not a public IP, the proxy will pass through 72.72.72.72 to the upstream server.
This option is similar to dnsmasqbogus-nxdomain
.dnsproxy
will transform
responses that contain at least a single IP address which is also specified by
the option intoNXDOMAIN
.Can be specified multiple times.
In the example below, we use AdGuard DNS server that returns0.0.0.0
for
blocked domains, and transform them toNXDOMAIN
.
./dnsproxy -u 94.140.14.14:53 --bogus-nxdomain=0.0.0.0
CIDR ranges are supported as well. The following will respond withNXDOMAIN
instead of responses containing any IP from192.168.0.0
-192.168.255.255
:
./dnsproxy -u 192.168.0.15:53 --bogus-nxdomain=192.168.0.0/16
By setting the--https-userinfo
option you can usednsproxy
as a DoH proxy
with basic authentication requirements.
For example:
./dnsproxy\
--https-port='443'\
--https-userinfo='user:p4ssw0rd'\
--tls-crt='…/my.crt'\
--tls-key='…/my.key'\
-u'94.140.14.14:53'
This configuration will only allow DoH queries that contain anAuthorization
header containing the BasicAuth credentials for useruser
with password
p4ssw0rd
.
Add-p 0
if you also want to disable plain-DNS handling and makednsproxy
only serve DoH with Basic Auth checking.