From 6a82a993992d33041c655aabd8bd2c655b5f1edd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Thu, 11 Jul 2024 23:59:03 +0200
Subject: [PATCH] add troubleshooting documentation for disko-install

---
 devdoc/hosts.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/devdoc/hosts.md b/devdoc/hosts.md
index 8dd4dfe..bbfd8fb 100644
--- a/devdoc/hosts.md
+++ b/devdoc/hosts.md
@@ -100,8 +100,28 @@ $ /root/kexec/run
 
 ## Fix up broken installations with disko-install
 
-```
-nix run github:nix-community/disko#disko-install -- --mode mount --flake github:nix-community/infra/initrd-ssh#build02 --disk nvme0n1 /dev/nvme1n1 --disk nvme1n1 /dev/nvme0n1
+Disko install allows to update nixos configuration with out re-formatting, if the `--mode` parameter is set to `mount`. This assumes that the file system is still intact. `--disk` may need to be adjusted according to the concrete disko configuration. i.e. disks during installation may have different names than later in the recovery system. Use lsblk or `/dev/disk/by-partlabel` to reason about which disk is which.
+
+```console
+$ ls -la /dev/disk/by-partlabel/
+total 0
+drwxr-xr-x  2 root root 120 Jul 11 21:45 .
+drwxr-xr-x 11 root root 220 Jul 11 21:45 ..
+lrwxrwxrwx  1 root root  15 Jul 11 21:45 disk-nvme0n1-boot -> ../../nvme1n1p1
+lrwxrwxrwx  1 root root  15 Jul 11 21:45 disk-nvme0n1-ESP -> ../../nvme1n1p2
+lrwxrwxrwx  1 root root  15 Jul 11 21:45 disk-nvme0n1-zfs -> ../../nvme1n1p3
+lrwxrwxrwx  1 root root  15 Jul 11 21:45 disk-nvme1n1-zfs -> ../../nvme0n1p1
+$ lsblk
+NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
+loop0         7:0    0 310.8M  0 loop /nix/.ro-store
+loop1         7:1    0    36K  0 loop
+nvme1n1     259:0    0   1.7T  0 disk
+├─nvme1n1p1 259:3    0     1M  0 part
+├─nvme1n1p2 259:4    0     1G  0 part
+└─nvme1n1p3 259:5    0   1.7T  0 part
+nvme0n1     259:1    0   1.7T  0 disk
+└─nvme0n1p1 259:2    0   1.7T  0 part
+$ nix run github:nix-community/disko#disko-install -- --mode mount --flake github:nix-community/infra#build02 --disk nvme0n1 /dev/nvme1n1 --disk nvme1n1 /dev/nvme0n1
 ```
 
 ### Debug VM