diff options
Diffstat (limited to 'nixos/doc/manual/administration/boot-problems.xml')
| -rw-r--r-- | nixos/doc/manual/administration/boot-problems.xml | 141 |
1 files changed, 83 insertions, 58 deletions
diff --git a/nixos/doc/manual/administration/boot-problems.xml b/nixos/doc/manual/administration/boot-problems.xml index be6ff3aac0fe..de3d8ac21aeb 100644 --- a/nixos/doc/manual/administration/boot-problems.xml +++ b/nixos/doc/manual/administration/boot-problems.xml @@ -3,63 +3,88 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-boot-problems"> + <title>Boot Problems</title> -<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 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 + <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> |