From 98c5296d1eb55647a20f656696c75f0c608787f2 Mon Sep 17 00:00:00 2001
From: Michael Walker <mike@barrucadu.co.uk>
Date: Sun, 15 Oct 2023 16:47:39 +0100
Subject: [PATCH] Document `erase-your-darlings` module and options

---
 shared/erase-your-darlings/default.nix | 10 +++++
 shared/erase-your-darlings/options.nix | 54 +++++++++++++++++++++++---
 2 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/shared/erase-your-darlings/default.nix b/shared/erase-your-darlings/default.nix
index b77d2ac8..9bf4752c 100644
--- a/shared/erase-your-darlings/default.nix
+++ b/shared/erase-your-darlings/default.nix
@@ -1,3 +1,13 @@
+# Wipe `/` on boot, inspired by ["erase your darlings"][].
+#
+# This module is responsible for configuring standard NixOS options and
+# services, all of my modules have their own `erase-your-darlings.nix` file
+# which makes any changes that they need.
+#
+# This requires a setting up ZFS in a specific way when first installing NixOS.
+# See the [README](./index.html#optional-configure-wiping--on-boot).
+#
+# ["erase your darlings"]: https://grahamc.com/blog/erase-your-darlings/
 { config, lib, ... }:
 
 with lib;
diff --git a/shared/erase-your-darlings/options.nix b/shared/erase-your-darlings/options.nix
index b4fdeee5..ee933400 100644
--- a/shared/erase-your-darlings/options.nix
+++ b/shared/erase-your-darlings/options.nix
@@ -4,10 +4,54 @@ with lib;
 
 {
   options.nixfiles.eraseYourDarlings = {
-    enable = mkOption { type = types.bool; default = false; };
-    barrucaduPasswordFile = mkOption { type = types.str; };
-    rootSnapshot = mkOption { type = types.str; default = "local/volatile/root@blank"; };
-    persistDir = mkOption { type = types.path; default = "/persist"; };
-    machineId = mkOption { type = types.str; };
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Enable the `erase-your-darlings` module.
+      '';
+    };
+
+    barrucaduPasswordFile = mkOption {
+      type = types.str;
+      description = mdDoc ''
+        Path to a file containing the hashed password for `barrucadu`.  This
+        file must be available in early boot.
+
+        If using [sops-nix](https://github.com/Mic92/sops-nix) set the
+        `neededForUsers` option on the secret.
+      '';
+    };
+
+    rootSnapshot = mkOption {
+      type = types.str;
+      default = "local/volatile/root@blank";
+      description = mdDoc ''
+        ZFS snapshot to roll back to on boot.
+      '';
+    };
+
+    persistDir = mkOption {
+      type = types.path;
+      default = "/persist";
+      description = mdDoc ''
+        Persistent directory which will not be erased.  This must be on a
+        different ZFS dataset that will not be wiped when rolling back to the
+        `rootSnapshot`.
+
+        This module moves various files from `/` to here.
+      '';
+    };
+
+    machineId = mkOption {
+      type = types.str;
+      example = "64b1b10f3bef4616a7faf5edf1ef3ca5";
+      description = mdDoc ''
+        An arbitrary 32-character hexadecimal string, used to identify the host.
+        This is needed for journalctl logs from previous boots to be accessible.
+
+        See [the systemd documentation](https://www.freedesktop.org/software/systemd/man/machine-id.html).
+      '';
+    };
   };
 }