1 files changed, 38 insertions, 0 deletions
diff --git a/doc/rescue.md b/doc/rescue.md
new file mode 100644
index 0000000..431246a
--- /dev/null
+++ b/doc/rescue.md
@@ -0,0 +1,38 @@
+# Using NixOS Installer as Rescue Environment
+
+As with most Linux distributions, you will need to mount your
+core file systems under `/mnt`.  You don't need to worry about
+the virtual file systems, just the real ones, including any boot
+or ESP partitions.  You can also skip swap for now.
+
+Once you are done with that, you can simply type `nixos-enter` to
+pivot into the chroot.  You will probably also want to `unset
+SUDO_USER` if you used `sudo -i` or something similar, as having
+it set will probably cause issues when trying to run
+`nixos-rebuild`.
+
+Should you need to manually set up the rescue environment, beyond
+the physical mounts already done above, you will also need to run
+the following:
+
+```
+mount -o bind /dev /mnt/dev
+mount -o bind /proc /mnt/proc
+mount -o bind /sys /mnt/sys
+chroot /mnt /nix/var/nix/profiles/system/activate
+chroot /mnt /run/current-system/sw/bin/bash
+```
+
+Lastly, should you get the following error when trying to run
+`nixos-rebuild switch` within your rescue environment, usually
+caused by systemd as the bootloader:
+
+```
+error: System has not been booted with systemd as init system (PID 1). Can't operate.
+```
+
+you can instead try running `nixos-rebuild boot`.  If that also
+fails, you can try appending those commands with
+`NIXOS_SWITCH_USE_DIRTY_ENV=1` which might work around the
+problem.  And should none of that work, you can try to use
+`nixos-install` as a last resort.