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 `linux`. The following are some useful kernel command line parameters that are recognised by the NixOS boot scripts or by systemd:
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 `linux`.
{manpage}`kernel-command-line(7)` documents the kernel parameters accepted by systemd. Those include many that are helpful for debugging boot issues, such as `systemd.debug_shell` and `rescue`. Some also have `rd.`‐prefixed variants that apply to stage 1.
`live.nixos.passwd=password`
: Set the password for the `nixos` live user. This can be used for SSH access if there are issues using the terminal.
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.target` (described in {manpage}`systemd.special(7)`). (Also note that since most units have a 90-second timeout before systemd gives up on them, the `agetty` login prompts should appear eventually unless something is very wrong.)
The scripted implementation of stage 1 also understands these boot parameters.
::: {.warning}
The scripted implementation of stage 1 is disabled by default and deprecated. These parameters have no effect, unless systemd stage 1 is explicitly disabled with `boot.initrd.systemd.enable = false;`.
:::
`boot.shell_on_fail`
: 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.
::: {.note}
systemd stage 1 alternative: `SYSTEMD_SULOGIN_FORCE=1` for rescue mode, or `rd.systemd.debug_shell` for shell on tty9.
:::
`boot.debug1`
: 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 `/proc` and `/sys`.
: Like `boot.debug1` or `boot.debug1devices`, but runs stage1 until all filesystems that are mounted during initrd are mounted (see [neededForBoot](#opt-fileSystems._name_.neededForBoot)). As a motivating example, this could be useful if you've forgotten to set [neededForBoot](#opt-fileSystems._name_.neededForBoot) on a file system.
: Print every shell command executed by the stage 1 and 2 boot scripts.
`single`
: Boot into rescue mode (a.k.a. single user mode). This will cause systemd to start nothing but the unit `rescue.target`, which runs `sulogin` 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.
Notice that for `boot.shell_on_fail`, `boot.debug1`, `boot.debug1devices`, and `boot.debug1mounts`, if you did **not** select "start the new shell as pid 1", and you `exit` from the new shell, boot will proceed normally from the point where it failed, as if you'd chosen "ignore the error and continue".
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 `agetty` login prompts should appear eventually unless something is very wrong.)
@@ -149,6 +149,10 @@ The first steps to all these are the same:
`NIXOS_LUSTRATE`:
:::
::: {.warning}
The lustrate process will not work if the [](#opt-boot.initrd.systemd.enable) option is set to `true`, which is now the default. Setting this to `false` is deprecated and scheduled for removal in NixOS 26.11, along with `NIXOS_LUSTRATE`. Other installation methods, such as the one outlined above, or installing from [kexec](#sec-booting-via-kexec), are recommended instead.
:::
Generate your NixOS configuration:
```ShellSession
@@ -167,11 +171,6 @@ The first steps to all these are the same:
If the current system and NixOS's bootloader configuration don't agree on where the [EFI System Partition](https://en.wikipedia.org/wiki/EFI_system_partition) is to be mounted, you'll need to manually alter the mount point in `hardware-configuration.nix` before building the system closure.
:::
::: {.note}
The lustrate process will not work if the [](#opt-boot.initrd.systemd.enable) option is set to `true`.
If you want to use this option, wait until after the first boot into the NixOS system to enable it and rebuild.
:::
You'll likely want to set a root password for your first boot using
the configuration files because you won't have a chance to enter a
password until after you reboot. You can initialize the root password
<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
- Stage 1 (a.k.a. initrd) is now based on systemd by default, and the old scripted implementation is deprecated and scheduled for removal in 26.11. If you run into issues migrating, you can [get help from the community](https://nixos.org/community/) or report an issue on GitHub.
You can temporarily revert to the scripted stage 1 implementation by disabling [](#opt-boot.initrd.systemd.enable), but this is discouraged.
Most incompatibilities will be explained with assertions during configuration evaluation, but be aware of the following that can't be automatically detected:
- If you use LUKS disk encryption, ensure that `fileSystems."/".device` is set to `"/dev/mapper/<name>"`, where `<name>` matches the name in your `boot.initrd.luks.devices.<name>` definition, to avoid systemd timing out while prompting for a passphrase. If you have a more complex setup, e.g. with LVM on top of LUKS, you may need to add `"x-systemd.device-timeout=infinity"` to `fileSystems."/".options` instead. If you need to disable the timeout before you can boot into the system, pass `systemd.default_device_timeout_sec=infinity` on the kernel command line.
- The `cryptsetup-askpass` program is not available; use `systemctl default` instead, which will prompt for passphrases as necessary. If you pipe password responses into SSH over stdin, use `ssh -o RequestTTY=force` to ensure `systemctl default` gets a TTY to prompt on.
- Many kernel parameters have been replaced with native systemd versions; see [](#sec-boot-problems).
- The system.nix file has been added has an alternative entry point to configuration.nix (and flake.nix) that allows to configure NixOS without using `nix-channel`.
This file must evaluate to a NixOS system derivation or an attribute set of such derivations, in which case the attribute to build has to be selected with the `--attr` option of `nixos-rebuild` or `nixos-install`.
cryptsetup-askpass is not available in systemd stage 1. Please remove it from: boot.initrd.systemd.users.${name}.shell
Use `systemctl default` instead; see the NixOS 26.05 release notes for details. If you want to continue restricting the command for SSH login, you can use `command="systemctl default"` in SSH authorized keys instead; see `sshd(8)`.
