nixpkgs/nixos/doc/manual/from_md/administration/boot-problems.section.xml
Jan Tojnar f07dcbef64
nixos/doc: Synchronize the Markdown generator with Nixpkgs
Switch to CommonMark with our extensions.
2021-06-18 00:07:00 +02:00

128 lines
4.6 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<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 “e” 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 youve
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 youd 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 youre 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>