pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="sec-boot-problems">
6
7<title>Boot Problems</title>
8
9<para>If NixOS fails to boot, there are a number of kernel command
10line parameters that may help you to identify or fix the issue. You
11can add these parameters in the GRUB boot menu by pressing “e” to
12modify the selected boot entry and editing the line starting with
13<literal>linux</literal>. The following are some useful kernel command
14line parameters that are recognised by the NixOS boot scripts or by
15systemd:
16
17<variablelist>
18
19 <varlistentry><term><literal>boot.shell_on_fail</literal></term>
20 <listitem><para>Start a root shell if something goes wrong in
21 stage 1 of the boot process (the initial ramdisk). This is
22 disabled by default because there is no authentication for the
23 root shell.</para></listitem>
24 </varlistentry>
25
26 <varlistentry><term><literal>boot.debug1</literal></term>
27 <listitem><para>Start an interactive shell in stage 1 before
28 anything useful has been done. That is, no modules have been
29 loaded and no file systems have been mounted, except for
30 <filename>/proc</filename> and
31 <filename>/sys</filename>.</para></listitem>
32 </varlistentry>
33
34 <varlistentry><term><literal>boot.trace</literal></term>
35 <listitem><para>Print every shell command executed by the stage 1
36 and 2 boot scripts.</para></listitem>
37 </varlistentry>
38
39 <varlistentry><term><literal>single</literal></term>
40 <listitem><para>Boot into rescue mode (a.k.a. single user mode).
41 This will cause systemd to start nothing but the unit
42 <literal>rescue.target</literal>, which runs
43 <command>sulogin</command> to prompt for the root password and
44 start a root login shell. Exiting the shell causes the system to
45 continue with the normal boot process.</para></listitem>
46 </varlistentry>
47
48 <varlistentry><term><literal>systemd.log_level=debug systemd.log_target=console</literal></term>
49 <listitem><para>Make systemd very verbose and send log messages to
50 the console instead of the journal.</para></listitem>
51 </varlistentry>
52
53</variablelist>
54
55For more parameters recognised by systemd, see
56<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
57
58<para>If no login prompts or X11 login screens appear (e.g. due to
59hanging dependencies), you can press Alt+ArrowUp. If you’re lucky,
60this will start rescue mode (described above). (Also note that since
61most units have a 90-second timeout before systemd gives up on them,
62the <command>agetty</command> login prompts should appear eventually
63unless something is very wrong.)</para>
64
65</section>