forked from mirrors/nixpkgs
145 lines
5 KiB
XML
145 lines
5 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 “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 you’ve
|
||
forgotten to set
|
||
<link linkend="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>
|
||
In addition, these arguments are recognised by the live image only:
|
||
</para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>live.nixos.passwd=password</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Set the password for the <literal>nixos</literal> live user.
|
||
This can be used for SSH access if there are issues using the
|
||
terminal.
|
||
</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>
|