{"id":13582492,"url":"https://github.com/m13253/dns-over-https","last_synced_at":"2025-05-13T21:08:04.781Z","repository":{"id":38420425,"uuid":"103812428","full_name":"m13253/dns-over-https","owner":"m13253","description":"High performance DNS over HTTPS client \u0026 server","archived":false,"fork":false,"pushed_at":"2025-03-29T00:03:06.000Z","size":400,"stargazers_count":2073,"open_issues_count":12,"forks_count":230,"subscribers_count":68,"default_branch":"master","last_synced_at":"2025-04-28T12:15:42.412Z","etag":null,"topics":["dns","dns-over-https","doh","google-dns","ietf-doh","rfc-8484"],"latest_commit_sha":null,"homepage":"https://developers.google.com/speed/public-dns/docs/dns-over-https","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m13253.png","metadata":{"files":{"readme":"Readme.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-17T07:55:31.000Z","updated_at":"2025-04-27T14:44:46.000Z","dependencies_parsed_at":"2024-01-08T21:40:52.484Z","dependency_job_id":"5193e669-6f08-4412-9728-3765bf953065","html_url":"https://github.com/m13253/dns-over-https","commit_stats":{"total_commits":320,"total_committers":33,"mean_commits":9.696969696969697,"dds":"0.40312499999999996","last_synced_commit":"72be4857a327d249b6c60dc09fa7014054cd3b90"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m13253%2Fdns-over-https","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m13253%2Fdns-over-https/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m13253%2Fdns-over-https/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m13253%2Fdns-over-https/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m13253","download_url":"https://codeload.github.com/m13253/dns-over-https/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251311334,"owners_count":21569009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dns","dns-over-https","doh","google-dns","ietf-doh","rfc-8484"],"created_at":"2024-08-01T15:02:46.094Z","updated_at":"2025-04-28T12:15:50.000Z","avatar_url":"https://github.com/m13253.png","language":"Go","readme":"DNS-over-HTTPS\n==============\n\nClient and server software to query DNS over HTTPS, using [Google DNS-over-HTTPS protocol](https://developers.google.com/speed/public-dns/docs/dns-over-https)\nand [IETF DNS-over-HTTPS (RFC 8484)](https://www.rfc-editor.org/rfc/rfc8484.txt).\n\n## Guides\n\n- [Tutorial: Setup your own DNS-over-HTTPS (DoH) server](https://www.aaflalo.me/2018/10/tutorial-setup-dns-over-https-server/). (Thanks to Antoine Aflalo)\n- [Tutorial: Setup your own Docker based DNS-over-HTTPS (DoH) server](https://github.com/satishweb/docker-doh/blob/master/README.md). (Thanks to Satish Gaikwad)\n\n## Installing\n### From Source\n- Install [Go](https://golang.org), at least version 1.20. The newer, the better.\n\u003e Note for Debian/Ubuntu users: You need to set `$GOROOT` if you could not get your new version of Go selected by the Makefile.\n\n- First create an empty directory, used for `$GOPATH`:\n```bash\nmkdir ~/gopath\nexport GOPATH=~/gopath\n```\n- To build the program, type:\n```bash\nmake\n```\n- To install DNS-over-HTTPS as Systemd services, type:\n```bash\nsudo make install\n```\n- By default, [Google DNS over HTTPS](https://dns.google.com) is used. It should\nwork for most users (except for People's Republic of China). If you need to\nmodify the default settings, type:\n```bash\nsudoedit /etc/dns-over-https/doh-client.conf\n```\n- To automatically start DNS-over-HTTPS client as a system service, type:\n```bash\nsudo systemctl start doh-client.service\nsudo systemctl enable doh-client.service\n```\n- Then, modify your DNS settings (usually with NetworkManager) to 127.0.0.1.\n\n- To test your configuration, type:\n```bash\ndig www.google.com\nOutput:\n;; SERVER: 127.0.0.1#53(127.0.0.1)\n```\n#### Uninstall\n\n- To uninstall, type:\n```bash\nsudo make uninstall\n```\n\u003e Note: The configuration files are kept at `/etc/dns-over-https`. Remove them manually if you want.\n\n### Using docker image\n```bash\ndocker run -d --name doh-server \\\n  -p 8053:8053 \\\n  -e UPSTREAM_DNS_SERVER=\"udp:208.67.222.222:53,udp:208.67.220.220:53\" \\\n  -e DOH_HTTP_PREFIX=\"/dns-query\" \\\n  -e DOH_SERVER_LISTEN=\":8053\" \\\n  -e DOH_SERVER_TIMEOUT=\"10\" \\\n  -e DOH_SERVER_TRIES=\"3\" \\\n  -e DOH_SERVER_VERBOSE=\"false\" \\\n  satishweb/doh-server\n```\nNote: Multiple Upstream DNS server support was added in the container image on 2024-12-19.\n\nFeeling adventurous? Try the latest build:\n\n- `m13253/dns-over-https-server:latest`\n- `m13253/dns-over-https-client:latest`\n\n## Logging\n\nAll log lines (by either doh-client or doh-server) are written into `stderr`; you can view them using your OS tool of choice (`journalctl` when using systemd).\n\n## Server Configuration\n\nThe following is a typical DNS-over-HTTPS architecture:\n\n    +--------------+                                +------------------------+\n    | Application  |                                |  Recursive DNS Server  |\n    +-------+------+                                +-----------+------------+\n            |                                                   |\n    +-------+------+                                +-----------+------------+\n    | Client side  |                                |      doh-server        |\n    | cache (nscd) |                                +-----------+------------+\n    +-------+------+                                            |\n            |         +--------------------------+  +-----------+------------+\n    +-------+------+  |    HTTP cache server /   |  |   HTTP service muxer   |\n    |  doh-client  +--+ Content Delivery Network +--+ (Apache, Nginx, Caddy) |\n    +--------------+  +--------------------------+  +------------------------+\n\nAlthough DNS-over-HTTPS can work alone, an HTTP service muxer would be useful as\nyou can host DNS-over-HTTPS along with other HTTPS services.\n\nHTTP/2 with at least TLS v1.3 is recommended. OCSP stapling must be enabled,\notherwise DNS recursion may happen.\n\n### Configuration file\n\nThe main configuration file is `doh-client.conf`.\n\n**Server selectors.** If several upstream servers are set, one is selected according to `upstream_selector` for each request. With `upstream_selector = \"random\"`, a random upstream server will be chosen for each request.\n\n```toml\n# available selector: random (default) or weighted_round_robin or lvs_weighted_round_robin\nupstream_selector = \"random\"\n```\n\n### Example configuration: Apache\n```bash\nSSLProtocol TLSv1.2\nSSLHonorCipherOrder On\nSSLCipherSuite ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+3DES:!aNULL:!MD5:!DSS:!eNULL:!EXP:!LOW:!MD5\nSSLUseStapling on\nSSLStaplingCache shmcb:/var/lib/apache2/stapling_cache(512000)\n\n\u003cVirtualHost *:443\u003e\n    ServerName MY_SERVER_NAME\n    Protocols h2 http/1.1\n    ProxyPass /dns-query http://[::1]:8053/dns-query\n    ProxyPassReverse /dns-query http://[::1]:8053/dns-query\n\u003c/VirtualHost\u003e\n```\n(Credit: [Joan Moreau](https://github.com/m13253/dns-over-https/issues/51#issuecomment-526820884))\n\n### Example configuration: Nginx\n```bash\nserver {\n  listen       443 ssl http2 default_server;\n  listen       [::]:443 ssl http2 default_server;\n  server_name  MY_SERVER_NAME;\n\n  server_tokens off;\n\n  ssl_protocols TLSv1.2 TLSv1.3;          # TLS 1.3 requires nginx \u003e= 1.20.0\n  ssl_prefer_server_ciphers on;\n  ssl_dhparam /etc/nginx/dhparam.pem;     # openssl dhparam -dsaparam -out /etc/nginx/dhparam.pem 4096\n  ssl_ciphers EECDH+AESGCM:EDH+AESGCM;\n  ssl_ecdh_curve secp384r1;               # Requires nginx \u003e= 1.1.0\n  ssl_session_timeout  10m;\n  ssl_session_cache shared:SSL:10m;\n  ssl_session_tickets off;                # Requires nginx \u003e= 1.5.9\n  ssl_stapling on;                        # Requires nginx \u003e= 1.3.7\n  ssl_stapling_verify on;                 # Requires nginx =\u003e 1.3.7\n  ssl_early_data off;                     # 0-RTT, enable if desired - Requires nginx \u003e= 1.15.4\n  resolver 1.1.1.1 valid=300s;            # Replace with your local resolver\n  resolver_timeout 5s;\n  # HTTP Security Headers\n  add_header X-Frame-Options DENY;\n  add_header X-Content-Type-Options nosniff;\n  add_header X-XSS-Protection \"1; mode=block\";\n  add_header Strict-Transport-Security \"max-age=63072000\";\n  ssl_certificate /path/to/your/server/certificates/fullchain.pem;\n  ssl_certificate_key /path/to/your/server/certificates/privkey.pem;\n  location /dns-query {\n    proxy_pass       http://localhost:8053/dns-query;\n    proxy_set_header Host      $host;\n    proxy_set_header X-Real-IP $remote_addr;\n  }\n}\n```\n(Credit: [Cipherli.st](https://cipherli.st/))\n\n### Example configuration: Caddy (v2)\n```bash\nmy.server.name {\n        reverse_proxy * localhost:8053\n        tls your@email.address\n        try_files {path} {path}/index.php /index.php?{query}\n}\n```\n### Example configuration: Docker Compose + Traefik + Unbound (Raspberry Pi/Linux/Mac) [linux/amd64,linux/arm64,linux/arm/v7]\n\n```yaml\nversion: '2.2'\nnetworks:\n  default:\n\nservices:\n  proxy:\n    # The official v2 Traefik docker image\n    image: traefik:v2.3\n    hostname: proxy\n    networks:\n      - default\n    environment:\n      TRAEFIK_ACCESSLOG: \"true\"\n      TRAEFIK_API: \"true\"\n      TRAEFIK_PROVIDERS_DOCKER: \"true\"\n      TRAEFIK_API_INSECURE: \"true\"\n      TRAEFIK_PROVIDERS_DOCKER_NETWORK: \"${STACK}_default\"\n      # DNS provider specific environment variables for DNS Challenge using route53 (AWS)\n      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}\n      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}\n      AWS_REGION: ${AWS_REGION}\n      AWS_HOSTED_ZONE_ID: ${AWS_HOSTED_ZONE_ID}\n    ports:\n      # The HTTP port\n      - \"80:80\"\n      # The HTTPS port\n      - \"443:443\"\n      # The Web UI (enabled by --api.insecure=true)\n      - \"8080:8080\"\n    command:\n      #- \"--log.level=DEBUG\"\n      - \"--providers.docker.exposedbydefault=false\"\n      - \"--entrypoints.web.address=:80\"\n      - \"--entrypoints.websecure.address=:443\"\n      - \"--certificatesresolvers.letsencrypt.acme.dnschallenge=true\"\n      # Providers list:\n      #  https://docs.traefik.io/https/acme/#providers\n      #  https://go-acme.github.io/lego/dns/\n      - \"--certificatesresolvers.letsencrypt.acme.dnschallenge.provider=route53\"\n      # Enable below line to use staging letsencrypt server.\n      #- \"--certificatesresolvers.letsencrypt.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory\"\n      - \"--certificatesresolvers.letsencrypt.acme.email=${EMAIL}\"\n      - \"--certificatesresolvers.letsencrypt.acme.storage=/certs/acme.json\"\n    volumes:\n      # So that Traefik can listen to the Docker events\n      - /var/run/docker.sock:/var/run/docker.sock\n      - ./data/proxy/certs:/certs\n  doh-server:\n    image: satishweb/doh-server:latest\n    hostname: doh-server\n    networks:\n      - default\n    environment:\n      # Enable below line to see more logs\n      # DEBUG: \"1\"\n      UPSTREAM_DNS_SERVER: \"udp:unbound:53\"\n      DOH_HTTP_PREFIX: \"${DOH_HTTP_PREFIX}\"\n      DOH_SERVER_LISTEN: \":${DOH_SERVER_LISTEN}\"\n      DOH_SERVER_TIMEOUT: \"10\"\n      DOH_SERVER_TRIES: \"3\"\n      DOH_SERVER_VERBOSE: \"false\"\n    #volumes:\n      # - ./doh-server.conf:/server/doh-server.conf\n      # - ./app-config:/app-config\n    depends_on:\n      - unbound\n    labels:\n      - \"traefik.enable=true\"\n      - \"traefik.http.routers.doh-server.rule=Host(`${SUBDOMAIN}.${DOMAIN}`) \u0026\u0026 Path(`${DOH_HTTP_PREFIX}`)\"\n      - \"traefik.http.services.doh-server.loadbalancer.server.port=${DOH_SERVER_LISTEN}\"\n      - \"traefik.http.middlewares.mw-doh-compression.compress=true\"\n      - \"traefik.http.routers.doh-server.tls=true\"\n      - \"traefik.http.middlewares.mw-doh-tls.headers.sslredirect=true\"\n      - \"traefik.http.middlewares.mw-doh-tls.headers.sslforcehost=true\"\n      - \"traefik.http.routers.doh-server.tls.certresolver=letsencrypt\"\n      - \"traefik.http.routers.doh-server.tls.domains[0].main=${DOMAIN}\"\n      - \"traefik.http.routers.doh-server.tls.domains[0].sans=${SUBDOMAIN}.${DOMAIN}\"\n      # Protection from requests flood\n      - \"traefik.http.middlewares.mw-doh-ratelimit.ratelimit.average=100\"\n      - \"traefik.http.middlewares.mw-doh-ratelimit.ratelimit.burst=50\"\n      - \"traefik.http.middlewares.mw-doh-ratelimit.ratelimit.period=10s\"\n  unbound:\n    image: satishweb/unbound:latest\n    hostname: unbound\n    networks:\n      - default\n    ports:\n      # Disable these ports if DOH server is the only client\n      - 53:53/tcp\n      - 53:53/udp\n    volumes:\n      - ./unbound.sample.conf:/templates/unbound.sample.conf\n      - ./data/unbound/custom:/etc/unbound/custom\n      # Keep your custom.hosts file inside custom folder\n    #environment:\n    #  DEBUG: \"1\"\n````\n\n\u003e Complete Guide available at: https://github.com/satishweb/docker-doh\n\n\u003e IPV6 Support for Docker Compose based configuration TBA\n\n### Example configuration: DNS-over-TLS\n\nThere is no native [DNS-over-TLS](https://en.wikipedia.org/wiki/DNS_over_TLS) support, but you can easily add it via nginx:\n```\nstream {\n    server {\n        listen                  *:853 ssl;\n        proxy_pass              ipofyourdnsresolver:port  #127.0.0.1:53\n    }\n\n    ssl_certificate /etc/letsencrypt/live/site.yourdomain/fullchain.pem;\n    ssl_certificate_key /etc/letsencrypt/live/site.yourdomain/privkey.pem;\n}\n```\n\nThe DoT service can also be provided by running a [STunnel](https://www.stunnel.org/) instance to wrap dnsmasq (or any other resolver of your choice, listening on a TCP port);\nthis approach does not need a stand-alone daemon to provide the DoT service.\n\n## DNSSEC\n\nDNS-over-HTTPS is compatible with DNSSEC, and requests DNSSEC signatures by\ndefault. However, signature validation is not built-in. It is highly recommended\nthat you install `unbound` or `bind` and pass results for them to validate DNS\nrecords. An instance of [Pi Hole](https://pi-hole.net) could also be used to validate DNS signatures as well as provide other capabilities.\n\n## EDNS0-Client-Subnet (GeoDNS)\n\nDNS-over-HTTPS supports EDNS0-Client-Subnet protocol, which submits part of the\nclient's IP address (/24 for IPv4, /56 for IPv6 by default) to the upstream\nserver. This is useful for GeoDNS and CDNs to work, and is exactly the same\nconfiguration as most public DNS servers.\n\nKeep in mind that /24 is not enough to track a single user, although it is\nprecise enough to know the city where the user is located. If you think\nEDNS0-Client-Subnet is affecting your privacy, you can set `no_ecs = true` in\n`/etc/dns-over-https/doh-client.conf`, with the cost of slower video streaming\nor software downloading speed.\n\nTo ultilize ECS, `X-Forwarded-For` or `X-Real-IP` should be enabled on your\nHTTP service muxer. If your server is backed by `unbound` or `bind`, you\nprobably want to configure it to enable the EDNS0-Client-Subnet feature as\nwell.\n\n## Protocol compatibility\n\n### Google DNS-over-HTTPS Protocol\n\nDNS-over-HTTPS uses a protocol compatible to [Google DNS-over-HTTPS](https://developers.google.com/speed/public-dns/docs/dns-over-https),\nexcept for absolute expire time is preferred to relative TTL value. Refer to\n[json-dns/response.go](json-dns/response.go) for a complete description of the\nAPI.\n\n### IETF DNS-over-HTTPS Protocol\n\nDNS-over-HTTPS uses a protocol compatible to [IETF DNS-over-HTTPS (RFC 8484)](https://www.rfc-editor.org/rfc/rfc8484.txt).\n\n### Supported features\n\nCurrently supported features are:\n\n- [X] IPv4 / IPv6\n- [X] EDNS0 large UDP packet (4 KiB by default)\n- [X] EDNS0-Client-Subnet (/24 for IPv4, /56 for IPv6 by default)\n\n## Known issues\n\n* it does not work well with [dnscrypt-proxy](https://github.com/DNSCrypt/dnscrypt-proxy), you might want to use either (or fix the compatibility bugs by submitting PRs)\n\n## The name of the project\n\nThis project is named \"DNS-over-HTTPS\" because it was written before the IETF DoH project. Although this project is compatible with IETF DoH, the project is not affiliated with IETF.\n\nTo avoid confusion, you may also call this project \"m13253/DNS-over-HTTPS\" or anything you like.\n\n## License\n\nDNS-over-HTTPS is licensed under the [MIT License](LICENSE). You are encouraged\nto embed DNS-over-HTTPS into your other projects, as long as the license\npermits.\n\nYou are also encouraged to disclose your improvements to the public, so that\nothers may benefit from your modification, in the same way you receive benefits\nfrom this project.\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm13253%2Fdns-over-https","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm13253%2Fdns-over-https","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm13253%2Fdns-over-https/lists"}