126 lines
4.4 KiB
XML
126 lines
4.4 KiB
XML
<section xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||
version="5.0"
|
||
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:
|
||
<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 <filename>/proc</filename> and
|
||
<filename>/sys</filename>.
|
||
</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
|
||
<option><link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link></option>
|
||
). As a motivating example, this could be useful if you've forgotten to set
|
||
<option><link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link></option>
|
||
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 <command>sulogin</command> 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 systemd.log_target=console</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Make systemd very verbose and send log messages to the console instead of
|
||
the journal.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
For more parameters recognised by systemd, see <citerefentry>
|
||
<refentrytitle>systemd</refentrytitle>
|
||
<manvolnum>1</manvolnum></citerefentry>.
|
||
</para>
|
||
|
||
<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>not</emphasis>
|
||
select "start the new shell as pid 1", and you <literal>exit</literal> from
|
||
the new shell, boot will proceed normally from the point where it failed, as
|
||
if you'd chosen "ignore the error and continue".
|
||
</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
|
||
<command>agetty</command> login prompts should appear eventually unless
|
||
something is very wrong.)
|
||
</para>
|
||
</section>
|