From 42a22e89b7d4af380eabf60465fe0fd6926a247f Mon Sep 17 00:00:00 2001
From: Simon Bruder <simon@sbruder.de>
Date: Wed, 15 Feb 2023 11:35:59 +0100
Subject: [PATCH] initrd-ssh: Improve module documentation

---
 modules/initrd-ssh.nix | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/modules/initrd-ssh.nix b/modules/initrd-ssh.nix
index afda98b..4d1a23d 100644
--- a/modules/initrd-ssh.nix
+++ b/modules/initrd-ssh.nix
@@ -1,7 +1,23 @@
-# For network to work in initrd, either pass the `ip=` kernel parameter or
-# enable networking.useDHCP. You also have to add the required kernel modules
-# for the network card to boot.initrd.availableKernelModules. Also see the
-# instructions on how to add a host key to password-store.
+# To enable this on a host, you have to do the following:
+# For network to work in initrd,
+# either pass the `ip=` kernel parameter or enable networking.useDHCP.
+# You also have to add the required kernel modules for the network adapter to `boot.initrd.availableKernelModules`
+# (if it is not loaded by default).
+# Then, you can set `boot.initrd.network.enable=true`,
+# which enables networking in initrd.
+# SSH in the initrd is enabled by this module automatically once networking is enabled.
+# To be able to log in,
+# you have to generate an SSH host key for the system (see the comments in the module on how to)
+# and copy it to that host.
+# It is then recommended to add a new `<host>-initrd`-entry to `modules/ssh.nix`
+# to ensure the key is known and trusted by default on all other hosts.
+# The host also needs a valid entry in `machines/default.nix`
+# with `targetHost` set.
+# If necessary, also set `unlockOverV4`,
+# which forces the SSH connection to use IPv4
+# (useful if the network of the host does not do SLAAC).
+# If all that is done,
+# remote unlocking should be possible by running `nix run .#unlock/host`
 { config, lib, ... }:
 {
   boot.initrd.network = {