DNS Server

Overview

This 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).

The Server can listen for queries on UDP (port 53), TLS/TCP (port 853) and HTTPS/H2 (port 443). The Resolver can send queries on UDP (port 53), TLS/TCP (port 853) or HTTPS/H2 (port 443).

Project built using rust and available on Docker Hub.

Usage

Create 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)

Usage: dns-server [OPTIONS]

Options:
  -p, --port <PORT>
          Listen port of the classic DNS server over UDP [default: 53]
  -l, --listen <LISTEN>
          Listen adress of the server [default: 0.0.0.0]
      --workers <WORKER>
          Number of workers to setup [default: 4]
      --blacklist <BLACKLIST>
          File containing a list of exact domains to block
      --default-ip <DEFAULT_IP>
          Default IP address to return when the domain is blocked instead of an empty NoError response
      --zone-blacklist <ZONE_BLACKLIST>
          File containing a list of zone of domains to block, this will block the domain and all subdomains
      --dns-server <DNS_SERVER>
          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:<tls|h2|h3|quic>:domain, [ipv6]:<tls|h2|h3|quic>:domain, ipv4:port:<tls|h2|h3|quic>:domain, [ipv6]:port:<tls|h2|h3|quic>:domain, ipv4:<h2|h3>:domain, [ipv6]:<h2|h3>:domain:/path, ipv4:port:<h2|h3>:domain:/path, [ipv6]:port:<h2|h3>:domain:/path]
      --h2
          Activate https/h2 server beside classic DNS server over UDP
      --h2-port <H2_PORT>
          Listen port of the https/h2 server [default: 443]
      --h2-path <H2_PATH>
          Listen path of the https/h2 server [default: /]
      --quic
          Activate quic server beside classic DNS server over UDP
      --quic-port <QUIC_PORT>
          Listen port of the quic server [default: 853]
      --h3
          Activate h3 server beside classic DNS server over UDP
      --h3-port <H3_PORT>
          Listen port of the h3 server [default: 443]
      --tls
          Activate DNS over TLS (TCP) server beside classic DNS server over UDP
      --tls-port <TLS_PORT>
          Listen port of the Dns over TLS (TCP) server [default: 853]
      --tls-certificate <TLS_CERTIFICATE>
          Path of the certificate for the https/h2 server
      --tls-private-key <TLS_PRIVATE_KEY>
          Path of the private key for the https/h2 server
      --rfc8215-ips <RFC8215_IPS>
          IP using Local-Use IPv4/IPv6 Translation Prefix (rfc8215)
      --deny-networks <DENY_NETWORKS>
          Networks denied to access the server
      --allow-networks <ALLOW_NETWORKS>
          Networks allowed to access the server
      --local-dns-file <LOCAL_DNS_FILE>
          Local DNS file in /etc/hosts style
  -h, --help
          Print help
  -V, --version
          Print version

Blacklist domain names

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

You have the choice between returning a specific IP with --default-ip for your blocked domain or send an empty response.

DNS Server resolver

You can add another DNS resolver (different than Cloudflare and Google) with the --dns-server option. The format is ip:port:protocol:domain:/path.

ip (Required): either IPv4 (e.g. 1.1.1.1) or IPv6 (e.g. [2606:4700:4700::1111]).
port: custom port to contact the resolver, must be a number greater than 0. Default value based on the protocol.
protocol: protocol to use to contact the resolver.
- default: when unset will use DNS over UDP
- tls: will use DNS over TLS (DoT). Default port will be 853 on TCP.
- h2: will use DNS over HTTPS/H2 (DoH). Default port will be 443 on TCP.
- quic: will use DNS over Quic (DoQ). Default port will be 853 on UDP.
- h3: will use DNS over HTTP3 (DoH3). Default port will be 443 on UDP.
domain (Required for tls, h2 and quic and h3): the domain name of your resolver. Use to check the certificate.
path: custom path to contact the resolver. Available only for h2 and h3.

Some examples with ipv4 and ipv6 and cloudflare IPs.

# UDP DNS IPv4
--dns-server 1.1.1.1 # cloudflare UDP DNS IPv4 with default port
--dns-server 1.1.1.1:53 # cloudflare UDP DNS IPv4

# UDP DNS IPv6
--dns-server  # cloudflare UDP DNS IPv6 with default port
--dns-server [2606:4700:4700::1111]:53 # cloudflare UDP DNS IPv6

# TLS DNS IPv4
--dns-server 1.1.1.1:tls:cloudflare-dns.com # cloudflare TLS DNS IPv4 with default port
--dns-server 1.1.1.1:853:tls:cloudflare-dns.com # cloudflare TLS DNS IPv4

# H2 DNS IPv4
--dns-server 1.1.1.1:h2:cloudflare-dns.com # cloudflare H2 DNS IPv4 with default port
--dns-server 1.1.1.1:443:h2:cloudflare-dns.com:/dns-query # cloudflare H2 DNS IPv4

# Quic DNS IPv4
--dns-server 1.1.1.1:quic:cloudflare-dns.com # cloudflare Quic DNS IPv4 with default port
--dns-server 1.1.1.1:853:quic:cloudflare-dns.com # cloudflare Quic DNS IPv4

# H3 DNS IPv4
--dns-server 1.1.1.1:h3:cloudflare-dns.com # cloudflare H3 DNS IPv4 with default port
--dns-server 1.1.1.1:443:h3:cloudflare-dns.com:/dns-query # cloudflare H3 DNS IPv4

DNS Resolve (bin)

Try your server with the built in DNS resolver.

Use 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)

Usage: dns-resolve [OPTIONS] [DOMAIN]...

Arguments:
  [DOMAIN]...  

Options:
      --dns-server <DNS_SERVER>  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:<tls|h2|h3|quic>:domain, [ipv6]:<tls|h2|h3|quic>:domain, ipv4:port:<tls|h2|h3|quic>:domain, [ipv6]:port:<tls|h2|h3|quic>:domain, ipv4:<h2|h3>:domain, [ipv6]:<h2|h3>:domain:/path, ipv4:port:<h2|h3>:domain:/path, [ipv6]:port:<h2|h3>:domain:/path]
  -t, --type <RECORD_TYPE>       Type of query to issue, e.g. A, AAAA, NS, etc [default: A]
  -h, --help                     Print help
  -V, --version                  Print version

Configure logging

You can configure the logging level with the envirnoment variable RUST_LOG. The default value in the image is RUST_LOG=warn.