Need help with https_dns_proxy?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

557 Stars 92 Forks MIT License 217 Commits 4 Opened issues


A lightweight DNS-over-HTTPS proxy.

Services available


Need anything else?

Contributors list


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.64.0)
libev (>=4.25)

On Debian-derived systems those are libc-ares-dev, libcurl4-{openssl,nss,gnutls}-dev and libev-dev respectively. On Redhat-derived systems those are c-ares-devel, libcurl-devel and libev-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


Install built program

This method work fine on most Linux operating system, which uses systemd.
Like: Raspberry Pi OS / Raspbian, Debian, Ubuntu, etc.

To install the program binary and systemd service, simply execute the following after build:

$ sudo make install

To overwrite default options use:

$ sudo systemctl edit https_dns_proxy.service
And re-define ExecStart with desired options:
ExecStart=/usr/local/bin/https_dns_proxy \
  -u nobody -g nogroup -r

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

Docker install

There is also an externally maintained Docker image for latest git version. Documentation, Dockerfile, and entrypoint script can be viewed on GitHub. An example run:

### points towards AdGuard DNS, only use IPv4, increase logging ###

docker run --name "https-dns-proxy" -p 5053:5053/udp
-d bwmoran/https-dns-proxy
-4 -vvv


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 ] -c 
        [-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 []. (,,,,,, -i polling_interval Optional polling interval of DNS servers. (Default: 120, Min: 5, Max: 3600) -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. -l logfile Path to file to log to. ("-") -c dscp_codepoint Optional DSCP codepoint[0-63] to set on upstream DNS server connections. -x Use HTTP/1.1 instead of HTTP/2. Useful with broken or limited builds of libcurl. (false) -v Increase logging verbosity. (INFO) -V Print version and exit.


  • 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.