Skip to content
This repository has been archived by the owner on Aug 3, 2021. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

DNS Over HTTPS Proxy

Test Code Base GitHub Super-Linter PyPI version

A set of python 3 scripts that supports proxying DNS over HTTPS as specified in the IETF Draft draft-ietf-doh-dns-over-https.

DOH provides a way to run encrypted DNS over HTTPS, a protocol which can freely traverse firewalls when other encrypted mechanism may be blocked.

The project comes with a set of 4 tools:

  • doh-proxy: A service that receives DOH queries over HTTP2 and forwards them to a recursive resolver.
  • doh-httpproxy: Like doh-proxy but uses HTTP instead of HTTP2. The main intent is to run this behind a reverse proxy.
  • doh-stub: A service that listens for DNS queries and forwards them to a DOH server.
  • doh-client: A tool to perform a test DNS query against DOH server.

See the CONTRIBUTING file for how to help out.

DOH Proxy was created during IETF Hackathon 100 as a proof-of-concept and is not used at Facebook.

You are welcome to use it, but be aware that support is limited and best-effort.


To install an already packaged version directly from PyPi:

$ pip3 install doh-proxy



doh-proxy is a stand alone server answering DOH request. The proxy does not do DNS recursion itself and rather forward the query to a full-featured DNS recursive server or DNS caching server.

By running doh-proxy, you can get and end-to-end DOH solution with minimal setup.

$ sudo doh-proxy \
    --upstream-resolver=::1 \
    --certfile=./fullchain.pem \


doh-httpproxy is designed to be running behind a reverse proxy. In this setup a reverse proxy such as NGINX would be handling the HTTPS/HTTP2 requests from the DOH clients and will forward them to doh-httpproxy backends.

While this setup requires more upfront setup, it allows running DOH proxy unprivileged and on multiple cores.

$ doh-httpproxy \
    --upstream-resolver=::1 \
    --port 8080 \
    --listen-address ::1

doh-httpproxy now also supports TLS, that you can enable passing the args --certfile and --keyfile (just like doh-proxy)


doh-stub is the piece of software that you would run on the clients. By providing a local DNS server, doh-stub will forward the DNS requests it receives to a DOH server using an encrypted link.

You can start a stub resolver with:

$ doh-stub \
    --listen-port 5553 \
    --listen-address ::1 \
    --domain \
    --remote-address ::1

and query it.

$ dig @::1 -p 5553


doh-client is just a test cli that can be used to quickly send a request to a DOH server and dump the returned answer.

$ doh-client  \
    --domain \
    --qname \
id 37762
opcode QUERY
flags QR RD RA
edns 0
eflags DO
payload 4096

$ doh-client  \
    --domain \
    --qname \
id 49772
opcode QUERY
flags QR RD RA AD
edns 0
eflags DO
payload 4096
;ANSWER 60 IN AAAA 2001:638:501:8efc::139 60 IN RRSIG AAAA 5 3 60 20180130030002 20171031030002 30665 O7QgNZFBu3fULvBXwM39apv5nMehh51f mLOVEsC8qZUyxIbxo4eDLQt0JvPoPpFH 5TbWdlm/jxq5x2/Kjw7yUdpohhiNmdoD Op7Y+RyHbf676FoC5Zko9uOAB7Pp8ERz qiT0QPt1ec12bM0XKQigfp+2Hy9wUuSN QmAzXS2s75k=



  • python >= 3.5
  • aiohttp
  • aioh2
  • dnspython


DOH Proxy uses Python'setuptools to manage dependencies and build.

To install its dependencies:

$ python3 develop
# Due to GH #63
$ pip install git+

To build:

$ python3 build

To run unittests:

$ python3 test

To run the linter:

DOH Proxy uses GitHub Action Super-Linter to lint the code. In order to validate your code locally, it is possible to run Super-Linter locally using the following comand line from within the repository:

docker run -e RUN_LOCAL=true  -e VALIDATE_PYTHON_PYLINT=false \
    -e FILTER_REGX_INCLUDE='(dohproxy|test)/.*.py' \
    -v $(pwd):/tmp/lint \
     --rm github/super-linter:v3

From within the root of the repository, you can test the proxy, stub and client respectively by using the following commands:

$ sudo PYTHONPATH=. ./dohproxy/ ...
$ PYTHONPATH=. ./dohproxy/ ...
$ PYTHONPATH=. ./dohproxy/ ...
$ PYTHONPATH=. ./dohproxy/ ...


DOH Proxy is BSD-licensed.