nixos/crab-hole: init crab-hole

nixos/doc/manual/release-notes/rl-2411.section.md

@@ -163,6 +163,8 @@
 
 - [Veilid](https://veilid.com), a headless server that enables privacy-focused data sharing and messaging on a peer-to-peer network. Available as [services.veilid](#opt-services.veilid.enable).
 
+- [crab-hole](https://github.com/LuckyTurtleDev/crab-hole), a cross platform Pi-hole clone written in Rust using hickory-dns/trust-dns. Available as [services.crab-hole](#opt-services.crab-hole.enable).
+
 ## Backward Incompatibilities {#sec-release-24.11-incompatibilities}
 
 - The `sound` options have been removed or renamed, as they had a lot of unintended side effects. See [below](#sec-release-24.11-migration-sound) for details.

nixos/modules/module-list.nix

@@ -1008,6 +1008,7 @@
   ./services/networking/coredns.nix
   ./services/networking/corerad.nix
   ./services/networking/coturn.nix
+  ./services/networking/crab-hole.nix
   ./services/networking/create_ap.nix
   ./services/networking/croc.nix
   ./services/networking/dae.nix

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

@@ -0,0 +1,210 @@
+# 🦀 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 use 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 (dns-over-tls) 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 = "localhost";
+          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.
+In the following there is a short overview over the different protocol options together with an example.
+
+#### UDP {#module-services-crab-hole-udp}
+UDP is the simplest downstream, but it is not encrypted.
+For this you need to use any other 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 has similar settings to UDP.
+To have encryption you need a valid certificate and key.
+These are specified via a path to the files.
+A valid certificate and key can be created by using services like ACME.
+Make sure the crab-hole service user has access to these files.
+Additionally you can set an optional timeout value, but this is not needed.
+```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 is similar to TLS, with the only difference of the additional `dns_hostname` option.
+This protocol might need a reverse proxy if there are other HTTPS services running.
+Make sure the service has permissions to access the certificate and key.
+
+***Note:** this config is untested*
+```nix
+{
+  services.crab-hole.settings.downstream = [
+    {
+      protocol = "https";
+      listen = "[::]";
+      port = 443;
+      certificate = ./dns.example.com.crt;
+      key = "/dns.example.com.key";
+      # optional
+      dns_hostname = "dns.example.com";
+      # optional (default = 3000)
+      timeout_ms = 3000;
+    }
+  ];
+}
+```
+
+#### QUIC {#module-services-crab-hole-quic}
+QUIC is identical to the HTTPS settings.
+But you do not need a reverse proxy, which might be needed for HTTPS.
+Make sure the service has permissions to access the certificate and key.
+```nix
+{
+  services.crab-hole.settings.downstream = [
+    {
+      protocol = "quic";
+      listen = "127.0.0.1";
+      port = 853;
+      certificate = ./dns.example.com.crt;
+      key = "/dns.example.com.key";
+      # optional
+      dns_hostname = "dns.example.com";
+      # optional (default = 3000)
+      timeout_ms = 3000;
+    }
+  ];
+}
+```
+
+### Upstream options {#module-services-crab-hole-upstream-options}
+You can set additional options of the underlying DNS server. A full list of all the options can be found in the [hickory-dns/trust-dns documentation](https://docs.rs/trust-dns-resolver/0.23.0/trust_dns_resolver/config/struct.ResolverOpts.html).
+
+This can look like the following example.
+```nix
+{
+  services.crab-hole.settings.upstream.options = {
+    validate = false;
+  };
+}
+```
+
+#### DNSSEC Issues {#module-services-crab-hole-dnssec}
+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`.
+Only DNSSEC capable sites will be resolved with this setting.
+To prevent this, set `validate = false` or omit the `[upstream.options]`.
+
+### API {#module-services-crab-hole-api}
+The API allows a user to fetch statistic and information about the crab-hole instance.
+Basic information is availablee for everyone, while more detailed information is secured by a key, which will be set with the `admin_key` option.
+
+```nix
+{
+  services.crab-hole.settings.api = {
+    listen = "127.0.0.1";
+    port = 8080;
+    # optional (default = false)
+    show_doc = true; # OpenAPI doc loads content from third party websites
+    # optional
+    admin_key = "1234";
+  };
+}
+
+```
+
+The documentation can be enabled seperately for the instance with `show_doc`.
+This will then create an additional webserver, which hosts the API documentation.
+An additional resource is in work in the [crab-hole repositiory](https://github.com/LuckyTurtleDev/crab-hole).
+
+## Troubleshooting {#module-services-crab-hole-troubleshooting}
+You can check for errors using `systemctl status crab-hole` or `journalctl -xeu crab-hole.service`.
+
+### Invalid config {#module-services-crab-hole-invalid-config}
+Some options of the service are in freeform and not type checked.
+This can lead to a config which is not valid or cannot be parsed by crab-hole.
+The error message will tell you what config value could not be parsed.
+For more information check the [example config](https://github.com/LuckyTurtleDev/crab-hole/blob/main/example-config.toml).
+
+### Permission Error {#module-services-crab-hole-permission-error}
+It can happen that the created certificates for TLS, HTTPS or QUIC are owned by another user or group.
+For ACME for example this would be `acme:acme`.
+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.
+For ACME for example:
+```nix
+{
+  services.crab-hole.supplementaryGroups = [ "acme" ];
+}
+```