nixos/pdns-recursor: deprecate settings, add yaml-settings (#406534)

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

@@ -273,6 +273,13 @@ Alongside many enhancements to NixOS modules and general system improvements, th
   [not recommended by upstream](https://docs.nextcloud.com/server/30/admin_manual/installation/system_requirements.html)
   and thus doesn't qualify as default.
 
+- PowerDNS Recursor has been updated to version 5.1.2, which comes with a new YAML configuration format (`recursor.yml`)
+  and deprecates the previous format (`recursor.conf`). Accordingly, the NixOS option `services.pdns-recursor.settings`
+  has been renamed to [old-settings](#opt-services.pdns-recursor.old-settings) and will be provided for backward compatibility
+  until the next NixOS release. Users are asked to migrate their settings to the new [yaml-settings](#opt-services.pdns-recursor.old-settings)
+  option following this [guide](https://doc.powerdns.com/recursor/appendices/yamlconversion.html).
+  Note that options other than `services.pdns-recursor.settings` are unaffacted by this change.
+
 - Nextcloud's default FPM pool settings have been increased according to upstream recommentations. It's advised
   to review the new defaults and description of
   [](#opt-services.nextcloud.poolSettings).

nixos/modules/services/networking/pdns-recursor.nix

@@ -38,12 +38,34 @@ let
     else
       "";
 
-  configDir = pkgs.writeTextDir "recursor.conf" (
+  settingsFormat = pkgs.formats.yaml { };
-    concatStringsSep "\n" (flip mapAttrsToList cfg.settings (name: val: "${name}=${serialize val}"))
-  );
 
   mkDefaultAttrs = mapAttrs (n: v: mkDefault v);
 
+  mkForwardZone = mapAttrsToList (
+    zone: uri: {
+      inherit zone;
+      forwarders = [ uri ];
+    }
+  );
+
+  configFile =
+    if cfg.old-settings != { } then
+      # Convert recursor.conf to recursor.yml and merge it
+      let
+        conf = pkgs.writeText "recursor.conf" (
+          concatStringsSep "\n" (mapAttrsToList (name: val: "${name}=${serialize val}") cfg.old-settings)
+        );
+
+        yaml = settingsFormat.generate "recursor.yml" cfg.yaml-settings;
+      in
+      pkgs.runCommand "recursor-merged.yml" { } ''
+        ${pkgs.pdns-recursor}/bin/rec_control show-yaml --config ${conf} > override.yml
+        ${pkgs.yq-go}/bin/yq '. *= load("override.yml")' ${yaml} > $out
+      ''
+    else
+      settingsFormat.generate "recursor.yml" cfg.yaml-settings;
+
 in
 {
   options.services.pdns-recursor = {
@@ -175,7 +197,7 @@ in
       '';
     };
 
-    settings = mkOption {
+    old-settings = mkOption {
       type = configType;
       default = { };
       example = literalExpression ''
@@ -184,11 +206,34 @@ in
           log-common-errors = true;
         }
       '';
+      description = ''
+        Older PowerDNS Recursor settings. Use this option to configure
+        Recursor settings not exposed in a NixOS option or to bypass one.
+        See the full documentation at
+        <https://doc.powerdns.com/recursor/settings.html>
+        for the available options.
+
+        ::: {.warning}
+        This option is provided for backward compatibility only
+        and will be removed in the next release of NixOS.
+        :::
+      '';
+    };
+
+    yaml-settings = mkOption {
+      type = settingsFormat.type;
+      default = { };
+      example = literalExpression ''
+        {
+          loglevel = 8;
+          log-common-errors = true;
+        }
+      '';
       description = ''
         PowerDNS Recursor settings. Use this option to configure Recursor
         settings not exposed in a NixOS option or to bypass one.
         See the full documentation at
-        <https://doc.powerdns.com/recursor/settings.html>
+        <https://doc.powerdns.com/recursor/yamlsettings.html>
         for the available options.
       '';
     };
@@ -205,42 +250,44 @@ in
 
   config = mkIf cfg.enable {
 
-    environment.etc."pdns-recursor".source = configDir;
+    environment.etc."/pdns-recursor/recursor.yml".source = configFile;
 
-    services.pdns-recursor.settings = mkDefaultAttrs {
+    services.pdns-recursor.yaml-settings = {
-      local-address = cfg.dns.address;
+      incoming = mkDefaultAttrs {
-      local-port = cfg.dns.port;
+        listen = cfg.dns.address;
-      allow-from = cfg.dns.allowFrom;
+        port = cfg.dns.port;
+        allow_from = cfg.dns.allowFrom;
+      };
 
-      webserver-address = cfg.api.address;
+      webservice = mkDefaultAttrs {
-      webserver-port = cfg.api.port;
+        address = cfg.api.address;
-      webserver-allow-from = cfg.api.allowFrom;
+        port = cfg.api.port;
+        allow_from = cfg.api.allowFrom;
+      };
 
-      forward-zones = mapAttrsToList (zone: uri: "${zone}.=${uri}") cfg.forwardZones;
+      recursor = mkDefaultAttrs {
-      forward-zones-recurse = mapAttrsToList (zone: uri: "${zone}.=${uri}") cfg.forwardZonesRecurse;
+        forward_zones = mkForwardZone cfg.forwardZones;
-      export-etc-hosts = cfg.exportHosts;
+        forward_zones_recurse = mkForwardZone cfg.forwardZonesRecurse;
-      dnssec = cfg.dnssecValidation;
+        export_etc_hosts = cfg.exportHosts;
-      serve-rfc1918 = cfg.serveRFC1918;
+        serve_rfc1918 = cfg.serveRFC1918;
-      lua-config-file = pkgs.writeText "recursor.lua" cfg.luaConfig;
+        lua_config_file = pkgs.writeText "recursor.lua" cfg.luaConfig;
+        daemon = false;
+        write_pid = false;
+      };
 
-      daemon = false;
+      dnssec = mkDefaultAttrs {
-      write-pid = false;
+        validation = cfg.dnssecValidation;
-      log-timestamp = false;
+      };
-      disable-syslog = true;
+
+      logging = mkDefaultAttrs {
+        timestamp = false;
+        disable_syslog = true;
+      };
     };
 
     systemd.packages = [ pkgs.pdns-recursor ];
 
-    systemd.services.pdns-recursor = {
+    systemd.services.pdns-recursor.wantedBy = [ "multi-user.target" ];
-      wantedBy = [ "multi-user.target" ];
-
-      serviceConfig = {
-        ExecStart = [
-          ""
-          "${pkgs.pdns-recursor}/bin/pdns_recursor --config-dir=${configDir}"
-        ];
-      };
-    };
 
     users.users.pdns-recursor = {
       isSystemUser = true;
@@ -250,6 +297,15 @@ in
 
     users.groups.pdns-recursor = { };
 
+    warnings = lib.optional (cfg.old-settings != { }) ''
+      pdns-recursor has changed its configuration file format from pdns-recursor.conf
+      (mapped to `services.pdns-recursor.old-settings`) to the newer pdns-recursor.yml
+      (mapped to `services.pdns-recursor.yaml-settings`).
+
+      Support for the older format will be removed in a future version, so please migrate
+      your settings over. See <https://doc.powerdns.com/recursor/yamlsettings.html>.
+    '';
+
   };
 
   imports = [
@@ -258,6 +314,19 @@ in
       "pdns-recursor"
       "extraConfig"
     ] "To change extra Recursor settings use services.pdns-recursor.settings instead.")
+
+    (mkRenamedOptionModule
+      [
+        "services"
+        "pdns-recursor"
+        "settings"
+      ]
+      [
+        "services"
+        "pdns-recursor"
+        "old-settings"
+      ]
+    )
   ];
 
   meta.maintainers = with lib.maintainers; [ rnhmjoj ];

nixos/tests/all-tests.nix

@@ -1019,7 +1019,7 @@ in
   paperless = handleTest ./paperless.nix { };
   parsedmarc = handleTest ./parsedmarc { };
   password-option-override-ordering = handleTest ./password-option-override-ordering.nix { };
-  pdns-recursor = handleTest ./pdns-recursor.nix { };
+  pdns-recursor = runTest ./pdns-recursor.nix;
   pds = handleTest ./pds.nix { };
   peerflix = handleTest ./peerflix.nix { };
   peering-manager = handleTest ./web-apps/peering-manager.nix { };

nixos/tests/pdns-recursor.nix

@@ -1,20 +1,25 @@
-import ./make-test-python.nix (
+{ lib, pkgs, ... }:
-  { pkgs, ... }:
-  {
-    name = "powerdns-recursor";
 
-    nodes.server =
+{
-      { ... }:
+  name = "powerdns-recursor";
-      {
+  meta.maintainers = with lib.maintainers; [ rnhmjoj ];
-        services.pdns-recursor.enable = true;
-        services.pdns-recursor.exportHosts = true;
-        networking.hosts."192.0.2.1" = [ "example.com" ];
-      };
 
-    testScript = ''
+  nodes.server = {
+    services.pdns-recursor.enable = true;
+    services.pdns-recursor.exportHosts = true;
+    services.pdns-recursor.old-settings.dnssec-log-bogus = true;
+    networking.hosts."192.0.2.1" = [ "example.com" ];
+  };
+
+  testScript = ''
+    with subtest("pdns-recursor is running"):
       server.wait_for_unit("pdns-recursor")
       server.wait_for_open_port(53)
+
+    with subtest("can resolve names"):
       assert "192.0.2.1" in server.succeed("host example.com localhost")
-    '';
+
-  }
+    with subtest("old-settings have been merged in"):
-)
+      server.succeed("${lib.getExe pkgs.yq-go} -e .dnssec.log_bogus /etc/pdns-recursor/recursor.yml")
+  '';
+}