🦀 crab-hole

Crab-hole is a cross platform Pi-hole clone written in Rust using hickory-dns/trust-dns. It can be used as a network wide Ad and spy blocker or run on your local pc.

For a secure and private communication, crab-hole has builtin support for doh(https), doq(quic) and dot(tls) for down- and upstreams and dnssec for upstreams. It also comes with privacy friendly default logging settings.

Installation:

Crab-hole is available in the following repositories:

Prebuilt binaries can also been downloaded from the Github release.

Building from source:

Alternatively you can easily build crab-hole yourself.

• Install Rust
• Run cargo install crab-hole --locked See the Rust book for more information about cargo install.
• Make sure that ~/.cargo/bin is listed in the PATH environment variable

Docker

A docker image is available at the Github Container Registry. Example docker-compose.yml:

version: '3.3'
services:
    crab-hole:
        image: 'ghcr.io/luckyturtledev/crab-hole:latest' #semver tags are available
        ports: #required ports depend on downstream configuration
            - "53:53/tcp"
            - "53:53/udp"
        volumes:
            - './data:/data'
            - './config.toml:/data/config.toml:ro'

Semver tags like v0, v0.1 and v0.1.3 are available to safely allow automatic updates.

Configuration:

Example config file using cloudflare as dot (dns-over-tls) upstream. For the all settings see here.

[blocklist]
include_subdomains = true
lists = [
    "https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews-gambling-porn/hosts",
    "https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt",
    "file:///blocked.txt"
]
# allow domains blocked by the blocklist again
allow_list = ["file:///allowed.txt"]
blocking_mode = "nxdomain" # or use "zero" so client will get 0.0.0.0 or [::] as answer

# optional
[api]
listener = "127.0.0.1:8080"
# to use unix sockets, start listener with `unix://` 
#listener = "unix:///tmp/crab-hole.sock"
# optional (default = false)
show_doc = true # OpenAPI doc loads content from third party websites
# optional
admin_key = "1234"

[[downstream]]
protocol = "udp"
listen = "localhost"
port = 8080

[[downstream]]
protocol = "udp"
listen = "[::]" #all ipv6 and ipv4 adress
port = 8053

[[downstream]]
protocol = "tls"
listen = "[::]"
port = 8054
certificate = "dns.example.com.crt"
key = "dns.example.com.key"
# optional (default = 3000)
timeout_ms = 3000

[[downstream]]
protocol = "https"
listen = "[::]"
port = 8055
certificate = "dns.example.com.crt"
key = "dns.example.com.key"
dns_hostname = "dns.example.com"
# optional (default = 3000)
timeout_ms = 3000

[[downstream]]
protocol = "quic"
listen = "127.0.0.1"
port = 8055
certificate = "dns.example.com.crt"
key = "dns.example.com.key"
# optional (default = 3000)
timeout_ms = 3000

[[downstream]]
protocol = "h3"
listen = "127.0.0.1"
port = 8443
certificate = "dns.example.com.crt"
key = "dns.example.com.key"
dns_hostname = "dns.example.com"
# optional (default = 3000)
timeout_ms = 3000

# optional
[upstream.options]
# optional (default = false)
validate = true # use DNSSEC
# see https://docs.rs/hickory-resolver/0.26.0/hickory_resolver/config/struct.ResolverOpts.html for all options

[[upstream.name_servers]]
ip = "2606:4700:4700::1111"
port = 853
protocol = "tls"
server_name = "1dot1dot1dot1.cloudflare-dns.com"
trust_negative_responses = false
# see https://docs.rs/crab-hole/0.3.0/crab_hole/config/enum.UpstreamServer.html for all options


[[upstream.name_servers]]
ip = "2606:4700:4700::1001"
protocol = "tls"
server_name = "1dot1dot1dot1.cloudflare-dns.com"
trust_negative_responses = false

[[upstream.name_servers]]
ip = "1.1.1.1"
protocol = "tls"
server_name = "1dot1dot1dot1.cloudflare-dns.com"
trust_negative_responses = false

[[upstream.name_servers]]
ip = "1.0.0.1"
protocol = "tls"
server_name = "1dot1dot1dot1.cloudflare-dns.com"
trust_negative_responses = false

Starting the Server

To start the server just execute the binary without any subcommands.

crab-hole

Syntax check

To check if the config has a valid syntax, the following command can be used.

crab-hole validate-config

This loads the config to check for syntax issues, but does not start the DNS server.

Validation

The config and blocklists can be validated by running the following command.

crab-hole validate-lists

This only validates the config, block- and allowlists, and does not start the DNS server. If the validation fails, the program exits with the error code 1.