{"id":16731598,"url":"https://github.com/joxit/dns-server","last_synced_at":"2026-05-14T20:04:15.341Z","repository":{"id":205741171,"uuid":"696480256","full_name":"Joxit/dns-server","owner":"Joxit","description":"Block ads and malwares at DNS level with your private DNS Server","archived":false,"fork":false,"pushed_at":"2026-05-05T13:56:52.000Z","size":120,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-05T15:41:59.383Z","etag":null,"topics":["dns","dns-over-https","dns-over-tls","dns-server","privacy","rust","rust-lang","security","security-tools"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/Joxit.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Joxit"}},"created_at":"2023-09-25T20:35:45.000Z","updated_at":"2026-05-05T13:57:34.000Z","dependencies_parsed_at":"2023-11-06T09:29:25.811Z","dependency_job_id":"581301a7-2707-4d07-a404-74ec6427c671","html_url":"https://github.com/Joxit/dns-server","commit_stats":null,"previous_names":["joxit/dns-server"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Joxit/dns-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Joxit%2Fdns-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Joxit%2Fdns-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Joxit%2Fdns-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Joxit%2Fdns-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Joxit","download_url":"https://codeload.github.com/Joxit/dns-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Joxit%2Fdns-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33041218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","dns-over-tls","dns-server","privacy","rust","rust-lang","security","security-tools"],"created_at":"2024-10-12T23:38:03.850Z","updated_at":"2026-05-14T20:04:15.335Z","avatar_url":"https://github.com/Joxit.png","language":"Rust","funding_links":["https://github.com/sponsors/Joxit"],"categories":[],"sub_categories":[],"readme":"# DNS Server\n\n[![Pulls](https://img.shields.io/docker/pulls/joxit/dns-server.svg?maxAge=86400)](https://hub.docker.com/r/joxit/dns-server)\n[![Langs](https://img.shields.io/github/languages/top/joxit/dns-server)](https://github.com/Joxit/dns-server)\n[![Project](https://img.shields.io/badge/joxit-dns_server-blue?logo=github)](https://github.com/Joxit/dns-server)\n[![website](https://img.shields.io/badge/website-dns_server-blue)](https://joxit.dev/dns-server)\n[![Sponsor](https://joxit.dev/images/sponsor.svg)](https://github.com/sponsors/Joxit)\n\n## Overview\n\nThis project aims to provide a simple dns server you can deploy and to blacklist domains (ads, malware...). Provide your own list of all domains to block and use your favorite DNS Resolver for authorised domains (only cloudflare and google over UDP/TLS/HTTPS are available).\n\nThe Server can listen for queries on UDP (port 53), TLS/TCP (port 853) and HTTPS/H2 (port 443).\nThe Resolver can send queries on UDP (port 53), TLS/TCP (port 853) or HTTPS/H2 (port 443).\n\nProject built using rust and available on [Docker Hub](https://hub.docker.com/r/joxit/dns-server).\n\n## Usage\n\n```\nCreate a DNS server you can configure to block some domain and zones.You can use UDP or DNS over TLS/TCP (DoT) or DNS over HTTPS/H2 (DoH) or DNS over Quic (DoQ) or DNS over HTTP3 (DoH3) as listeners (frontend) and resolver (backend)\n\nUsage: dns-server [OPTIONS]\n\nOptions:\n  -p, --port \u003cPORT\u003e\n          Listen port of the classic DNS server over UDP [default: 53]\n  -l, --listen \u003cLISTEN\u003e\n          Listen adress of the server [default: 0.0.0.0]\n      --workers \u003cWORKER\u003e\n          Number of workers to setup [default: 4]\n      --blacklist \u003cBLACKLIST\u003e\n          File containing a list of exact domains to block\n      --default-ip \u003cDEFAULT_IP\u003e\n          Default IP address to return when the domain is blocked instead of an empty NoError response\n      --zone-blacklist \u003cZONE_BLACKLIST\u003e\n          File containing a list of zone of domains to block, this will block the domain and all subdomains\n      --dns-server \u003cDNS_SERVER\u003e\n          Setup your trusted dns resolver, could be cloudflare or google with UDP, TLS or H2. The port is optional when you are using custom IP. When you use TLS or H2 protocols, you must add the domain name too [default: cloudflare:h2] [possible values: cloudflare, google, cloudflare:tls, google:tls, cloudflare:h2, google:h2, cloudflare:h3, google:h3, cloudflare:quic, google:quic, ipv4:port, [ipv6]:port, ipv4:\u003ctls|h2|h3|quic\u003e:domain, [ipv6]:\u003ctls|h2|h3|quic\u003e:domain, ipv4:port:\u003ctls|h2|h3|quic\u003e:domain, [ipv6]:port:\u003ctls|h2|h3|quic\u003e:domain, ipv4:\u003ch2|h3\u003e:domain, [ipv6]:\u003ch2|h3\u003e:domain:/path, ipv4:port:\u003ch2|h3\u003e:domain:/path, [ipv6]:port:\u003ch2|h3\u003e:domain:/path]\n      --h2\n          Activate https/h2 server beside classic DNS server over UDP\n      --h2-port \u003cH2_PORT\u003e\n          Listen port of the https/h2 server [default: 443]\n      --h2-path \u003cH2_PATH\u003e\n          Listen path of the https/h2 server [default: /]\n      --quic\n          Activate quic server beside classic DNS server over UDP\n      --quic-port \u003cQUIC_PORT\u003e\n          Listen port of the quic server [default: 853]\n      --h3\n          Activate h3 server beside classic DNS server over UDP\n      --h3-port \u003cH3_PORT\u003e\n          Listen port of the h3 server [default: 443]\n      --tls\n          Activate DNS over TLS (TCP) server beside classic DNS server over UDP\n      --tls-port \u003cTLS_PORT\u003e\n          Listen port of the Dns over TLS (TCP) server [default: 853]\n      --tls-certificate \u003cTLS_CERTIFICATE\u003e\n          Path of the certificate for the https/h2 server\n      --tls-private-key \u003cTLS_PRIVATE_KEY\u003e\n          Path of the private key for the https/h2 server\n      --rfc8215-ips \u003cRFC8215_IPS\u003e\n          IP using Local-Use IPv4/IPv6 Translation Prefix (rfc8215)\n      --deny-networks \u003cDENY_NETWORKS\u003e\n          Networks denied to access the server\n      --allow-networks \u003cALLOW_NETWORKS\u003e\n          Networks allowed to access the server\n      --local-dns-file \u003cLOCAL_DNS_FILE\u003e\n          Local DNS file in /etc/hosts style\n  -h, --help\n          Print help\n  -V, --version\n          Print version\n```\n\n## Blacklist domain names\n\nYou have two ways to block domain names, both are based on files, one domain per line. All domains in the file given to `--blacklist` will be blocked only if they exactly match the query. By using `--zone-blacklist` you will block the domain and all its subdomains.\n\nYou have the choice between returning a specific IP with `--default-ip` for your blocked domain or send an empty response.\n\n## DNS Server resolver\n\nYou can add another DNS resolver (different than Cloudflare and Google) with the `--dns-server` option. The format is `ip:port:protocol:domain:/path`. \n- `ip` (Required): either IPv4 (e.g. `1.1.1.1`) or IPv6 (e.g. `[2606:4700:4700::1111]`).\n- `port`: custom port to contact the resolver, must be a number greater than 0. Default value based on the protocol.\n- `protocol`: protocol to use to contact the resolver.\n  - default: when unset will use DNS over UDP\n  - `tls`: will use DNS over TLS (DoT). Default port will be `853` on TCP.\n  - `h2`: will use DNS over HTTPS/H2 (DoH). Default port will be `443` on TCP.\n  - `quic`: will use DNS over Quic (DoQ). Default port will be `853` on UDP.\n  - `h3`: will use DNS over HTTP3 (DoH3). Default port will be `443` on UDP.\n- `domain` (Required for `tls`, `h2` and `quic` and `h3`): the domain name of your resolver. Use to check the certificate.\n- `path`: custom path to contact the resolver. Available only for `h2` and `h3`.\n\nSome examples with ipv4 and ipv6 and cloudflare IPs.\n\n\n```\n# UDP DNS IPv4\n--dns-server 1.1.1.1 # cloudflare UDP DNS IPv4 with default port\n--dns-server 1.1.1.1:53 # cloudflare UDP DNS IPv4\n\n# UDP DNS IPv6\n--dns-server  # cloudflare UDP DNS IPv6 with default port\n--dns-server [2606:4700:4700::1111]:53 # cloudflare UDP DNS IPv6\n\n# TLS DNS IPv4\n--dns-server 1.1.1.1:tls:cloudflare-dns.com # cloudflare TLS DNS IPv4 with default port\n--dns-server 1.1.1.1:853:tls:cloudflare-dns.com # cloudflare TLS DNS IPv4\n\n# H2 DNS IPv4\n--dns-server 1.1.1.1:h2:cloudflare-dns.com # cloudflare H2 DNS IPv4 with default port\n--dns-server 1.1.1.1:443:h2:cloudflare-dns.com:/dns-query # cloudflare H2 DNS IPv4\n\n# Quic DNS IPv4\n--dns-server 1.1.1.1:quic:cloudflare-dns.com # cloudflare Quic DNS IPv4 with default port\n--dns-server 1.1.1.1:853:quic:cloudflare-dns.com # cloudflare Quic DNS IPv4\n\n# H3 DNS IPv4\n--dns-server 1.1.1.1:h3:cloudflare-dns.com # cloudflare H3 DNS IPv4 with default port\n--dns-server 1.1.1.1:443:h3:cloudflare-dns.com:/dns-query # cloudflare H3 DNS IPv4\n```\n\n## DNS Resolve (bin)\n\nTry your server with the built in DNS resolver.\n\n```\nUse DNS client to try your dns server. You can use UDP or DNS over TLS/TCP (DoT) or DNS over HTTPS/H2 (DoH) or DNS over Quic (DoQ) or DNS over HTTP3 (DoH3)\n\nUsage: dns-resolve [OPTIONS] [DOMAIN]...\n\nArguments:\n  [DOMAIN]...  \n\nOptions:\n      --dns-server \u003cDNS_SERVER\u003e  Setup your dns server [default: cloudflare:h2] [possible values: cloudflare, google, cloudflare:tls, google:tls, cloudflare:h2, google:h2, cloudflare:h3, google:h3, cloudflare:quic, google:quic, ipv4:port, [ipv6]:port, ipv4:\u003ctls|h2|h3|quic\u003e:domain, [ipv6]:\u003ctls|h2|h3|quic\u003e:domain, ipv4:port:\u003ctls|h2|h3|quic\u003e:domain, [ipv6]:port:\u003ctls|h2|h3|quic\u003e:domain, ipv4:\u003ch2|h3\u003e:domain, [ipv6]:\u003ch2|h3\u003e:domain:/path, ipv4:port:\u003ch2|h3\u003e:domain:/path, [ipv6]:port:\u003ch2|h3\u003e:domain:/path]\n  -t, --type \u003cRECORD_TYPE\u003e       Type of query to issue, e.g. A, AAAA, NS, etc [default: A]\n  -h, --help                     Print help\n  -V, --version                  Print version\n```\n\n## Configure logging\n\nYou can configure the logging level with the envirnoment variable `RUST_LOG`. The default value in the image is `RUST_LOG=warn`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoxit%2Fdns-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoxit%2Fdns-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoxit%2Fdns-server/lists"}