128 lines
4.6 KiB
XML
128 lines
4.6 KiB
XML
|
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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
|
|||
|
|
<quote>e</quote> 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:
|
|||
|
|
</para>
|
|||
|
|
<variablelist>
|
|||
|
|
<varlistentry>
|
|||
|
|
<term>
|
|||
|
|
<literal>boot.shell_on_fail</literal>
|
|||
|
|
</term>
|
|||
|
|
<listitem>
|
|||
|
|
<para>
|
|||
|
|
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.
|
|||
|
|
</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
|
|||
|
|
<literal>/proc</literal> and <literal>/sys</literal>.
|
|||
|
|
</para>
|
|||
|
|
</listitem>
|
|||
|
|
</varlistentry>
|
|||
|
|
<varlistentry>
|
|||
|
|
<term>
|
|||
|
|
<literal>boot.debug1devices</literal>
|
|||
|
|
</term>
|
|||
|
|
<listitem>
|
|||
|
|
<para>
|
|||
|
|
Like <literal>boot.debug1</literal>, but runs stage1 until
|
|||
|
|
kernel modules are loaded and device nodes are created. This
|
|||
|
|
may help with e.g. making the keyboard work.
|
|||
|
|
</para>
|
|||
|
|
</listitem>
|
|||
|
|
</varlistentry>
|
|||
|
|
<varlistentry>
|
|||
|
|
<term>
|
|||
|
|
<literal>boot.debug1mounts</literal>
|
|||
|
|
</term>
|
|||
|
|
<listitem>
|
|||
|
|
<para>
|
|||
|
|
Like <literal>boot.debug1</literal> or
|
|||
|
|
<literal>boot.debug1devices</literal>, but runs stage1 until
|
|||
|
|
all filesystems that are mounted during initrd are mounted
|
|||
|
|
(see
|
|||
|
|
<link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link>).
|
|||
|
|
As a motivating example, this could be useful if you’ve
|
|||
|
|
forgotten to set
|
|||
|
|
<link xlink:href="options.html#opt-fileSystems._name_.neededForBoot">neededForBoot</link>
|
|||
|
|
on a file system.
|
|||
|
|
</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
|
|||
|
|
<literal>sulogin</literal> 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</literal>
|
|||
|
|
<literal>systemd.log_target=console</literal>
|
|||
|
|
</term>
|
|||
|
|
<listitem>
|
|||
|
|
<para>
|
|||
|
|
Make systemd very verbose and send log messages to the console
|
|||
|
|
instead of the journal. For more parameters recognised by
|
|||
|
|
systemd, see systemd(1).
|
|||
|
|
</para>
|
|||
|
|
</listitem>
|
|||
|
|
</varlistentry>
|
|||
|
|
</variablelist>
|
|||
|
|
<para>
|
|||
|
|
Notice that for <literal>boot.shell_on_fail</literal>,
|
|||
|
|
<literal>boot.debug1</literal>,
|
|||
|
|
<literal>boot.debug1devices</literal>, and
|
|||
|
|
<literal>boot.debug1mounts</literal>, if you did
|
|||
|
|
<emphasis role="strong">not</emphasis> select <quote>start the new
|
|||
|
|
shell as pid 1</quote>, and you <literal>exit</literal> from the new
|
|||
|
|
shell, boot will proceed normally from the point where it failed, as
|
|||
|
|
if you’d chosen <quote>ignore the error and continue</quote>.
|
|||
|
|
</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
|
|||
|
|
<literal>agetty</literal> login prompts should appear eventually
|
|||
|
|
unless something is very wrong.)
|
|||
|
|
</para>
|
|||
|
|
</section>
|