Add howto to repair nixos installations

docs/howtos/INDEX.md

@@ -12,6 +12,8 @@
 
 [Using your own kexec image](./custom-kexec.md)
 
+[Repair installations without wiping data](./disko-modes.md)
+
 [Secrets and full disk encryption](./secrets.md)
 
 [Use without flakes](./use-without-flakes.md)

docs/howtos/disko-modes.md

@@ -0,0 +1,19 @@
+# Repair installations without wiping data
+
+By default, nixos-anywhere will reformat all configured disks before running the
+installation. However it is also possible to mount the filesystems of an
+existing installation and run `nixos-install`. This is useful to recover from a
+mis-configured NixOS installation by first booting into a NixOS installer or
+recovery system.
+
+To only mount existing filesystems, add `--disko-mode mount` to
+`nixos-anywhere`:
+
+```
+nix run github:nix-community/nixos-anywhere -- --disko-mode mount --flake <path to configuration>#<configuration name> root@<ip address>
+```
+
+1. This will first boot into a nixos-installer
+2. Mounts disks with disko
+3. Runs nixos-install based on the provided flake
+4. Reboots the machine.

docs/quickstart.md

@@ -232,13 +232,13 @@ If you also need to generate hardware configuration amend flags for
 nixos-generate-config:
 
 ```
-nix run --generate-hardware-config nixos-generate-config ./hardware-configuration.nix github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> root@<ip address>
+nix run github:nix-community/nixos-anywhere -- --generate-hardware-config nixos-generate-config ./hardware-configuration.nix --flake <path to configuration>#<configuration name> root@<ip address>
 ```
 
 Or these flags if you are using nixos-facter instead:
 
 ```
-nix run --generate-hardware-config nixos-facter ./facter.json github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> root@<ip address>
+nix run github:nix-community/nixos-anywhere -- --generate-hardware-config nixos-facter ./facter.json  --flake <path to configuration>#<configuration name> root@<ip address>
 ```
 
 Adjust the location of `./hardware-configuration.nix` and `./facter.json`

docs/reference.md

@@ -74,11 +74,11 @@ Options:
   disko: first unmount and destroy all filesystems on the disks we want to format, then run the create and mount mode
   install: install the system
   reboot: reboot the machine
-* --disko-mode create|mount|disko
-  set the disko mode to create, mount or destroy. Default is disko.
-  format: create partition tables, zpools, lvms, raids and filesystems (Experimental: Can be run increntally, but use with caution and good backups)
-  mount: mount the partition at the specified root-mountpoint
+* --disko-mode disko|mount|format
+  set the disko mode to format, mount or destroy. Default is disko.
   disko: first unmount and destroy all filesystems on the disks we want to format, then run the create and mount mode
+  mount: mount the partition at the specified root-mountpoint
+  format: create partition tables, zpools, lvms, raids and filesystems (Experimental: Can be run increntally, but use with caution and good backups)
 ```
 
 ## Explanation of known error messages

src/nixos-anywhere.sh

@@ -117,11 +117,11 @@ Options:
   disko: first unmount and destroy all filesystems on the disks we want to format, then run the create and mount mode
   install: install the system
   reboot: reboot the machine
-* --disko-mode create|mount|disko
-  set the disko mode to create, mount or destroy. Default is disko.
-  format: create partition tables, zpools, lvms, raids and filesystems (Experimental: Can be run increntally, but use with caution and good backups)
-  mount: mount the partition at the specified root-mountpoint
+* --disko-mode disko|mount|format
+  set the disko mode to format, mount or destroy. Default is disko.
   disko: first unmount and destroy all filesystems on the disks we want to format, then run the create and mount mode
+  mount: mount the partition at the specified root-mountpoint
+  format: create partition tables, zpools, lvms, raids and filesystems (Experimental: Can be run increntally, but use with caution and good backups)
 USAGE
 }
 
@@ -209,11 +209,11 @@ parseArgs() {
       ;;
     --disko-mode)
       case "$2" in
-      create | mount | disko)
+      format | mount | disko)
         diskoMode=$2
         ;;
       *)
-        abort "Supported values for --disko-mode create, mount, disko. Unknown mode : $2"
+        abort "Supported values for --disko-mode are disko, mount and format. Unknown mode : $2"
         ;;
       esac