• Stars
    star
    1,791
  • Rank 25,940 (Top 0.6 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created almost 6 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Simple DNS proxy with DoH, DoT, DoQ and DNSCrypt support

Code Coverage Go Report Card Go Doc

DNS Proxy

A simple DNS proxy server that supports all existing DNS protocols including DNS-over-TLS, DNS-over-HTTPS, DNSCrypt, and DNS-over-QUIC. Moreover, it can work as a DNS-over-HTTPS, DNS-over-TLS or DNS-over-QUIC server.

How to install

There are several options how to install dnsproxy.

  1. Grab the binary for your device/OS from the Releases page.
  2. Use the official Docker image.
  3. Build it yourself (see the instruction below).

How to build

You will need Go v1.21 or later.

$ make build

Usage

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.com/ameshkov/dnscrypt
      --edns-addr=                 Send EDNS Client Address
  -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.
      --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
      --all-servers                If specified, parallel queries to all configured upstream servers are enabled
      --fastest-addr               Respond to A or AAAA requests only with the fastest IP address
      --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

Help Options:
  -h, --help                       Show this help message

Examples

Simple options

Runs a DNS proxy on 0.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 file log.txt.

./dnsproxy -u 8.8.8.8:53 -v -o log.txt

Runs a DNS proxy on 127.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

Encrypted upstreams

DNS-over-TLS upstream:

./dnsproxy -u tls://dns.adguard.com

DNS-over-HTTPS upstream with specified bootstrap DNS:

./dnsproxy -u https://dns.adguard.com/dns-query -b 1.1.1.1:53

DNS-over-QUIC upstream:

./dnsproxy -u quic://dns.adguard.com

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 Stamp of AdGuard DNS):

./dnsproxy -u sdns://AQIAAAAAAAAAFDE3Ni4xMDMuMTMwLjEzMDo1NDQzINErR_JS3PLCu_iZEIbq95zkSV2LFsigxDIuUso_OQhzIjIuZG5zY3J5cHQuZGVmYXVsdC5uczEuYWRndWFyZC5jb20

DNS-over-HTTPS upstream (DNS Stamp of 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.com -f 8.8.8.8:53 -f 1.1.1.1:53

Encrypted DNS server

Runs a DNS-over-TLS proxy on 127.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 on 127.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 on 127.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 on 127.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 on 127.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 use https://github.com/ameshkov/dnscrypt command-line tool to do that with a command like this ./dnscrypt generate --provider-name=2.dnscrypt-cert.example.org --out=dnscrypt-config.yaml

Additional features

Runs a DNS proxy on 0.0.0.0:53 with rate limit set to 10 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.com --all-servers

Loads upstreams list from a file.

./dnsproxy -l 127.0.0.1 -p 5353 -u ./upstreams.txt

DNS64 server

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 also RFC 6147.

Enables DNS64 with the default Well-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 one could 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.

Fastest addr + cache-min-ttl

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 override cache-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 --fastest-addr

who run dnsproxy with multiple upstreams

Specifying upstreams for domains

You can specify upstreams that will be used for a specific domain(s). We use the dnsmasq-like syntax (see --server description here).

Syntax: [/[domain1][/../domainN]/]upstreamString

Where upstreamString is one or many upstreams separated by space (e.g. 1.1.1.1 or 1.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 at 192.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!).

  1. An empty domain specification, // has the special meaning of "unqualified names only" ie names without any dots in them.
  2. More specific domains take precedence over less specific domains, so: --upstream=[/host.com/]1.2.3.4 --upstream=[/www.host.com/]2.3.4.5 will send queries for *.host.com to 1.2.3.4, except *.www.host.com, which will go to 2.3.4.5
  3. The special server address # means, "use the standard servers", so: --upstream=[/host.com/]1.2.3.4 --upstream=[/www.host.com/]# will send queries for *.host.com to 1.2.3.4, except *.www.host.com which will be forwarded as usual.
  4. The wildcard * has special meaning of "any sub-domain", so: --upstream=[/*.host.com/]1.2.3.4 will send queries for *.host.com to 1.2.3.4, but host.com will be forwarded to default upstreams.

Examples

Sends queries for *.local domains to 192.168.0.1:53. Other queries are sent to 8.8.8.8:53.

./dnsproxy -u 8.8.8.8:53 -u [/local/]192.168.0.1:53

Sends queries for *.host.com to 1.1.1.1:53 except for *.maps.host.com which are sent to 8.8.8.8:53 (along with other queries).

./dnsproxy -u 8.8.8.8:53 -u [/host.com/]1.1.1.1:53 -u [/maps.host.com/]#

Sends queries for *.host.com to 1.1.1.1:53 except for host.com which is sent to 8.8.8.8:53 (along with other queries).

./dnsproxy -u 8.8.8.8:53 -u [/*.host.com/]1.1.1.1:53

Specifying private rDNS upstreams

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 from RFC 6303 is 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 to 192.168.1.2, if requested by client from 192.168.0.0/16 subnet. Other queries answered with NXDOMAIN.

./dnsproxy -l 192.168.1.1 -p 53 -u 8.8.8.8 --use-private-rdns --private-rdns-upstream="192.168.1.2" --private-subnets="192.168.0.0/16"

Sends queries for *.in-addr.arpa to 192.168.1.2, *.ip6.arpa to fe80::1, if requested by client within the default RFC 6303 subnet set. Other queries answered with NXDOMAIN.

./dnsproxy -l 192.168.1.1 -p 53 -u 8.8.8.8 --use-private-rdns --private-rdns-upstream="192.168.1.2" --private-rdns-upstream="[/ip6.arpa/]fe80::1"

EDNS Client Subnet

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.

Bogus NXDomain

This option is similar to dnsmasq bogus-nxdomain. dnsproxy will transform responses that contain at least a single IP address which is also specified by the option into NXDOMAIN. Can be specified multiple times.

In the example below, we use AdGuard DNS server that returns 0.0.0.0 for blocked domains, and transform them to NXDOMAIN.

./dnsproxy -u 94.140.14.14:53 --bogus-nxdomain=0.0.0.0

CIDR ranges are supported as well. The following will respond with NXDOMAIN instead of responses containing any IP from 192.168.0.0-192.168.255.255:

./dnsproxy -u 192.168.0.15:53 --bogus-nxdomain=192.168.0.0/16

Basic Auth for DoH

By setting the --https-userinfo option you can use dnsproxy 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 an Authorization header containing the BasicAuth credentials for user user with password p4ssw0rd.

Add -p 0 if you also want to disable plain-DNS handling and make dnsproxy only serve DoH with Basic Auth checking.

More Repositories

1

AdGuardHome

Network-wide ads & trackers blocking DNS server
Go
18,381
star
2

AdguardBrowserExtension

AdGuard browser extension
JavaScript
2,427
star
3

AdguardFilters

AdGuard Content Blocking Filters
Adblock Filter List
2,331
star
4

AdguardForiOS

The most advanced ad blocker for iOS
JavaScript
1,289
star
5

AdguardForAndroid

Open bug tracker for Android version of AdGuard.
1,060
star
6

AdGuardForSafari

AdGuard for Safari app extension
JavaScript
875
star
7

AdGuardDNS

Public DNS resolver that protects you from ad trackers
Go
634
star
8

AdguardForWindows

AdGuard for Windows open bug tracker
568
star
9

AdGuardSDNSFilter

AdGuard Simplified Domain names filter
Adblock Filter List
491
star
10

ContentBlocker

Content blocking extension for Samsung Internet and Yandex Browser
Java
402
star
11

cname-trackers

This repository contains a list of popular CNAME trackers
JavaScript
334
star
12

AdGuardExtra

AdGuard Extra is designed to solve complicated cases when regular ad blocking rules aren't enough.
270
star
13

AdguardForMac

Open bug tracker for Mac version of AdGuard
269
star
14

PopupBlocker

Popup blocking userscript
TypeScript
220
star
15

gomitmproxy

Simple golang mitm proxy implementation
Go
155
star
16

FiltersRegistry

Known filters subscriptions transformed for better compatibility with AdGuard
Adblock Filter List
152
star
17

AdguardKnowledgeBase

Adguard Knowledge Base
140
star
18

AdGuardMV3

AdGuard browser extension prototype based on the new Manifest V3
TypeScript
121
star
19

HostlistsRegistry

Known hosts blocklists that are made available to the users of AdGuard products
JavaScript
113
star
20

AdguardAssistant

Adguard Assistant userscript
JavaScript
110
star
21

Scriptlets

AdGuard scriptlets library
JavaScript
109
star
22

HostlistCompiler

A simple tool that compiles hosts blocklists from multiple sources
JavaScript
95
star
23

BlockYouTubeAdsShortcut

This repo contains the code for blocking YouTube ads that is supposed to be run by an iOS shortcut
JavaScript
85
star
24

AdGuardVPNForAndroid

AdGuard VPN Android app open bug tracker
81
star
25

DisableAMP

Disable AMP userscript
JavaScript
76
star
26

DnsLibs

DNS filtering library
C++
75
star
27

urlfilter

AdGuard content blocking library in golang
Go
71
star
28

AdGuardVPNExtension

AdGuard VPN Chrome and Firefox extension
TypeScript
57
star
29

AnonymousRedirect

Very simple HTML page that is used for anonymous redirect
HTML
55
star
30

ExtendedCss

A TypeScript library for non-standard element selecting — :contains(), :matches-css(), etc., and applying CSS styles with extended properties.
TypeScript
54
star
31

HttpsExclusions

Centralized repo for HTTPS exclusions
JavaScript
48
star
32

KnowledgeBaseDNS

AdGuard DNS knowledge base
JavaScript
47
star
33

StealthMode

JavaScript
46
star
34

Userscripts

Userscripts made by our team
JavaScript
42
star
35

AdGuardVPNForWindows

AdGuard VPN Windows app open bug tracker
39
star
36

VscodeAdblockSyntax

TM language plugin with ad blocking rules syntax
37
star
37

FiltersCompiler

A tool that compiles & validates filters
JavaScript
36
star
38

tsurlfilter

AdGuard content blocking library
TypeScript
35
star
39

CoreLibs

Core Adguard libraries
33
star
40

BrowserAssistant

AdGuard Browser Assistant
JavaScript
33
star
41

AGLint

Universal adblock filter list parser, linter and converter
TypeScript
28
star
42

KnowledgeBase

AdGuard knowledge base
JavaScript
26
star
43

AdGuardVPNForiOS

AdGuard VPN iOS app open bug tracker
25
star
44

SafariConverterLib

Swift library that converts AdGuard rules to Safari content blocking rules
Swift
21
star
45

AdGuardVPNForMac

AdGuard VPN Mac app open bug tracker
21
star
46

AdguardTeam.github.io

HTML
17
star
47

companiesdb

This is a companies DB that we use in AdGuard Home and AdGuard DNS.
JavaScript
16
star
48

ProxiesSetup

A simple script that sets up an HTTP and a SOCKS5 proxy (squid and danted)
Shell
16
star
49

WebBatteryTester

This application allows you to test how quick is your battery drained by web-browsing.
Java
14
star
50

golibs

Small helper Go libraries
Go
13
star
51

SafariConverter

Converter: ad blocking rules -> safari content blocker
JavaScript
12
star
52

deep-override

TypeScript
10
star
53

VerificationLibrary

Certificates verification library
C
9
star
54

go-webext

Automation for working with extension stores
Go
9
star
55

FiltersDownloader

Pre-processing library for filters subscriptions
JavaScript
9
star
56

translate

Simple internationalization library with react integration
TypeScript
8
star
57

AdGuardFiltersStats

The repo where we collect AdguardFilters statistics
JavaScript
8
star
58

ecsstree

Adblock Extended CSS supplement for CSSTree
JavaScript
7
star
59

ReportsWebApp

Allows users to report a problem with Adguard filters
JavaScript
7
star
60

NativeLibsCommon

Native libs common
C++
6
star
61

Recovery

JavaScript
5
star
62

VpnLibs

Open bug tracker for AdGuard VPN core library
5
star
63

KnowledgeBaseVPN

AdGuard VPN knowledge base
JavaScript
5
star
64

AdGuardVpnKnowledgeBase

AdGuard VPN Knowledge Base
5
star
65

LegalDocs

AdGuard's legal documents
4
star
66

SafariContentBlockerTester

Utility Safari extension for content blocker format testing.
JavaScript
4
star
67

TestCases

Used for testing puproses
JavaScript
3
star
68

SafariContentBlockerConverterCompiler

Utility scripts for building safari content blocker converter.
JavaScript
3
star
69

github-stats

Tool for calculating AdguardFilters contributors statistics
JavaScript
3
star
70

DeadDomainsLinter

Simple tool to check adblock filtering rules for dead domains.
JavaScript
2
star
71

AdGuardVPNCLI

AdGuard VPN command-line version
2
star
72

AdGuardDNSClient

Client tool for AdGuard DNS
Go
2
star
73

closure-tools-helper

TypeScript
1
star
74

dns-sde-extension

Proof-of-concept browser extension for Structured DNS errors
1
star