nixos/doh-server: init

nixos/doc/manual/redirects.json

@@ -875,6 +875,12 @@
   "module-services-networking-dnsmasq-references": [
     "index.html#module-services-networking-dnsmasq-references"
   ],
+  "module-service-doh-server": [
+    "index.html#module-service-doh-server"
+  ],
+  "module-service-doh-server-quick-start": [
+    "index.html#module-service-doh-server-quick-start"
+  ],
   "module-services-samba": [
     "index.html#module-services-samba"
   ],

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

@@ -51,6 +51,8 @@
 
 - [networking.modemmanager](options.html#opt-networking.modemmanager) has been split out of [networking.networkmanager](options.html#opt-networking.networkmanager). NetworkManager still enables ModemManager by default, but options exist now to run NetworkManager without ModemManager.
 
+- [doh-server](https://github.com/m13253/dns-over-https), a high performance DNS over HTTPS server. Available as [services.doh-server](options.html#opt-services.doh-server.enable).
+
 - [ncps](https://github.com/kalbasit/ncps), a Nix binary cache proxy service implemented in Go using [go-nix](https://github.com/nix-community/go-nix). Available as [services.ncps](options.html#opt-services.ncps.enable).
 
 - [Conduwuit](https://conduwuit.puppyirl.gay/), a federated chat server implementing the Matrix protocol, forked from Conduit. Available as [services.conduwuit](#opt-services.conduwuit.enable).

nixos/modules/module-list.nix

@@ -1055,6 +1055,7 @@
   ./services/networking/dnsmasq.nix
   ./services/networking/dnsproxy.nix
   ./services/networking/doh-proxy-rust.nix
+  ./services/networking/doh-server.nix
   ./services/networking/ejabberd.nix
   ./services/networking/envoy.nix
   ./services/networking/epmd.nix

nixos/modules/services/networking/doh-server.md

@@ -0,0 +1,64 @@
+# DNS-over-HTTPS Server {#module-service-doh-server}
+
+[DNS-over-HTTPS](https://github.com/m13253/dns-over-https) is a high performance DNS over HTTPS client & server. This module enables its server part (`doh-server`).
+
+## Quick Start {#module-service-doh-server-quick-start}
+
+`doh-server` can be used as a standalone https web server (with ssl cert and key speicified) or with other reverse proxy services (such as `nginx` or `candy`). The latter approach is recommended as `doh-server` does not do OCSP Stapling.
+
+Setup a standalone instance:
+
+```nix
+services.doh-server = {
+  enable = true;
+  settings = {
+    listen = [ ":443" ];
+    upstream = [ "udp:1.1.1.1:53" ];
+    cert = "/path/to/cert.crt";
+    key = "/path/to/key.key";
+  };
+};
+```
+
+Setup with Nginx + ACME (recommanded):
+
+```nix
+services.doh-server = {
+  enable = true;
+  settings = {
+    listen = [ ":8053" ];
+    upstream = [ "udp:1.1.1.1:53" ];
+  };
+};
+
+services.nginx = {
+  enable = true;
+  virtualHosts."doh.example.com" = {
+    enableACME = true;
+    forceSSL = true;
+    http2 = true;
+    locations."/".return = 404;
+    locations."/dns-query".extraConfig = ''
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header Host $host;
+      proxy_set_header X-NginX-Proxy true;
+      proxy_http_version 1.1;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_redirect off;
+      proxy_set_header X-Forwarded-Proto $scheme;
+      proxy_read_timeout 86400;
+      proxy_pass http://127.0.0.1:8053/dns-query;
+    '';
+  };
+  # and other virtual hosts ...
+};
+
+security.acme = {
+  acceptTerms = true;
+  defaults.email = "[email protected]";
+  defaults.group = "nginx";
+};
+```
+
+See a full configuration in https://github.com/m13253/dns-over-https/blob/master/doh-server/doh-server.conf.

nixos/modules/services/networking/doh-server.nix

@@ -0,0 +1,153 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+
+let
+  cfg = config.services.doh-server;
+  toml = pkgs.formats.toml { };
+  configFile = toml.generate "config.toml" cfg.settings;
+in
+{
+  options.services.doh-server = {
+    enable = lib.mkEnableOption "DNS-over-HTTPS server";
+
+    package = lib.mkPackageOption pkgs "dns-over-https" { };
+
+    settings = lib.mkOption {
+      type = lib.types.submodule {
+        freeformType = toml.type;
+        options = {
+
+          listen = lib.mkOption {
+            type = lib.types.listOf lib.types.str;
+            default = [
+              "127.0.0.1:8053"
+              "[::1]:8053"
+            ];
+            example = [ ":443" ];
+            description = "HTTP listen address and port";
+          };
+
+          path = lib.mkOption {
+            type = lib.types.str;
+            default = "/dns-query";
+            example = "/dns-query";
+            description = "HTTP path for resolve application";
+          };
+
+          upstream = lib.mkOption {
+            type = lib.types.listOf lib.types.str;
+            default = [
+              "udp:1.1.1.1:53"
+              "udp:1.0.0.1:53"
+              "udp:8.8.8.8:53"
+              "udp:8.8.4.4:53"
+            ];
+            example = [ "udp:127.0.0.1:53" ];
+            description = ''
+              Upstream DNS resolver.
+              If multiple servers are specified, a random one will be chosen each time.
+              You can use "udp", "tcp" or "tcp-tls" for the type prefix.
+              For "udp", UDP will first be used, and switch to TCP when the server asks to or the response is too large.
+              For "tcp", only TCP will be used.
+              For "tcp-tls", DNS-over-TLS (RFC 7858) will be used to secure the upstream connection.
+            '';
+          };
+
+          timeout = lib.mkOption {
+            type = lib.types.int;
+            default = 10;
+            example = 15;
+            description = "Upstream timeout";
+          };
+
+          tries = lib.mkOption {
+            type = lib.types.int;
+            default = 3;
+            example = 5;
+            description = "Number of tries if upstream DNS fails";
+          };
+
+          verbose = lib.mkOption {
+            type = lib.types.bool;
+            default = false;
+            example = true;
+            description = "Enable logging";
+          };
+
+          log_guessed_client_ip = lib.mkOption {
+            type = lib.types.bool;
+            default = false;
+            example = true;
+            description = ''
+              Enable log IP from HTTPS-reverse proxy header: X-Forwarded-For or X-Real-IP
+              Note: http uri/useragent log cannot be controlled by this config
+            '';
+          };
+
+          ecs_allow_non_global_ip = lib.mkOption {
+            type = lib.types.bool;
+            default = false;
+            example = true;
+            description = ''
+              By default, non global IP addresses are never forwarded to upstream servers.
+              This is to prevent two things from happening:
+                1. the upstream server knowing your private LAN addresses;
+                2. the upstream server unable to provide geographically near results,
+                  or even fail to provide any result.
+              However, if you are deploying a split tunnel corporation network environment, or for any other reason you want to inhibit this behavior and allow local (eg RFC1918) address to be forwarded, change the following option to "true".
+            '';
+          };
+
+          ecs_use_precise_ip = lib.mkOption {
+            type = lib.types.bool;
+            default = false;
+            example = true;
+            description = ''
+              If ECS is added to the request, let the full IP address or cap it to 24 or 128 mask. This option is to be used only on private networks where knowledge of the terminal endpoint may be required for security purposes (eg. DNS Firewalling). Not a good option on the internet where IP address may be used to identify the user and not only the approximate location.
+            '';
+          };
+        };
+      };
+      default = { };
+      example = {
+        listen = [ ":8153" ];
+        upstream = [ "udp:127.0.0.1:53" ];
+      };
+      description = "Configuration of doh-server in toml. See example in https://github.com/m13253/dns-over-https/blob/master/doh-server/doh-server.conf";
+    };
+
+    configFile = lib.mkOption {
+      type = lib.types.path;
+      example = ~/doh-server.conf;
+      description = ''
+        The config file for the doh-server.
+        Setting this option will override any configuration applied by the `settings` option.
+      '';
+    };
+  };
+  config = lib.mkIf cfg.enable {
+    services.doh-server.configFile = lib.mkDefault (toml.generate "doh-server.conf" cfg.settings);
+    systemd.services.doh-server = {
+      description = "DNS-over-HTTPS Server";
+      documentation = [ "https://github.com/m13253/dns-over-https" ];
+      after = [ "network.target" ];
+      wantedBy = [ "multi-user.target" ];
+      serviceConfig = {
+        AmbientCapabilities = "CAP_NET_BIND_SERVICE";
+        ExecStart = "${cfg.package}/bin/doh-server -conf ${configFile}";
+        LimitNOFILE = 1048576;
+        Restart = "always";
+        RestartSec = 3;
+        Type = "simple";
+        DynamicUser = true;
+      };
+    };
+  };
+
+  meta.maintainers = with lib.maintainers; [ DictXiong ];
+  meta.doc = ./doh-server.md;
+}