nixpkgs-suyu/nixos/doc/manual/administration/boot-problems.xml

<section xmlns="http://docbook.org/ns/docbook"
        xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns:xi="http://www.w3.org/2001/XInclude"
        version="5.0"
        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:
  <variablelist>
   <varlistentry>
    <term>
     <literal>boot.shell_on_fail</literal>
    </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.
     </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 <filename>/proc</filename> and
      <filename>/sys</filename>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <literal>boot.debug1devices</literal>
    </term>
    <listitem>
     <para>
      Like <literal>boot.debug1</literal>, but with some more devices loaded.
      This may help with e.g. making the keyboard work.
     </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 <command>sulogin</command> 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 systemd.log_target=console</literal>
    </term>
    <listitem>
     <para>
      Make systemd very verbose and send log messages to the console instead of
      the journal.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
  For more parameters recognised by systemd, see <citerefentry>
  <refentrytitle>systemd</refentrytitle>
  <manvolnum>1</manvolnum></citerefentry>.
 </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
  <command>agetty</command> login prompts should appear eventually unless
  something is very wrong.)
 </para>
</section>