Document resolved module and options

barrucadu · Oct 15, 2023 · 37de90f · 37de90f
1 parent 66e8ea4
commit 37de90f
Show file tree

Hide file tree

Showing 2 changed files with 105 additions and 12 deletions.
diff --git a/shared/resolved/default.nix b/shared/resolved/default.nix
@@ -1,3 +1,9 @@
+# [resolved][] is a recursive DNS server for LAN DNS.
+#
+# Enabling this module also provisions a [Grafana][] dashboard.
+#
+# [resolved]: https://github.com/barrucadu/resolved
+# [Grafana]: https://grafana.com/
 { config, lib, pkgs, ... }:
 
 with lib;

diff --git a/shared/resolved/options.nix b/shared/resolved/options.nix
@@ -4,17 +4,104 @@ with lib;
 
 {
   options.nixfiles.resolved = {
-    enable = mkOption { type = types.bool; default = false; };
-    address = mkOption { type = types.str; default = "0.0.0.0:53"; };
-    metrics_address = mkOption { type = types.str; default = "127.0.0.1:9420"; };
-    authoritative_only = mkOption { type = types.bool; default = false; };
-    protocol_mode = mkOption { type = types.str; default = "only-v4"; };
-    forward_address = mkOption { type = types.nullOr types.str; default = null; };
-    cache_size = mkOption { type = types.int; default = 512; };
-    hosts_dirs = mkOption { type = types.listOf types.str; default = [ ]; };
-    zones_dirs = mkOption { type = types.listOf types.str; default = [ ]; };
-    use_default_zones = mkOption { type = types.bool; default = true; };
-    log_level = mkOption { type = types.str; default = "dns_resolver=info,resolved=info"; };
-    log_format = mkOption { type = types.str; default = "json,no-time"; };
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Enable the `resolved` service.
+      '';
+    };
+
+    address = mkOption {
+      type = types.str;
+      default = "0.0.0.0:53";
+      description = mdDoc ''
+        Address to listen on.
+      '';
+    };
+
+    metrics_address = mkOption {
+      type = types.str;
+      default = "127.0.0.1:9420";
+      description = mdDoc ''
+        Address to listen on to serve Prometheus metrics.
+      '';
+    };
+
+    authoritative_only = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Only answer queries for which this server is authoritative: do not
+        perform recursive or forwarding resolution.
+      '';
+    };
+
+    protocol_mode = mkOption {
+      type = types.str;
+      default = "only-v4";
+      description = mdDoc ''
+        How to choose between connecting to upstream nameservers over IPv4 or
+        IPv6 when acting as a recursive resolver.
+      '';
+    };
+
+    forward_address = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = mdDoc ''
+        Act as a forwarding resolver, not a recursive resolver: forward queries
+        which can't be answered from local state to this nameserver and cache
+        the result.
+      '';
+    };
+
+    cache_size = mkOption {
+      type = types.int;
+      default = 512;
+      description = mdDoc ''
+        How many records to hold in the cache.
+      '';
+    };
+
+    hosts_dirs = mkOption {
+      type = types.listOf types.str;
+      default = [ ];
+      description = mdDoc ''
+        List of directories to read hosts files from.
+      '';
+    };
+
+    zones_dirs = mkOption {
+      type = types.listOf types.str;
+      default = [ ];
+      description = mdDoc ''
+        List of directories to read zone files from.
+      '';
+    };
+
+    use_default_zones = mkOption {
+      type = types.bool;
+      default = true;
+      description = mdDoc ''
+        Include the default zone files.
+      '';
+    };
+
+    log_level = mkOption {
+      type = types.str;
+      default = "dns_resolver=info,resolved=info";
+      description = mdDoc ''
+        Verbosity of the log messages.
+      '';
+    };
+
+    log_format = mkOption {
+      type = types.str;
+      default = "json,no-time";
+      description = mdDoc ''
+        Format of the log messages.
+      '';
+    };
   };
 }