pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-boot-problems">
2 <title>Boot Problems</title>
3 <para>
4 If NixOS fails to boot, there are a number of kernel command line
5 parameters that may help you to identify or fix the issue. You can
6 add these parameters in the GRUB boot menu by pressing “e” to modify
7 the selected boot entry and editing the line starting with
8 <literal>linux</literal>. The following are some useful kernel
9 command line parameters that are recognised by the NixOS boot
10 scripts or by systemd:
11 </para>
12 <variablelist>
13 <varlistentry>
14 <term>
15 <literal>boot.shell_on_fail</literal>
16 </term>
17 <listitem>
18 <para>
19 Allows the user to start a root shell if something goes wrong
20 in stage 1 of the boot process (the initial ramdisk). This is
21 disabled by default because there is no authentication for the
22 root shell.
23 </para>
24 </listitem>
25 </varlistentry>
26 <varlistentry>
27 <term>
28 <literal>boot.debug1</literal>
29 </term>
30 <listitem>
31 <para>
32 Start an interactive shell in stage 1 before anything useful
33 has been done. That is, no modules have been loaded and no
34 file systems have been mounted, except for
35 <literal>/proc</literal> and <literal>/sys</literal>.
36 </para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term>
41 <literal>boot.debug1devices</literal>
42 </term>
43 <listitem>
44 <para>
45 Like <literal>boot.debug1</literal>, but runs stage1 until
46 kernel modules are loaded and device nodes are created. This
47 may help with e.g. making the keyboard work.
48 </para>
49 </listitem>
50 </varlistentry>
51 <varlistentry>
52 <term>
53 <literal>boot.debug1mounts</literal>
54 </term>
55 <listitem>
56 <para>
57 Like <literal>boot.debug1</literal> or
58 <literal>boot.debug1devices</literal>, but runs stage1 until
59 all filesystems that are mounted during initrd are mounted
60 (see
61 <link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link>).
62 As a motivating example, this could be useful if you’ve
63 forgotten to set
64 <link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link>
65 on a file system.
66 </para>
67 </listitem>
68 </varlistentry>
69 <varlistentry>
70 <term>
71 <literal>boot.trace</literal>
72 </term>
73 <listitem>
74 <para>
75 Print every shell command executed by the stage 1 and 2 boot
76 scripts.
77 </para>
78 </listitem>
79 </varlistentry>
80 <varlistentry>
81 <term>
82 <literal>single</literal>
83 </term>
84 <listitem>
85 <para>
86 Boot into rescue mode (a.k.a. single user mode). This will
87 cause systemd to start nothing but the unit
88 <literal>rescue.target</literal>, which runs
89 <literal>sulogin</literal> to prompt for the root password and
90 start a root login shell. Exiting the shell causes the system
91 to continue with the normal boot process.
92 </para>
93 </listitem>
94 </varlistentry>
95 <varlistentry>
96 <term>
97 <literal>systemd.log_level=debug</literal>
98 <literal>systemd.log_target=console</literal>
99 </term>
100 <listitem>
101 <para>
102 Make systemd very verbose and send log messages to the console
103 instead of the journal. For more parameters recognised by
104 systemd, see systemd(1).
105 </para>
106 </listitem>
107 </varlistentry>
108 </variablelist>
109 <para>
110 In addition, these arguments are recognised by the live image only:
111 </para>
112 <variablelist>
113 <varlistentry>
114 <term>
115 <literal>live.nixos.passwd=password</literal>
116 </term>
117 <listitem>
118 <para>
119 Set the password for the <literal>nixos</literal> live user.
120 This can be used for SSH access if there are issues using the
121 terminal.
122 </para>
123 </listitem>
124 </varlistentry>
125 </variablelist>
126 <para>
127 Notice that for <literal>boot.shell_on_fail</literal>,
128 <literal>boot.debug1</literal>,
129 <literal>boot.debug1devices</literal>, and
130 <literal>boot.debug1mounts</literal>, if you did
131 <emphasis role="strong">not</emphasis> select <quote>start the new
132 shell as pid 1</quote>, and you <literal>exit</literal> from the new
133 shell, boot will proceed normally from the point where it failed, as
134 if you’d chosen <quote>ignore the error and continue</quote>.
135 </para>
136 <para>
137 If no login prompts or X11 login screens appear (e.g. due to hanging
138 dependencies), you can press Alt+ArrowUp. If you’re lucky, this will
139 start rescue mode (described above). (Also note that since most
140 units have a 90-second timeout before systemd gives up on them, the
141 <literal>agetty</literal> login prompts should appear eventually
142 unless something is very wrong.)
143 </para>
144</section>