https://github.com/joxit/dns-server
Block ads and malwares at DNS level with your private DNS Server
https://github.com/joxit/dns-server
dns dns-over-https dns-over-tls dns-server privacy rust rust-lang security security-tools
Last synced: about 1 month ago
JSON representation
Block ads and malwares at DNS level with your private DNS Server
- Host: GitHub
- URL: https://github.com/joxit/dns-server
- Owner: Joxit
- License: mit
- Created: 2023-09-25T20:35:45.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-02T20:08:32.000Z (7 months ago)
- Last Synced: 2025-03-24T10:06:31.269Z (about 2 months ago)
- Topics: dns, dns-over-https, dns-over-tls, dns-server, privacy, rust, rust-lang, security, security-tools
- Language: Rust
- Homepage:
- Size: 78.1 KB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# DNS Server
[](https://hub.docker.com/r/joxit/dns-server)
[](https://github.com/Joxit/dns-server)
[](https://github.com/Joxit/dns-server)
[](https://joxit.dev/dns-server)
[](https://github.com/sponsors/Joxit)
## 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](https://hub.docker.com/r/joxit/dns-server).
## 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) as listeners (frontend) and resolver (backend)
Usage: dns-server [OPTIONS]
Options:
-p, --port
Listen port of the classic DNS server over UDP [default: 53]
-l, --listen
Listen adress of the server [default: 0.0.0.0]
--workers
Number of workers to setup [default: 4]
--blacklist
File containing a list of exact domains to block
--default-ip
Default IP address to return when the domain is blocked instead of an empty NoError response
--zone-blacklist
File containing a list of zone of domains to block, this will block the domain and all subdomains
--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, ipv4:port, [ipv6]:port, ipv4:port::domain, [ipv6]:port::domain]
--h2
Activate https/h2 server beside classic DNS server over UDP
--h2-port
Listen port of the https/h2 server [default: 443]
--tls
Activate DNS over TLS (TCP) server beside classic DNS server over UDP
--tls-port
Listen port of the Dns over TLS (TCP) server [default: 853]
--tls-certificate
Path of the certificate for the https/h2 server
--tls-private-key
Path of the private key for the https/h2 server
-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`. 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 [2606:4700:4700::1111] # 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
# TLS DNS IPv6
--dns-server [2606:4700:4700::1111]:tls:cloudflare-dns.com # cloudflare TLS DNS IPv6 with default port
--dns-server [2606:4700:4700::1111]:853:tls:cloudflare-dns.com # cloudflare TLS DNS IPv6
# 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 # cloudflare H2 DNS IPv4
# H2 DNS IPv6
--dns-server [2606:4700:4700::1111]:h2:cloudflare-dns.com # cloudflare H2 DNS IPv6 with default port
--dns-server [2606:4700:4700::1111]:443:h2:cloudflare-dns.com # cloudflare H2 DNS IPv6
```
## Configure logging
You can configure the logging level with the envirnoment variable `RUST_LOG`. The default value in the image is `RUST_LOG=warn`.