From 2ee84ca8e2adb0ef5b5ea52ad38fe0e107893d3e Mon Sep 17 00:00:00 2001
From: jakobrs <jakobrs100@gmail.com>
Date: Wed, 17 Jun 2020 13:36:06 +0000
Subject: nixos/manual: Document `boot.debug1mounts` and clarify what `exit`
 does with `shell_on_fail` (#89365)

* nixos/manual: document boot.debug1mounts

* nixos/manual: clarify what `exit` does with shell_on_fail
---
 nixos/doc/manual/administration/boot-problems.xml | 31 ++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

(limited to 'nixos/doc/manual/administration/boot-problems.xml')

diff --git a/nixos/doc/manual/administration/boot-problems.xml b/nixos/doc/manual/administration/boot-problems.xml
index 5fa0b29e6d62..badc374ebcfd 100644
--- a/nixos/doc/manual/administration/boot-problems.xml
+++ b/nixos/doc/manual/administration/boot-problems.xml
@@ -19,9 +19,9 @@
     </term>
     <listitem>
      <para>
-      Start a root shell if something goes wrong in stage 1 of the boot process
-      (the initial ramdisk). This is disabled by default because there is no
-      authentication for the root shell.
+      Allows the user to start a root shell if something goes wrong in stage 1
+      of the boot process (the initial ramdisk). This is disabled by default
+      because there is no authentication for the root shell.
      </para>
     </listitem>
    </varlistentry>
@@ -49,6 +49,22 @@
      </para>
     </listitem>
    </varlistentry>
+   <varlistentry>
+    <term>
+     <literal>boot.debug1mounts</literal>
+    </term>
+    <listitem>
+     <para>
+      Like <literal>boot.debug1</literal> or
+      <literal>boot.debug1devices</literal>, but runs stage1 until all
+      filesystems that are mounted during initrd are mounted (see
+      <option><link linkend="opt-fileSystems._name__.neededForBoot">neededForBoot</link></option>
+      ). As a motivating example, this could be useful if you've forgotten to set
+      <option><link linkend="opt-fileSystems._name__.neededForBoot">neededForBoot</link></option>
+      on a file system.
+     </para>
+    </listitem>
+   </varlistentry>
    <varlistentry>
     <term>
      <literal>boot.trace</literal>
@@ -90,6 +106,15 @@
   <manvolnum>1</manvolnum></citerefentry>.
  </para>
 
+ <para>
+  Notice that for <literal>boot.shell_on_fail</literal>,
+  <literal>boot.debug1</literal>, <literal>boot.debug1devices</literal>, and
+  <literal>boot.debug1mounts</literal>, if you did <emphasis>not</emphasis>
+  select "start the new shell as pid 1", and you <literal>exit</literal> from
+  the new shell, boot will proceed normally from the point where it failed, as
+  if you'd chosen "ignore the error and continue".
+ </para>
+
  <para>
   If no login prompts or X11 login screens appear (e.g. due to hanging
   dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start
-- 
cgit 1.4.1