INSTALLATION.md

@@ -102,10 +102,62 @@ nixos-install
 
 ## how to deploy the initial config
 - Don't forget to install the bootloader, if you changed it since `nixos-install`
+- The fresh install has no flakes and no git yet, a temporary shell is enough
+- If the installer iso is older than the flake's nixpkgs, `--no-reexec` keeps
+  `nixos-rebuild` from re-executing a newer version of itself, which can fail
+  against the older systemd of the fresh install (only needed once)
+- Set a password for the user before rebooting, `users.nix` doesn't set one
 ```bash
-$ sudo nixos-rebuild --install-bootloader switch --flake .#host_name
+$ export NIX_CONFIG="experimental-features = nix-command flakes"
+$ nix-shell -p git
+$ sudo nixos-rebuild --install-bootloader boot --flake .#host_name --no-reexec
+$ sudo passwd aaron
 ```
 
+## how to enable secure boot
+Secure Boot uses lanzaboote with our own keys, see `modules/nixos/lanzaboote.nix`.
+Do this after the initial config is deployed and boots.
+
+1. create the keys, before the first rebuild with the lanzaboote module
+```bash
+# the keys end up in /var/lib/sbctl, they never leave the host
+$ sudo nix run nixpkgs#sbctl -- create-keys
+```
+
+2. import `modules/nixos/lanzaboote.nix` in the host's `configuration.nix`, rebuild and check the signatures
+```bash
+$ sudo nixos-rebuild switch --flake .#host_name
+# EFI/Linux/*.efi and the bootloader must be signed, kernels in EFI/nixos
+# are not, lanzaboote checks them by hash
+$ sudo sbctl verify
+```
+
+3. reboot once with Secure Boot still disabled, to make sure the new entries boot
+
+4. in the firmware (F2), erase all Secure Boot keys, then boot nixos again
+```bash
+# "Setup Mode: ✗ Enabled", the ✗ only means the state is insecure
+$ sudo sbctl status
+```
+
+5. enroll the keys
+```bash
+# only our own keys, no microsoft keys
+$ sudo sbctl enroll-keys
+```
+- sbctl refuses if the TPM eventlog shows option ROMs (e.g. a dedicated gpu).
+  Don't force it, either trust exactly those with `--tpm-eventlog` or
+  microsoft's keys with `--microsoft`. Without either, the firmware may not
+  start the device, in the worst case the machine doesn't boot at all.
+
+6. enable Secure Boot in the firmware and set a firmware password, then check
+```bash
+$ bootctl status | grep "Secure Boot"   # enabled (user)
+$ sudo sbctl status                     # Secure Boot: ✓ Enabled
+```
+- If it doesn't boot anymore, disabling Secure Boot in the firmware boots as before
+- Losing the keys isn't fatal: erase the keys in the firmware and start over at step 1
+
 ## how to upgrade the system
 ```bash
 $ cd /path/to/repo