summary refs log tree commit diff
path: root/nixos/doc/manual/from_md/administration/boot-problems.section.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/from_md/administration/boot-problems.section.xml')
-rw-r--r--nixos/doc/manual/from_md/administration/boot-problems.section.xml144
1 files changed, 144 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/administration/boot-problems.section.xml b/nixos/doc/manual/from_md/administration/boot-problems.section.xml
new file mode 100644
index 00000000000..144661c86eb
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/boot-problems.section.xml
@@ -0,0 +1,144 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-boot-problems">
+  <title>Boot Problems</title>
+  <para>
+    If NixOS fails to boot, there are a number of kernel command line
+    parameters that may help you to identify or fix the issue. You can
+    add these parameters in the GRUB boot menu by pressing “e” to modify
+    the selected boot entry and editing the line starting with
+    <literal>linux</literal>. The following are some useful kernel
+    command line parameters that are recognised by the NixOS boot
+    scripts or by systemd:
+  </para>
+  <variablelist>
+    <varlistentry>
+      <term>
+        <literal>boot.shell_on_fail</literal>
+      </term>
+      <listitem>
+        <para>
+          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>
+    <varlistentry>
+      <term>
+        <literal>boot.debug1</literal>
+      </term>
+      <listitem>
+        <para>
+          Start an interactive shell in stage 1 before anything useful
+          has been done. That is, no modules have been loaded and no
+          file systems have been mounted, except for
+          <literal>/proc</literal> and <literal>/sys</literal>.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>boot.debug1devices</literal>
+      </term>
+      <listitem>
+        <para>
+          Like <literal>boot.debug1</literal>, but runs stage1 until
+          kernel modules are loaded and device nodes are created. This
+          may help with e.g. making the keyboard work.
+        </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
+          <link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link>).
+          As a motivating example, this could be useful if you’ve
+          forgotten to set
+          <link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link>
+          on a file system.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>boot.trace</literal>
+      </term>
+      <listitem>
+        <para>
+          Print every shell command executed by the stage 1 and 2 boot
+          scripts.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>single</literal>
+      </term>
+      <listitem>
+        <para>
+          Boot into rescue mode (a.k.a. single user mode). This will
+          cause systemd to start nothing but the unit
+          <literal>rescue.target</literal>, which runs
+          <literal>sulogin</literal> to prompt for the root password and
+          start a root login shell. Exiting the shell causes the system
+          to continue with the normal boot process.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>systemd.log_level=debug</literal>
+        <literal>systemd.log_target=console</literal>
+      </term>
+      <listitem>
+        <para>
+          Make systemd very verbose and send log messages to the console
+          instead of the journal. For more parameters recognised by
+          systemd, see systemd(1).
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+  <para>
+    In addition, these arguments are recognised by the live image only:
+  </para>
+  <variablelist>
+    <varlistentry>
+      <term>
+        <literal>live.nixos.passwd=password</literal>
+      </term>
+      <listitem>
+        <para>
+          Set the password for the <literal>nixos</literal> live user.
+          This can be used for SSH access if there are issues using the
+          terminal.
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+  <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 role="strong">not</emphasis> select <quote>start the new
+    shell as pid 1</quote>, and you <literal>exit</literal> from the new
+    shell, boot will proceed normally from the point where it failed, as
+    if you’d chosen <quote>ignore the error and continue</quote>.
+  </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 rescue mode (described above). (Also note that since most
+    units have a 90-second timeout before systemd gives up on them, the
+    <literal>agetty</literal> login prompts should appear eventually
+    unless something is very wrong.)
+  </para>
+</section>