pyrox.dev
Merge pull request #125608 from ryantm/md-boot-problems
nixos/doc: convert boot problems section to CommonMark
authored by Ryan Mulligan and committed by GitHub d37b25ca fa676044
+35
nixos/doc/manual/administration/boot-problems.section.md
+35
nixos/doc/manual/administration/boot-problems.section.md
···
1
+
# Boot Problems {#sec-boot-problems}
2
+
3
+
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 `linux`. The following are some useful kernel command line parameters that are recognised by the NixOS boot scripts or by systemd:
4
+
5
+
`boot.shell_on_fail`
6
+
7
+
: 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.
8
+
9
+
`boot.debug1`
10
+
11
+
: 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 `/proc` and `/sys`.
12
+
13
+
`boot.debug1devices`
14
+
15
+
: Like `boot.debug1`, but runs stage1 until kernel modules are loaded and device nodes are created. This may help with e.g. making the keyboard work.
16
+
17
+
`boot.debug1mounts`
18
+
19
+
: Like `boot.debug1` or `boot.debug1devices`, but runs stage1 until all filesystems that are mounted during initrd are mounted (see [neededForBoot](#opt-fileSystems._name_.neededForBoot)). As a motivating example, this could be useful if you've forgotten to set [neededForBoot](options.html#opt-fileSystems._name_.neededForBoot) on a file system.
20
+
21
+
`boot.trace`
22
+
23
+
: Print every shell command executed by the stage 1 and 2 boot scripts.
24
+
25
+
`single`
26
+
27
+
: Boot into rescue mode (a.k.a. single user mode). This will cause systemd to start nothing but the unit `rescue.target`, which runs `sulogin` 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.
28
+
29
+
`systemd.log_level=debug` `systemd.log_target=console`
30
+
31
+
: Make systemd very verbose and send log messages to the console instead of the journal. For more parameters recognised by systemd, see systemd(1).
32
+
33
+
Notice that for `boot.shell_on_fail`, `boot.debug1`, `boot.debug1devices`, and `boot.debug1mounts`, if you did **not** select "start the new shell as pid 1", and you `exit` from the new shell, boot will proceed normally from the point where it failed, as if you'd chosen "ignore the error and continue".
34
+
35
+
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 `agetty` login prompts should appear eventually unless something is very wrong.)
-126
nixos/doc/manual/administration/boot-problems.xml
-126
nixos/doc/manual/administration/boot-problems.xml
···
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
-
Allows the user to start a root shell if something goes wrong in stage 1
23
-
of the boot process (the initial ramdisk). This is disabled by default
24
-
because there is no 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.debug1devices</literal>
44
-
</term>
45
-
<listitem>
46
-
<para>
47
-
Like <literal>boot.debug1</literal>, but runs stage1 until kernel modules are loaded and device nodes are created.
48
-
This may help with e.g. making the keyboard work.
49
-
</para>
50
-
</listitem>
51
-
</varlistentry>
52
-
<varlistentry>
53
-
<term>
54
-
<literal>boot.debug1mounts</literal>
55
-
</term>
56
-
<listitem>
57
-
<para>
58
-
Like <literal>boot.debug1</literal> or
59
-
<literal>boot.debug1devices</literal>, but runs stage1 until all
60
-
filesystems that are mounted during initrd are mounted (see
61
-
<option><link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link></option>
62
-
). As a motivating example, this could be useful if you've forgotten to set
63
-
<option><link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link></option>
64
-
on a file system.
65
-
</para>
66
-
</listitem>
67
-
</varlistentry>
68
-
<varlistentry>
69
-
<term>
70
-
<literal>boot.trace</literal>
71
-
</term>
72
-
<listitem>
73
-
<para>
74
-
Print every shell command executed by the stage 1 and 2 boot scripts.
75
-
</para>
76
-
</listitem>
77
-
</varlistentry>
78
-
<varlistentry>
79
-
<term>
80
-
<literal>single</literal>
81
-
</term>
82
-
<listitem>
83
-
<para>
84
-
Boot into rescue mode (a.k.a. single user mode). This will cause systemd
85
-
to start nothing but the unit <literal>rescue.target</literal>, which
86
-
runs <command>sulogin</command> to prompt for the root password and start
87
-
a root login shell. Exiting the shell causes the system to continue with
88
-
the normal boot process.
89
-
</para>
90
-
</listitem>
91
-
</varlistentry>
92
-
<varlistentry>
93
-
<term>
94
-
<literal>systemd.log_level=debug systemd.log_target=console</literal>
95
-
</term>
96
-
<listitem>
97
-
<para>
98
-
Make systemd very verbose and send log messages to the console instead of
99
-
the journal.
100
-
</para>
101
-
</listitem>
102
-
</varlistentry>
103
-
</variablelist>
104
-
For more parameters recognised by systemd, see <citerefentry>
105
-
<refentrytitle>systemd</refentrytitle>
106
-
<manvolnum>1</manvolnum></citerefentry>.
107
-
</para>
108
-
109
-
<para>
110
-
Notice that for <literal>boot.shell_on_fail</literal>,
111
-
<literal>boot.debug1</literal>, <literal>boot.debug1devices</literal>, and
112
-
<literal>boot.debug1mounts</literal>, if you did <emphasis>not</emphasis>
113
-
select "start the new shell as pid 1", and you <literal>exit</literal> from
114
-
the new shell, boot will proceed normally from the point where it failed, as
115
-
if you'd chosen "ignore the error and continue".
116
-
</para>
117
-
118
-
<para>
119
-
If no login prompts or X11 login screens appear (e.g. due to hanging
120
-
dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start
121
-
rescue mode (described above). (Also note that since most units have a
122
-
90-second timeout before systemd gives up on them, the
123
-
<command>agetty</command> login prompts should appear eventually unless
124
-
something is very wrong.)
125
-
</para>
126
-
</section>
+1
-1
nixos/doc/manual/administration/troubleshooting.xml
+1
-1
nixos/doc/manual/administration/troubleshooting.xml
···
8
8
This chapter describes solutions to common problems you might encounter when
9
9
you manage your NixOS system.
10
10
</para>
11
-
<xi:include href="boot-problems.xml" />
11
+
<xi:include href="../from_md/administration/boot-problems.section.xml" />
12
12
<xi:include href="maintenance-mode.xml" />
13
13
<xi:include href="rollback.xml" />
14
14
<xi:include href="store-corruption.xml" />
+127
nixos/doc/manual/from_md/administration/boot-problems.section.xml
+127
nixos/doc/manual/from_md/administration/boot-problems.section.xml
···
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
7
+
<quote>e</quote> to modify the selected boot entry and editing the
8
+
line starting with <literal>linux</literal>. The following are some
9
+
useful kernel command line parameters that are recognised by the
10
+
NixOS boot 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 xlink:href="options.html#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
+
Notice that for <literal>boot.shell_on_fail</literal>,
111
+
<literal>boot.debug1</literal>,
112
+
<literal>boot.debug1devices</literal>, and
113
+
<literal>boot.debug1mounts</literal>, if you did
114
+
<emphasis role="strong">not</emphasis> select <quote>start the new
115
+
shell as pid 1</quote>, and you <literal>exit</literal> from the new
116
+
shell, boot will proceed normally from the point where it failed, as
117
+
if you’d chosen <quote>ignore the error and continue</quote>.
118
+
</para>
119
+
<para>
120
+
If no login prompts or X11 login screens appear (e.g. due to hanging
121
+
dependencies), you can press Alt+ArrowUp. If you’re lucky, this will
122
+
start rescue mode (described above). (Also note that since most
123
+
units have a 90-second timeout before systemd gives up on them, the
124
+
<literal>agetty</literal> login prompts should appear eventually
125
+
unless something is very wrong.)
126
+
</para>
127
+
</section>