diff options
Diffstat (limited to 'nixos/doc/manual/administration/boot-problems.xml')
-rw-r--r-- | nixos/doc/manual/administration/boot-problems.xml | 65 |
1 files changed, 65 insertions, 0 deletions
diff --git a/nixos/doc/manual/administration/boot-problems.xml b/nixos/doc/manual/administration/boot-problems.xml new file mode 100644 index 000000000000..be6ff3aac0fe --- /dev/null +++ b/nixos/doc/manual/administration/boot-problems.xml @@ -0,0 +1,65 @@ +<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>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.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>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> \ No newline at end of file |