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