# 🦀 crab-hole {#module-services-crab-hole}

Crab-hole is a cross platform Pi-hole clone written in Rust using [hickory-dns/trust-dns](https://github.com/hickory-dns/hickory-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.

## Configuration {#module-services-crab-hole-configuration}
As an example config file using Cloudflare as DoT upstream, you can use this [crab-hole.toml](https://github.com/LuckyTurtleDev/crab-hole/blob/main/example-config.toml)


The following is a basic nix config using UDP as a downstream and Cloudflare as upstream.

```nix
{
  services.crab-hole = {
    enable = true;

    settings = {
      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"
        ];
      };

      downstream = [
        {
          protocol = "udp";
          listen = "127.0.0.1";
          port = 53;
        }
        {
          protocol = "udp";
          listen = "::1";
          port = 53;
        }
      ];

      upstream = {
        name_servers = [
          {
            socket_addr = "1.1.1.1:853";
            protocol = "tls";
            tls_dns_name = "1dot1dot1dot1.cloudflare-dns.com";
            trust_nx_responses = false;
          }
          {
            socket_addr = "[2606:4700:4700::1111]:853";
            protocol = "tls";
            tls_dns_name = "1dot1dot1dot1.cloudflare-dns.com";
            trust_nx_responses = false;
          }
        ];
      };
    };
  };
}
```

To test your setup, just query the DNS server with any domain like `example.com`.
To test if a domain gets blocked, just choose one of the domains from the blocklist.
If the server does not return an IP, this worked correctly.

### Downstream options {#module-services-crab-hole-downstream}
There are multiple protocols which are supported for the downstream:
UDP, TLS, HTTPS and QUIC.
Below you can find a brief overview over the various protocol options together with an example for each protocol.

#### UDP {#module-services-crab-hole-udp}
UDP is the simplest downstream, but it is not encrypted.
If you want encryption, you need to use another protocol.
***Note:** This also opens a TCP port*
```nix
{
  services.crab-hole.settings.downstream = [
    {
      protocol = "udp";
      listen = "localhost";
      port = 53;
    }
  ];
}
```

#### TLS {#module-services-crab-hole-tls}
TLS is a simple encrypted options to serve DNS.
It comes with similar settings to UDP,
but you additionally need a valid TLS certificate and its private key.
The later are specified via a path to the files.
A valid TLS certificate and private key can be obtained using services like ACME.
Make sure the crab-hole service user has access to these files.
Additionally you can set an optional timeout value.
```nix
{
  services.crab-hole.settings.downstream = [
    {
      protocol = "tls";
      listen = "[::]";
      port = 853;
      certificate = ./dns.example.com.crt;
      key = "/dns.example.com.key";
      # optional (default = 3000)
      timeout_ms = 3000
    }
  ];
}
```

#### HTTPS {#module-services-crab-hole-https}
HTTPS has similar settings to TLS, with the only difference being the additional `dns_hostname` option.
This protocol might need a reverse proxy if other HTTPS services are to share the same port.