by aarond10

A lightweight DNS-over-HTTPS proxy.

506 Stars 84 Forks Last release: Not found MIT License 163 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:


is a light-weight DNS<-->HTTPS, non-caching translation proxy for the RFC 8484 DNS-over-HTTPS standard. It receives regular (UDP) DNS requests and issues them via DoH.

Google's DNS-over-HTTPS service is default, but Cloudflare's service also works with trivial commandline flag changes.

Using Google

# ./https_dns_proxy -u nobody -g nogroup -d -b, \
    -r ""

Using Cloudflare

# ./https_dns_proxy -u nobody -g nogroup -d -b, \
    -r ""


Using DNS over HTTPS makes eavesdropping and spoofing of DNS traffic between you and the HTTPS DNS provider (Google/Cloudflare) much less likely. This of course only makes sense if you trust your DoH provider.


  • Tiny Size (<30kiB).
  • Uses curl for HTTP/2 and pipelining, keeping resolve latencies extremely low.
  • Single-threaded, non-blocking select() server for use on resource-starved embedded systems.
  • Designed to sit in front of dnsmasq or similar caching resolver for transparent use.


Depends on

c-ares (>=1.11.0)
libcurl (>=7.66.0)
libev (>=4.25)

On Debian-derived systems those are libc-ares-dev, libcurl4-{openssl,nss,gnutls}-dev, libev-dev and libgtest-dev respectively. On Redhat-derived systems those are c-ares-devel, libcurl-devel, libev-devel and gtest-devel, .

On MacOS, you may run into issues with curl headers. Others have had success when first installing curl with brew.

brew install curl --with-openssl --with-c-ares --with-libssh2 --with-nghttp2 --with-gssapi --with-libmetalink
brew link curl --force

On Ubuntu

apt-get install cmake libc-ares-dev libcurl4-openssl-dev libev-dev build-essential

If all pre-requisites are met, you should be able to build with:

$ cmake .
$ make


There is no installer at this stage - just run it.

OpenWRT package install

There is a package in the OpenWRT packages repository as well. You can install as follows:

[email protected]:~# opkg update
[email protected]:~# opkg install https-dns-proxy
[email protected]:~# /etc/init.d/https-dns-proxy enable
[email protected]:~# /etc/init.d/https-dns-proxy start

OpenWrt's init script automatically updates the

config to include only DoH servers on its start and restores old settings on stop. Additional information on OpenWrt-specific configuration is available at the README.

If you are using any other resolver on your router you will need to manually replace any previously used servers with entries like:

You may also want to prevent your resolver from using /etc/resolv.conf DNS servers, leaving only our proxy server.

There's also a WebUI package available for OpenWrt (

) which contains the list of supported and tested DoH providers.

archlinux package install

There is also an externally maintained AUR package for latest git version. You can install as follows:

[email protected]:~# yaourt -S https-dns-proxy-git


Just run it as a daemon and point traffic at it. Commandline flags are:

Usage: ./https_dns_proxy [-a ] [-p ]
        [-d] [-u ] [-g ] [-b ]
        [-r ] [-e ]
        [-t ] [-l ] [-x] [-v]+

-a listen_addr Local IPv4/v6 address to bind to. ( -p listen_port Local port to bind to. (5053) -d Daemonize. -u user Optional user to drop to if launched as root. -g group Optional group to drop to if launched as root. -b dns_servers Comma-separated IPv4/v6 addresses and ports (addr:port) of DNS servers to resolve resolver host (e.g. When specifying a port for IPv6, enclose the address in []. (,,,,,, -4 Force IPv4 hostnames for DNS resolvers non IPv6 networks. -r resolver_url The HTTPS path to the resolver URL. default: -t proxy_server Optional HTTP proxy. e.g. socks5:// Remote name resolution will be used if the protocol supports it (http, https, socks4a, socks5h), otherwise initial DNS resolution will still be done via the bootstrap DNS servers. -c dscp_codepoint Optional DSCP codepoint[0-63] to set on upstream DNS server connections. -l logfile Path to file to log to. ("-") -x Use HTTP/1.1 instead of HTTP/2. Useful with broken or limited builds of libcurl. (false) -v Increase logging verbosity. (INFO)


  • Add some tests.


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.