nixos/modules/services/networking/crab-hole.md

   1 # 🦀 crab-hole {#module-services-crab-hole}
   2
   3 Crab-hole is a cross platform Pi-hole clone written in Rust using [hickory-dns/trust-dns](https://github.com/hickory-dns/hickory-dns).
   4 It can be used as a network wide ad and spy blocker or run on your local PC.
   5
   6 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.
   7 It also comes with privacy friendly default logging settings.
   8
   9 ## Configuration {#module-services-crab-hole-configuration}
  10 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)
  11
  12
  13 The following is a basic nix config using UDP as a downstream and Cloudflare as upstream.
  14
  15 ```nix
  16 {
  17   services.crab-hole = {
  18     enable = true;
  19
  20     settings = {
  21       blocklist = {
  22         include_subdomains = true;
  23         lists = [
  24           "https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews-gambling-porn/hosts"
  25           "https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt"
  26         ];
  27       };
  28
  29       downstream = [
  30         {
  31           protocol = "udp";
  32           listen = "127.0.0.1";
  33           port = 53;
  34         }
  35         {
  36           protocol = "udp";
  37           listen = "::1";
  38           port = 53;
  39         }
  40       ];
  41
  42       upstream = {
  43         name_servers = [
  44           {
  45             socket_addr = "1.1.1.1:853";
  46             protocol = "tls";
  47             tls_dns_name = "1dot1dot1dot1.cloudflare-dns.com";
  48             trust_nx_responses = false;
  49           }
  50           {
  51             socket_addr = "[2606:4700:4700::1111]:853";
  52             protocol = "tls";
  53             tls_dns_name = "1dot1dot1dot1.cloudflare-dns.com";
  54             trust_nx_responses = false;
  55           }
  56         ];
  57       };
  58     };
  59   };
  60 }
  61 ```
  62
  63 To test your setup, just query the DNS server with any domain like `example.com`.
  64 To test if a domain gets blocked, just choose one of the domains from the blocklist.
  65 If the server does not return an IP, this worked correctly.
  66
  67 ### Downstream options {#module-services-crab-hole-downstream}
  68 There are multiple protocols which are supported for the downstream:
  69 UDP, TLS, HTTPS and QUIC.
  70 Below you can find a brief overview over the various protocol options together with an example for each protocol.
  71
  72 #### UDP {#module-services-crab-hole-udp}
  73 UDP is the simplest downstream, but it is not encrypted.
  74 If you want encryption, you need to use another protocol.
  75 ***Note:** This also opens a TCP port*
  76 ```nix
  77 {
  78   services.crab-hole.settings.downstream = [
  79     {
  80       protocol = "udp";
  81       listen = "localhost";
  82       port = 53;
  83     }
  84   ];
  85 }
  86 ```
  87
  88 #### TLS {#module-services-crab-hole-tls}
  89 TLS is a simple encrypted options to serve DNS.
  90 It comes with similar settings to UDP,
  91 but you additionally need a valid TLS certificate and its private key.
  92 The later are specified via a path to the files.
  93 A valid TLS certificate and private key can be obtained using services like ACME.
  94 Make sure the crab-hole service user has access to these files.
  95 Additionally you can set an optional timeout value.
  96 ```nix
  97 {
  98   services.crab-hole.settings.downstream = [
  99     {
 100       protocol = "tls";
 101       listen = "[::]";
 102       port = 853;
 103       certificate = ./dns.example.com.crt;
 104       key = "/dns.example.com.key";
 105       # optional (default = 3000)
 106       timeout_ms = 3000
 107     }
 108   ];
 109 }
 110 ```
 111
 112 #### HTTPS {#module-services-crab-hole-https}
 113 HTTPS has similar settings to TLS, with the only difference being the additional `dns_hostname` option.
 114 This protocol might need a reverse proxy if other HTTPS services are to share the same port.
 115 Make sure the service has permissions to access the certificate and key.
 116
 117 ***Note:** this config is untested*
 118 ```nix
 119 {
 120   services.crab-hole.settings.downstream = [
 121     {
 122       protocol = "https";
 123       listen = "[::]";
 124       port = 443;
 125       certificate = ./dns.example.com.crt;
 126       key = "/dns.example.com.key";
 127       # optional
 128       dns_hostname = "dns.example.com";
 129       # optional (default = 3000)
 130       timeout_ms = 3000;
 131     }
 132   ];
 133 }
 134 ```
 135
 136 #### QUIC {#module-services-crab-hole-quic}
 137 QUIC has identical settings to the HTTPS protocol.
 138 Since by default it doesn't run on the standard HTTPS port, you shouldn't need a reverse proxy.
 139 Make sure the service has permissions to access the certificate and key.
 140 ```nix
 141 {
 142   services.crab-hole.settings.downstream = [
 143     {
 144       protocol = "quic";
 145       listen = "127.0.0.1";
 146       port = 853;
 147       certificate = ./dns.example.com.crt;
 148       key = "/dns.example.com.key";
 149       # optional
 150       dns_hostname = "dns.example.com";
 151       # optional (default = 3000)
 152       timeout_ms = 3000;
 153     }
 154   ];
 155 }
 156 ```
 157
 158 ### Upstream options {#module-services-crab-hole-upstream-options}
 159 You can set additional options of the underlying DNS server. A full list of all the options can be found in the [hickory-dns documentation](https://docs.rs/trust-dns-resolver/0.23.0/trust_dns_resolver/config/struct.ResolverOpts.html).
 160
 161 This can look like the following example.
 162 ```nix
 163 {
 164   services.crab-hole.settings.upstream.options = {
 165     validate = false;
 166   };
 167 }
 168 ```
 169
 170 #### DNSSEC Issues {#module-services-crab-hole-dnssec}
 171 Due to an upstream issue of [hickory-dns](https://github.com/hickory-dns/hickory-dns/issues/2429), sites without DNSSEC will not be resolved if `validate = true`.
 172 Only DNSSEC capable sites will be resolved with this setting.
 173 To prevent this, set `validate = false` or omit the `[upstream.options]`.
 174
 175 ### API {#module-services-crab-hole-api}
 176 The API allows a user to fetch statistic and information about the crab-hole instance.
 177 Basic information is availablee for everyone, while more detailed information is secured by a key, which will be set with the `admin_key` option.
 178
 179 ```nix
 180 {
 181   services.crab-hole.settings.api = {
 182     listen = "127.0.0.1";
 183     port = 8080;
 184     # optional (default = false)
 185     show_doc = true; # OpenAPI doc loads content from third party websites
 186     # optional
 187     admin_key = "1234";
 188   };
 189 }
 190
 191 ```
 192
 193 The documentation can be enabled seperately for the instance with `show_doc`.
 194 This will then create an additional webserver, which hosts the API documentation.
 195 An additional resource is in work in the [crab-hole repository](https://github.com/LuckyTurtleDev/crab-hole).
 196
 197 ## Troubleshooting {#module-services-crab-hole-troubleshooting}
 198 You can check for errors using `systemctl status crab-hole` or `journalctl -xeu crab-hole.service`.
 199
 200 ### Invalid config {#module-services-crab-hole-invalid-config}
 201 Some options of the service are in freeform and not type checked.
 202 This can lead to a config which is not valid or cannot be parsed by crab-hole.
 203 The error message will tell you what config value could not be parsed.
 204 For more information check the [example config](https://github.com/LuckyTurtleDev/crab-hole/blob/main/example-config.toml).
 205
 206 ### Permission Error {#module-services-crab-hole-permission-error}
 207 It can happen that the created certificates for TLS, HTTPS or QUIC are owned by another user or group.
 208 For ACME for example this would be `acme:acme`.
 209 To give the crab-hole service access to these files, the group which owns the certificate can be added as a supplementary group to the service.
 210 For ACME for example:
 211 ```nix
 212 {
 213   services.crab-hole.supplementaryGroups = [ "acme" ];
 214 }
 215 ```