Appendix A. Configuration Options

Additional arguments passed to each module in addition to ones like lib, config, and pkgs, modulesPath.

This option is also available to all submodules. Submodules do not inherit args from their parent module, nor do they provide args to their parent module or sibling submodules. The sole exception to this is the argument name which is provided by parent modules to a submodule and contains the attribute name the submodule is bound to, or a unique generated name if it is not bound to an attribute.

Some arguments are already passed by default, of which the following cannot be changed with this option:

For NixOS, the default value for this option includes at least this argument:

Type: lazy attribute set of raw value

Declared by:

Whether to install files to support the AppStream metadata specification.

Type: boolean

Default: true

Declared by:

Whether to enable support for NixOS containers. Defaults to true (at no cost if containers are not actually used).

Type: boolean

Default: true

Declared by:

Whether to enable bcache mount support.

Type: boolean

Default: true

Example: false

Declared by:

Whether to add the boot.binfmt.emulatedSystems to nix.settings.extra-platforms. Disable this to use remote builders for those platforms, while allowing testing binaries locally.

Type: boolean

Default: true

Example: false

Declared by:

List of systems to emulate. Will also configure Nix to support your new systems. Warning: the builder can execute all emulated systems within the same build, which introduces impurities in the case of cross compilation.

Type: list of (one of “aarch64-linux”, “aarch64_be-linux”, “alpha-linux”, “armv6l-linux”, “armv7l-linux”, “i386-linux”, “i486-linux”, “i586-linux”, “i686-linux”, “i686-windows”, “loongarch64-linux”, “mips-linux”, “mips64-linux”, “mips64-linuxabin32”, “mips64el-linux”, “mips64el-linuxabin32”, “mipsel-linux”, “powerpc-linux”, “powerpc64-linux”, “powerpc64le-linux”, “riscv32-linux”, “riscv64-linux”, “s390x-linux”, “sparc-linux”, “sparc64-linux”, “wasm32-wasi”, “wasm64-wasi”, “x86_64-linux”, “x86_64-windows”)

Default: [ ]

Example:

[
  "wasm32-wasi"
  "x86_64-windows"
  "aarch64-linux"
]

Declared by:

Whether to use static emulators when available.

This enables the kernel to preload the emulator binaries when the binfmt registrations are added, obviating the need to make the emulator binaries available inside chroots and chroot-like sandboxes.

Type: boolean

Default: false

Declared by:

Extra binary formats to register with the kernel. See https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html for more details.

Type: attribute set of (submodule)

Default: { }

Declared by:

Whether to open the interpreter file as soon as the registration is loaded, rather than waiting for a relevant file to be invoked.

See the description of the ‘F’ flag in the kernel docs for more details.

Type: boolean

Default: false

Declared by:

The interpreter to invoke to run the program.

Note that the actual registration will point to /run/binfmt/${name}, so the kernel interpreter length limit doesn’t apply.

Type: absolute path

Declared by:

The magic number or extension to match on.

Type: string

Declared by:

A mask to be ANDed with the byte sequence of the file before matching

Type: null or string

Default: null

Declared by:

Whether to launch with the credentials and security token of the binary, not the interpreter (e.g. setuid bit).

See the description of the ‘C’ flag in the kernel docs for more details.

Implies/requires openBinary = true.

Type: boolean

Default: false

Declared by:

The byte offset of the magic number used for recognition.

Type: null or signed integer

Default: null

Declared by:

Whether to pass the binary to the interpreter as an open file descriptor, instead of a path.

Type: boolean

Default: false

Declared by:

Whether to pass the original argv[0] to the interpreter.

See the description of the ‘P’ flag in the kernel docs for more details;

Type: boolean

Default: false

Declared by:

Whether to recognize executables by magic number or extension.

Type: one of “magic”, “extension”

Default: "magic"

Declared by:

Whether to wrap the interpreter in a shell script.

This allows a shell command to be set as the interpreter.

Type: boolean

Default: true

Declared by:

List of names of kernel modules that should not be loaded automatically by the hardware probing code.

Type: list of string

Default: [ ]

Example:

[
  "cirrusfb"
  "i2c_piix4"
]

Declared by:

Whether to enable the validation of bootspec documents for each build. This will introduce Go in the build-time closure as we are relying on Cuelang for schema validation. Enable this option if you want to ascertain that your documents are correct .

Type: boolean

Default: false

Example: true

Declared by:

User-defined data that extends the bootspec document.

To reduce incompatibility and prevent names from clashing between applications, it is highly recommended to use a unique namespace for your extensions.

Type: attribute set of anything

Default: { }

Declared by:

The kernel console loglevel. All Kernel Messages with a log level smaller than this setting will be printed to the console.

Type: signed integer

Default: 4

Declared by:

If enabled, NixOS will set up a kernel that will boot on crash, and leave the user in systemd rescue to be able to save the crashed kernel dump at /proc/vmcore. It also activates the NMI watchdog.

Type: boolean

Default: false

Declared by:

Parameters that will be passed to the kernel kexec-ed on crash.

Type: list of string

Default:

[
  "1"
  "boot.shell_on_fail"
]

Declared by:

The amount of memory reserved for the crashdump kernel. If you choose a too high value, dmesg will mention “crashkernel reservation failed”.

Type: string

Default: "128M"

Declared by:

Size limit for the /dev/shm tmpfs. Look at mount(8), tmpfs size option, for the accepted syntax.

Type: string

Default: "50%"

Example: "256m"

Declared by:

Size limit for the /dev tmpfs. Look at mount(8), tmpfs size option, for the accepted syntax.

Type: string

Default: "5%"

Example: "32m"

Declared by:

Any additional configuration to be appended to the generated modprobe.conf. This is typically used to specify module options. See modprobe.d(5) for details.

Type: strings concatenated with “\n”

Default: ""

Example:

''
  options parport_pc io=0x378 irq=7 dma=1
''

Declared by:

A list of additional packages supplying kernel modules.

Type: list of package

Default: [ ]

Example: [ config.boot.kernelPackages.nvidia_x11 ]

Declared by:

Additional paths that get appended to the SYSTEMD_UNIT_PATH environment variable that can contain mutable unit files.

Type: list of string

Default: [ ]

Declared by:

Whether to enable growing the root partition on boot.

Type: boolean

Default: false

Example: true

Declared by:

Whether to try to load kernel modules for all detected hardware. Usually this does a good job of providing you with the modules you need, but sometimes it can crash the system or cause other nasty effects.

Type: boolean

Default: true

Declared by:

Whether to enable the NixOS initial RAM disk (initrd). This may be needed to perform some initialisation tasks (like mounting network/encrypted file systems) before continuing the boot process.

Type: boolean

Default: !config.boot.isContainer

Declared by:

The set of kernel modules in the initial ramdisk used during the boot process. This set must include all modules necessary for mounting the root device. That is, it should include modules for the physical device (e.g., SCSI drivers) and for the file system (e.g., ext3). The set specified here is automatically closed under the module dependency relation, i.e., all dependencies of the modules list here are included automatically. The modules listed here are available in the initrd, but are only loaded on demand (e.g., the ext3 module is loaded automatically when an ext3 filesystem is mounted, and modules for PCI devices are loaded when they match the PCI ID of a device in your system). To force a module to be loaded, include it in boot.initrd.kernelModules.

Type: list of string

Default: [ ]

Example:

[
  "sata_nv"
  "ext3"
]

Declared by:

Whether to run fsck on journaling filesystems such as ext3.

Type: boolean

Default: true

Declared by:

Whether to enable Clevis in initrd.

Type: boolean

Default: false

Example: true

Declared by:

Clevis package

Type: package

Default: "pkgs.clevis"

Declared by:

Encrypted devices that need to be unlocked at boot using Clevis

Type: attribute set of (submodule)

Default: { }

Declared by:

Clevis JWE file used to decrypt the device at boot, in concert with the chosen pin (one of TPM2, Tang server, or SSS).

Type: absolute path

Declared by:

Whether the Clevis JWE file used to decrypt the devices uses a Tang server as a pin.

Type: boolean

Default: false

Declared by:

The compressor to use on the initrd image. May be any of:

The given program should read data from stdin and write it to stdout compressed.

Type: string or function that evaluates to a(n) string

Default: zstd if the kernel supports it (5.9+), gzip if not

Example: "xz"

Declared by:

Arguments to pass to the compressor for the initrd image, or null to use the compressor’s defaults.

Type: null or (list of string)

Default: null

Declared by:

Extra files to link and copy in to the initrd.

Type: attribute set of (submodule)

Default: { }

Declared by:

The object to make available inside the initrd.

Type: package

Declared by:

Other firmware files (relative to "${config.hardware.firmware}/lib/firmware") to include in the final initrd we are building.

Type: list of string

Default: [ ]

Declared by:

This option, if set, adds a collection of default kernel modules to boot.initrd.availableKernelModules and boot.initrd.kernelModules.

Type: boolean

Default: true

Declared by:

List of modules that are always loaded by the initrd.

Type: list of string

Default: [ ]

Declared by:

A list of cryptographic kernel modules needed to decrypt the root device(s). The default includes all common modules.

Type: list of string

Default:

[
  "aes"
  "aes_generic"
  "blowfish"
  "twofish"
  "serpent"
  "cbc"
  "xts"
  "lrw"
  "sha1"
  "sha256"
  "sha512"
  "af_alg"
  "algif_skcipher"
]

Declared by:

The encrypted disk that should be opened before the root filesystem is mounted. Both LVM-over-LUKS and LUKS-over-LVM setups are supported. The unencrypted devices can be accessed as /dev/mapper/«name».

Type: attribute set of (submodule)

Default: { }

Example:

{
  luksroot = {
    device = "/dev/disk/by-uuid/430e9eff-d852-4f68-aa3b-2fa3599ebe08";
  };
}

Declared by:

Whether to allow TRIM requests to the underlying device. This option has security implications; please read the LUKS documentation before activating it. This option is incompatible with authenticated encryption (dm-crypt stacked over dm-integrity).

Type: boolean

Default: false

Declared by:

Whether to bypass dm-crypt’s internal read and write workqueues. Enabling this should improve performance on SSDs; see here for more information. Needs Linux 5.9 or later.

Type: boolean

Default: false

Declared by:

Path of the underlying encrypted block device.

Type: string

Example: "/dev/disk/by-uuid/430e9eff-d852-4f68-aa3b-2fa3599ebe08"

Declared by:

Whether to fallback to interactive passphrase prompt if the keyfile cannot be found. This will prevent unattended boot should the keyfile go missing.

Type: boolean

Default: false

Declared by:

The FIDO2 credential ID.

Type: null or string

Default: null

Example: "f1d00200d8dc783f7fb1e10ace8da27f8312d72692abfca2f7e4960a73f48e82e1f7571f6ebfcee9fb434f9886ccc8fcc52a6614d8d2"

Declared by:

List of FIDO2 credential IDs.

Use this if you have multiple FIDO2 keys you want to use for the same luks device.

Type: list of string

Default: [ ]

Example:

[
  "f1d00200d8dc783f7fb1e10ace8da27f8312d72692abfca2f7e4960a73f48e82e1f7571f6ebfcee9fb434f9886ccc8fcc52a6614d8d2"
]

Declared by:

Time in seconds to wait for the FIDO2 key.

Type: signed integer

Default: 10

Declared by:

Defines whatever to use an empty string as a default salt.

Enable only when your device is PIN protected, such as Trezor.

Type: boolean

Default: false

Declared by:

The option to use this LUKS device with a GPG encrypted luks password by the GPG Smartcard. If null (the default), GPG-Smartcard will be disabled for this device.

Type: null or (submodule)

Default: null

Declared by:

Path to the GPG encrypted passphrase.

Type: absolute path

Declared by:

Time in seconds to wait for the GPG Smartcard.

Type: signed integer

Default: 10

Declared by:

Path to the Public Key.

Type: absolute path

Declared by:

The name of the file or block device that should be used as header for the encrypted device.

Type: null or string

Default: null

Example: "/root/header.img"

Declared by:

The name of the file (can be a raw device or a partition) that should be used as the decryption key for the encrypted device. If not specified, you will be prompted for a passphrase instead.

Type: null or string

Default: null

Example: "/dev/sdb1"

Declared by:

The offset of the key file. Use this in combination with keyFileSize to use part of a file as key file (often the case if a raw device or partition is used as a key file). If not specified, the key begins at the first byte of keyFile.

Type: null or signed integer

Default: null

Example: 4096

Declared by:

The size of the key file. Use this if only the beginning of the key file should be used as a key (often the case if a raw device or partition is used as key file). If not specified, the whole keyFile will be used decryption, instead of just the first keyFileSize bytes.

Type: null or signed integer

Default: null

Example: 4096

Declared by:

The amount of time in seconds for a keyFile to appear before timing out and trying passwords.

Type: null or signed integer

Default: null

Example: 5

Declared by:

Commands that should be run right after we have mounted our LUKS device.

Type: strings concatenated with “\n”

Default: ""

Example:

''
  umount /tmp/persistent
''

Declared by:

Whether the luksOpen will be attempted before LVM scan or after it.

Type: boolean

Default: true

Declared by:

Commands that should be run right before we try to mount our LUKS device. This can be useful, if the keys needed to open the drive is on another partition.

Type: strings concatenated with “\n”

Default: ""

Example:

''
  mkdir -p /tmp/persistent
  mount -t zfs rpool/safe/persistent /tmp/persistent
''

Declared by:

If keyFile fails then try an empty passphrase first before prompting for password.

Type: boolean

Default: false

Declared by:

The options to use for this LUKS device in YubiKey-PBA. If null (the default), YubiKey-PBA will be disabled for this device.

Type: null or (submodule)

Default: null

Declared by:

Time in seconds to wait for the YubiKey.

Type: signed integer

Default: 10

Declared by:

How much the iteration count for PBKDF2 is increased at each successful authentication.

Type: signed integer

Default: 0

Declared by:

Length of the LUKS slot key derived with PBKDF2 in byte.

Type: signed integer

Default: 64

Declared by:

Length of the new salt in byte (64 is the effective maximum).

Type: signed integer

Default: 16

Declared by:

Which slot on the YubiKey to challenge.

Type: signed integer

Default: 2

Declared by:

An unencrypted device that will temporarily be mounted in stage-1. Must contain the current salt to create the challenge for this LUKS device.

Type: absolute path

Default: "/dev/sda1"

Declared by:

The filesystem of the unencrypted device.

Type: string

Default: "vfat"

Declared by:

Absolute path of the salt on the unencrypted device with that device’s root directory as “/”.

Type: string

Default: "/crypt-storage/default"

Declared by:

Whether to use a passphrase and a YubiKey (true), or only a YubiKey (false).

Type: boolean

Default: true

Declared by:

Enables support for authenticating with FIDO2 devices.

Type: boolean

Default: false

Declared by:

Enables support for authenticating with a GPG encrypted password.

Type: boolean

Default: false

Declared by:

Unless enabled, encryption keys can be easily recovered by an attacker with physical access to any machine with PCMCIA, ExpressCard, ThunderBolt or FireWire port. More information is available at https://en.wikipedia.org/wiki/DMA_attack.

This option blacklists FireWire drivers, but doesn’t remove them. You can manually load the drivers if you need to use a FireWire device, but don’t forget to unload them!

Type: boolean

Default: true

Declared by:

When opening a new LUKS device try reusing last successful passphrase.

Useful for mounting a number of devices that use the same passphrase without retyping it several times.

Such setup can be useful if you use cryptsetup luksSuspend. Different LUKS devices will still have different master keys even when using the same passphrase.

Type: boolean

Default: true

Declared by:

Enables support for authenticating with a YubiKey on LUKS devices. See the NixOS wiki for information on how to properly setup a LUKS device and a YubiKey to work with this feature.

Type: boolean

Default: false

Declared by:

Add network connectivity support to initrd. The network may be configured using the ip kernel parameter, as described in the kernel documentation. Otherwise, if networking.useDHCP is enabled, an IP address is acquired using DHCP.

You should add the module(s) required for your network card to boot.initrd.availableKernelModules. lspci -v | grep -iA8 'network\|ethernet' will tell you which.

Type: boolean

Default: false

Declared by:

Whether to clear the configuration of the interfaces that were set up in the initrd right before stage 2 takes over. Stage 2 will do the regular network configuration based on the NixOS networking options.

The default is false when systemd is enabled in initrd, because the systemd-networkd documentation suggests it.

Type: boolean

Default: "!config.boot.initrd.systemd.enable"

Declared by:

Starts an OpenVPN client during initrd boot. It can be used to e.g. remotely accessing the SSH service controlled by boot.initrd.network.ssh or other network services included. Service is killed when stage-1 boot is finished.

Type: boolean

Default: false

Declared by:

The configuration file for OpenVPN.

Type: absolute path

Example: ./configuration.ovpn

Declared by:

Shell commands to be executed after stage 1 of the boot has initialised the network.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Start SSH service during initrd boot. It can be used to debug failing boot on a remote server, enter pasphrase for an encrypted partition etc. Service is killed when stage-1 boot is finished.

The sshd configuration is largely inherited from services.openssh.

Type: boolean

Default: false

Declared by:

Authorized keys taken from files for the root user on initrd. You can combine the authorizedKeyFiles and authorizedKeys options.

Type: list of absolute path

Default: config.users.users.root.openssh.authorizedKeys.keyFiles

Declared by:

Authorized keys for the root user on initrd. You can combine the authorizedKeys and authorizedKeyFiles options.

Type: list of string

Default: config.users.users.root.openssh.authorizedKeys.keys

Example:

[
  "ssh-rsa AAAAB3NzaC1yc2etc/etc/etcjwrsh8e596z6J0l7 example@host"
  "ssh-ed25519 AAAAC3NzaCetcetera/etceteraJZMfk3QPfQ foo@bar"
]

Declared by:

Verbatim contents of sshd_config.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Specify SSH host keys to import into the initrd.

To generate keys, use ssh-keygen(1) as root:

ssh-keygen -t rsa -N "" -f /etc/secrets/initrd/ssh_host_rsa_key
ssh-keygen -t ed25519 -N "" -f /etc/secrets/initrd/ssh_host_ed25519_key

Type: list of (string or absolute path)

Default: [ ]

Example:

[
  "/etc/secrets/initrd/ssh_host_rsa_key"
  "/etc/secrets/initrd/ssh_host_ed25519_key"
]

Declared by:

Allow leaving config.boot.initrd.network.ssh.hostKeys empty, to deploy ssh host keys out of band.

Type: boolean

Default: false

Declared by:

Port on which SSH initrd service should listen.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: 22

Declared by:

Login shell of the remote user. Can be used to limit actions user can do.

Type: null or string

Default: "\"/bin/ash\""

Declared by:

Enables the udhcpc service during stage 1 of the boot process. This defaults to networking.useDHCP. Therefore, this useful if useDHCP is off but the initramfs should do dhcp.

Type: boolean

Default: "networking.useDHCP"

Declared by:

Additional command-line arguments passed verbatim to udhcpc if boot.initrd.network.enable and boot.initrd.network.udhcpc.enable are enabled.

Type: list of string

Default: [ ]

Declared by:

Shell commands to be executed immediately after stage 1 of the boot has loaded kernel modules and created device nodes in /dev.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Shell commands to be executed immediately after the stage 1 filesystems have been mounted.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Shell commands to be executed immediately after attempting to resume.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Shell commands to be executed before udev is started to create device nodes.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Shell commands to be executed before the failure prompt is shown.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Shell commands to be executed immediately before LVM discovery.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Other initrd files to prepend to the final initrd we are building.

Type: list of string

Default: [ ]

Declared by:

Secrets to append to the initrd. The attribute name is the path the secret should have inside the initrd, the value is the path it should be copied from (or null for the same path inside and out).

Note that nixos-rebuild switch will generate the initrd also for past generations, so if secrets are moved or deleted you will also have to garbage collect the generations that use those secrets.

Type: attribute set of (null or absolute path)

Default: { }

Example:

{ "/etc/dropbear/dropbear_rsa_host_key" =
    ./secret-dropbear-key;
}

Declared by:

This will only be used when systemd is used in stage 1.

Whether to enable bcache support in the initrd.

Type: boolean

Default: config.boot.initrd.systemd.enable && config.boot.bcache.enable

Example: true

Declared by:

This will only be used when systemd is used in stage 1.

Whether to enable booting from LVM2 in the initrd.

Type: boolean

Default: config.boot.initrd.systemd.enable && config.services.lvm.enable

Example: true

Declared by:

Whether to enable resolved for stage 1 networking. Uses the toplevel ‘services.resolved’ options for ‘resolved.conf’

Type: unspecified value

Default: "config.boot.initrd.systemd.network.enable"

Declared by:

This will only be used when systemd is used in stage 1.

List of packages containing udev rules that will be copied to stage 1. All files found in «pkg»/etc/udev/rules.d and «pkg»/lib/udev/rules.d will be included.

Type: list of absolute path

Default: [ ]

Declared by:

This will only be used when systemd is used in stage 1.

Packages to search for binaries that are referenced by the udev rules in stage 1. This list always contains /bin of the initrd.

Type: list of absolute path

Default: [ ]

Declared by:

udev rules to include in the initrd only. They’ll be written into file 99-local.rules. Thus they are read and applied after the essential initrd rules.

Type: strings concatenated with “\n”

Default: ""

Example:

''
  SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:1D:60:B9:6D:4F", KERNEL=="eth*", NAME="my_fast_network_card"
''

Declared by:

Names of supported filesystem types, or an attribute set of file system types and their state. The set form may be used together with lib.mkForce to explicitly disable support for specific filesystems, e.g. to disable ZFS with an unsupported kernel.

Type: (attribute set of boolean) or (list of string) convertible to it

Default: { }

Example:

{
  btrfs = true;
  zfs = lib.mkForce false;
}

Declared by:

Whether to enable systemd in initrd. The unit options such as boot.initrd.systemd.services are the same as their stage 2 counterparts such as systemd.services, except that restartTriggers and reloadTriggers are not supported.

Type: boolean

Default: false

Example: true

Declared by:

The systemd package to use.

Type: package

Default: config.systemd.package

Declared by:

Packages providing systemd units and hooks.

Type: list of package

Default: [ ]

Example: [ pkgs.systemd-cryptsetup-generator ]

Declared by:

Additional units shipped with systemd that shall be enabled.

Type: list of string

Default: [ ]

Example:

[
  "debug-shell.service"
  "systemd-quotacheck.service"
]

Declared by:

Definition of systemd automount units. This is a list instead of an attrSet, because systemd mandates the names to be derived from the ‘where’ attribute.

Type: list of (submodule)

Default: [ ]

Declared by:

Set of files that have to be linked into the initrd

Type: attribute set of (submodule)

Default: { }

Example:

{
  "/etc/machine-id".source = /etc/machine-id;
}

Declared by:

Whether to enable copying of this file and symlinking it.

Type: boolean

Default: true

Example: true

Declared by:

Features to enable via dlopen ELF notes. These will be in addition to anything included via ‘usePriority’, regardless of their priority.

Type: list of (optionally newline-terminated) single-line string

Default: [ ]

Declared by:

Priority of dlopen ELF notes to include. “required” is minimal, “recommended” includes “required”, and “suggested” includes “recommended”.

See: https://systemd.io/ELF_DLOPEN_METADATA/

Type: one of “required”, “recommended”, “suggested”

Default: "recommended"

Declared by:

Path of the source file.

Type: absolute path

Declared by:

Path of the symlink.

Type: null or absolute path

Default: null

Declared by:

Text of the file.

Type: null or strings concatenated with “\n”

Default: null

Declared by:

Whether to enable dbus in stage 1.

Type: boolean

Default: false

Example: true

Declared by:

Mount verity-protected block devices in the initrd.

Enabling this option allows to use systemd-veritysetup and systemd-veritysetup-generator in the initrd.

Type: boolean

Default: false

Example: true

Declared by:

Set to true for unauthenticated emergency access, and false or null for no emergency access.

Can also be set to a hashed super user password to allow authenticated access to the emergency mode.

Type: boolean or null or (string, not containing newlines or colons)

Default: false

Declared by:

Tools to add to /bin

Type: attribute set of absolute path

Default: { }

Example:

{
  umount = ${pkgs.util-linux}/bin/umount;
}

Declared by:

Extra config options for systemd. See systemd-system.conf(5) man page for available options.

Type: strings concatenated with “\n”

Default: ""

Example: "DefaultLimitCORE=infinity"

Declared by:

Whether to enable systemd FIDO2 support.

Type: boolean

Default: config.boot.initrd.systemd.package.withFido2

Example: true

Declared by:

Groups to include in initrd.

Type: attribute set of (submodule)

Default: { }

Declared by:

ID of the group in initrd.

Type: signed integer

Default: config.users.groups.${name}.gid

Declared by:

Packages to include in /bin for the stage 1 emergency shell.

Type: list of package

Default: [ ]

Declared by:

Environment variables of PID 1. These variables are not passed to started units.

Type: attribute set of (null or string or absolute path or package)

Default: { }

Example:

{
  SYSTEMD_LOG_LEVEL = "debug";
}

Declared by:

Definition of systemd mount units. This is a list instead of an attrSet, because systemd mandates the names to be derived from the ‘where’ attribute.

Type: list of (submodule)

Default: [ ]

Declared by:

Whether to enable networkd or not.

Type: boolean

Default: false

Declared by:

Definition of global systemd network config.

Type: submodule

Default: { }

Declared by:

Definition of systemd network links.

Type: attribute set of (submodule)

Default: { }

Declared by:

Definition of systemd network devices.

Type: attribute set of (submodule)

Default: { }

Declared by:

Definition of systemd networks.

Type: attribute set of (submodule)

Default: { }

Declared by:

Whether to enable the systemd-networkd-wait-online service.

systemd-networkd-wait-online can timeout and fail if there are no network interfaces available for it to manage. When systemd-networkd is enabled but a different service is responsible for managing the system’s internet connection (for example, NetworkManager or connman are used to manage WiFi connections), this service is unnecessary and can be disabled.

Type: boolean

Default: true

Example: false

Declared by:

Whether to consider the network online when any interface is online, as opposed to all of them. This is useful on portable machines with a wired and a wireless interface, for example.

This is on by default if networking.useDHCP is enabled.

Type: boolean

Default: "config.networking.useDHCP"

Declared by:

Extra command-line arguments to pass to systemd-networkd-wait-online. These also affect per-interface systemd-network-wait-online@ services.

See systemd-networkd-wait-online.service(8) for all available options.

Type: list of string

Default: [ ]

Declared by:

Network interfaces to be ignored when deciding if the system is online.

Type: list of string

Default: [ ]

Example:

[
  "wg0"
]

Declared by:

Time to wait for the network to come online, in seconds. Set to 0 to disable.

Type: unsigned integer, meaning >=0

Default: 120

Example: 0

Declared by:

Definition of systemd path units.

Type: attribute set of (submodule)

Default: { }

Declared by:

Grow and add partitions to a partition table at boot time in the initrd. systemd-repart only works with GPT partition tables.

To run systemd-repart after the initrd, see options.systemd.repart.enable.

Type: boolean

Default: false

Example: true

Declared by:

The device to operate on.

If device == null, systemd-repart will operate on the device backing the root partition. So in order to dynamically create the root partition in the initrd you need to set a device.

Type: null or string

Default: null

Example: "/dev/vda"

Declared by:

Controls how to operate on empty devices that contain no partition table yet. See systemd-repart(8) for details.

Type: one of “refuse”, “allow”, “require”, “force”, “create”

Default: "refuse"

Example: "require"

Declared by:

Controls how systemd will interpret the root FS in initrd. See kernel-command-line(7). NixOS currently does not allow specifying the root file system itself this way. Instead, the fstab value is used in order to interpret the root file system specified with the fileSystems option.

Type: one of “fstab”, “gpt-auto”

Default: "fstab"

Example: "gpt-auto"

Declared by:

Definition of systemd service units.

Type: attribute set of (submodule)

Default: { }

Declared by:

Definition of slice configurations.

Type: attribute set of (submodule)

Default: { }

Declared by:

Definition of systemd socket units.

Type: attribute set of (submodule)

Default: { }

Declared by:

Store paths to copy into the initrd as well.

Type: list of ((submodule) or ((optionally newline-terminated) single-line string or package) convertible to it)

Default: [ ]

Declared by:

Whether to enable copying of this file and symlinking it.

Type: boolean

Default: true

Example: true

Declared by:

Features to enable via dlopen ELF notes. These will be in addition to anything included via ‘usePriority’, regardless of their priority.

Type: list of (optionally newline-terminated) single-line string

Default: [ ]

Declared by:

Priority of dlopen ELF notes to include. “required” is minimal, “recommended” includes “required”, and “suggested” includes “recommended”.

See: https://systemd.io/ELF_DLOPEN_METADATA/

Type: one of “required”, “recommended”, “suggested”

Default: "recommended"

Declared by:

Path of the source file.

Type: absolute path

Declared by:

Path of the symlink.

Type: null or absolute path

Default: null

Declared by:

Whether to completely strip executables and libraries copied to the initramfs.

Setting this to false may save on the order of 30MiB on the machine building the system (by avoiding a binutils reference), at the cost of ~1MiB of initramfs size. This puts this option firmly in the territory of micro-optimisation.

Type: boolean

Default: true

Declared by:

Store paths specified in the storePaths option that should not be copied.

Type: list of (optionally newline-terminated) single-line string

Default: [ ]

Declared by:

A list of units to skip when generating system systemd configuration directory. This has priority over upstream units, boot.initrd.systemd.units, and boot.initrd.systemd.additionalUpstreamUnits. The main purpose of this is to prevent a upstream systemd unit from being added to the initrd with any modifications made to it by other NixOS modules.

Type: list of string

Default: [ ]

Example:

[
  "systemd-backlight@.service"
]

Declared by:

Definition of systemd target units.

Type: attribute set of (submodule)

Default: { }

Declared by:

Definition of systemd timer units.

Type: attribute set of (submodule)

Default: { }

Declared by:

Similar to systemd.tmpfiles.settings but the rules are only applied by systemd-tmpfiles before initrd-switch-root.target.

See bootup(7).

Type: attribute set of attribute set of attribute set of (submodule)

Default: { }

Example:

{
  "10-mypackage" = {
    "/var/lib/my-service/statefolder" = {
      d = {
        group = "root";
        mode = "0755";
        user = "root";
      };
    };
  };
}

Declared by:

Delete a file when it reaches a certain age.

If a file or directory is older than the current time minus the age field, it is deleted.

If set to "-" no automatic clean-up is done.

Type: string

Default: "-"

Example: "10d"

Declared by:

An argument whose meaning depends on the type of operation.

Please see the upstream documentation for the meaning of this parameter in different situations: tmpfiles.d(5)

Type: string

Default: ""

Example: ""

Declared by:

The group of the file.

This may either be a numeric ID or a user/group name.

If omitted or when set to "-", the user and group of the user who invokes systemd-tmpfiles is used.

Type: string

Default: "-"

Example: "root"

Declared by:

The file access mode to use when creating this file or directory.

Type: string

Default: "-"

Example: "0755"

Declared by:

The type of operation to perform on the file.

The type consists of a single letter and optionally one or more modifier characters.

Please see the upstream documentation for the available types and more details: tmpfiles.d(5)

Type: string

Default: "‹tmpfiles-type›"

Example: "d"

Declared by:

The user of the file.

This may either be a numeric ID or a user/group name.

If omitted or when set to "-", the user and group of the user who invokes systemd-tmpfiles is used.

Type: string

Default: "-"

Example: "root"

Declared by:

Whether to enable systemd initrd TPM2 support.

Type: boolean

Default: "boot.initrd.systemd.package.withTpm2Units"

Example: true

Declared by:

Definition of systemd units.

Type: attribute set of (submodule)

Default: { }

Declared by:

Users to include in initrd.

Type: attribute set of (submodule)

Default: { }

Declared by:

Group the user belongs to in initrd.

Type: (optionally newline-terminated) single-line string

Default: config.users.users.${name}.group

Declared by:

The path to the user’s shell in initrd.

Type: absolute path, not containing newlines or colons

Default: ${pkgs.shadow}/bin/nologin

Declared by:

ID of the user in initrd.

Type: signed integer

Default: config.users.users.${name}.uid

Declared by:

Whether to enable the unl0kr on-screen keyboard in initrd to unlock LUKS.

Type: boolean

Default: false

Example: true

Declared by:

The buffybox package to use.

Type: package

Default: pkgs.buffybox

Declared by:

Whether to load additional drivers for certain vendors (I.E: Wacom, Intel, etc.)

Type: boolean

Default: false

Example: true

Declared by:

Configuration for unl0kr.

See unl0kr.conf(5) for supported values.

Alternatively, visit https://gitlab.postmarketos.org/postmarketOS/buffybox/-/blob/3.2.0/unl0kr/unl0kr.conf

Type: attribute set of section of an INI file (attrs of INI atom (null, bool, int, float or string))

Default: { }

Example:

{
  general.animations = true;
  general.backend = "drm";
  theme = {
    default = "pmos-dark";
    alternate = "pmos-light";
  };
}

Declared by:

Verbosity of the initrd. Please note that disabling verbosity removes only the mandatory messages generated by the NixOS scripts. For a completely silent boot, you might also want to set the two following configuration options:

Type: boolean

Default: true

Declared by:

Whether this NixOS machine is a lightweight container running in another NixOS system.

Type: boolean

Default: false

Declared by:

iSCSI portal to boot from.

Type: null or string

Default: null

Example: "192.168.1.1:3260"

Declared by:

Extra lines to append to /etc/iscsid.conf

Type: null or strings concatenated with “\n”

Default: null

Declared by:

Append an additional file’s contents to /etc/iscsid.conf. Use a non-store path and store passwords in this file. Note: the file specified here must be available in the initrd, see: boot.initrd.secrets.

Type: null or string

Default: null

Declared by:

Extra iscsi commands to run in the initrd.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Higher numbers elicits more logs.

Type: signed integer

Default: 1

Example: 8

Declared by:

Do not log into a specific target on the portal, but to all that we discover. This overrides setting target.

Type: boolean

Default: false

Declared by:

Name of the iSCSI initiator to boot from. Note, booting from iscsi requires networkd based networking.

Type: null or string

Default: null

Example: "iqn.2020-08.org.linux-iscsi.initiatorhost:example"

Declared by:

Name of the iSCSI target to boot from.

Type: null or string

Default: null

Example: "iqn.2020-08.org.linux-iscsi.targethost:example"

Declared by:

Whether to enable the Linux kernel. This is useful for systemd-like containers which do not require a kernel.

Type: boolean

Default: true

Example: true

Declared by:

Provides a custom seed for the RANDSTRUCT security option of the Linux kernel. Note that RANDSTRUCT is only enabled in NixOS hardened kernels. Using a custom seed requires building the kernel and dependent packages locally, since this customization happens at build time.

Type: string

Default: ""

Example: "my secret seed"

Declared by:

Runtime parameters of the Linux kernel, as set by sysctl(8). Note that sysctl parameters names must be enclosed in quotes (e.g. "vm.swappiness" instead of vm.swappiness). The value of each parameter may be a string, integer, boolean, or null (signifying the option will not appear at all).

Type: attribute set of (sysctl option value)

Default: { }

Example:

{ "net.ipv4.tcp_syncookies" = false; "vm.swappiness" = 60; }

Declared by:

The maximum receive socket buffer size in bytes. In case of conflicting values, the highest will be used.

Type: null or (unsigned integer, meaning >=0)

Default: null

Declared by:

The maximum send socket buffer size in bytes. In case of conflicting values, the highest will be used.

Type: null or (unsigned integer, meaning >=0)

Default: null

Declared by:

The set of kernel modules to be loaded in the second stage of the boot process. Note that modules that are needed to mount the root file system should be added to boot.initrd.availableKernelModules or boot.initrd.kernelModules.

Type: list of string

Default: [ ]

Declared by:

This option allows you to override the Linux kernel used by NixOS. Since things like external kernel module packages are tied to the kernel you’re using, it also overrides those. This option is a function that takes Nixpkgs as an argument (as a convenience), and returns an attribute set containing at the very least an attribute kernel. Additional attributes may be needed depending on your configuration. For instance, if you use the NVIDIA X driver, then it also needs to contain an attribute nvidia_x11.

Please note that we strictly support kernel versions that are maintained by the Linux developers only. More information on the availability of kernel versions is documented in the Linux section of the manual.

Type: raw value

Default: pkgs.linuxPackages

Example: pkgs.linuxKernel.packages.linux_5_10

Declared by:

Parameters added to the kernel command line.

Type: list of string, with spaces inside double quotes

Default: [ ]

Declared by:

A list of additional patches to apply to the kernel.

Every item should be an attribute set with the following attributes:

{
  name = "foo";                 # descriptive name, required

  patch = ./foo.patch;          # path or derivation that contains the patch source
                                # (required, but can be null if only config changes
                                # are needed)

  extraStructuredConfig = {     # attrset of extra configuration parameters without the CONFIG_ prefix
    FOO = lib.kernel.yes;       # (optional)
  };                            # values should generally be lib.kernel.yes,
                                # lib.kernel.no or lib.kernel.module

  features = {                  # attrset of extra "features" the kernel is considered to have
    foo = true;                 # (may be checked by other NixOS modules, optional)
  };

  extraConfig = "FOO y";        # extra configuration options in string form without the CONFIG_ prefix
                                # (optional, multiple lines allowed to specify multiple options)
                                # (deprecated, use extraStructuredConfig instead)
}

There’s a small set of existing kernel patches in Nixpkgs, available as pkgs.kernelPatches, that follow this format and can be used directly.

Type: list of (attribute set)

Default: [ ]

Example:

[
  {
    name = "foo";
    patch = ./foo.patch;
    extraStructuredConfig.FOO = lib.kernel.yes;
    features.foo = true;
  }
  {
    name = "foo-ml-mbox";
    patch = (fetchurl {
      url = "https://lore.kernel.org/lkml/19700205182810.58382-1-email@domain/t.mbox.gz";
      hash = "sha256-...";
    });
  }
]

Declared by:

Whether the installation process is allowed to modify EFI boot variables.

Type: boolean

Default: false

Declared by:

Where the EFI System Partition is mounted.

Type: string

Default: "/boot"

Declared by:

Whether to enable using an external tool to install your bootloader.

Type: boolean

Default: false

Example: true

Declared by:

The full path to a program of your choosing which performs the bootloader installation process.

The program will be called with an argument pointing to the output of the system’s toplevel.

Type: absolute path

Declared by:

Whether to create symlinks to the system generations under /boot. When enabled, /boot/default/kernel, /boot/default/initrd, etc., are updated to point to the current generation’s kernel image, initial RAM disk, and other bootstrap files.

This optional is not necessary with boot loaders such as GNU GRUB for which the menu is updated to point to the latest bootstrap files. However, it is needed for U-Boot on platforms where the boot command line is stored in flash memory rather than in a menu file.

Type: boolean

Default: false

Declared by:

Whether to copy the necessary boot files into /boot, so /nix/store is not needed by the boot loader.

Type: boolean

Default: false

Declared by:

Whether to generate an extlinux-compatible configuration file under /boot/extlinux.conf. For instance, U-Boot’s generic distro boot support uses this file format.

See U-boot’s documentation for more information.

Type: boolean

Default: false

Declared by:

Maximum number of configurations in the boot menu.

Type: signed integer

Default: 20

Example: 10

Declared by:

Mirror the boot configuration to multiple paths.

Type: list of (submodule)

Default:

[
  {
    path = "/boot";
  }
]

Example:

[
  {
    path = "/boot1";
  }
  {
    path = "/boot2";
  }
]

Declared by:

The path to the boot directory where the extlinux-compatible configuration files will be written.

Type: string

Example: "/boot1"

Declared by:

Contains the builder command used to populate an image, honoring all options except the -c <path-to-default-configuration> argument. Useful to have for sdImage.populateRootCommands

Type: string (read only)

Declared by:

Whether to generate Device Tree-related directives in the extlinux configuration.

When enabled, the bootloader will attempt to load the device tree binaries from the generation’s kernel.

Note that this affects all generations, regardless of the setting value used in their configurations.

Type: boolean

Default: true

Declared by:

Whether to enable the GNU GRUB boot loader.

Type: boolean

Default: !config.boot.isContainer

Declared by:

Enable support for encrypted partitions. GRUB should automatically unlock the correct encrypted partition and look for filesystems.

Type: boolean

Default: false

Declared by:

Background color to be used for GRUB to fill the areas the image isn’t filling.

Type: null or string

Default: null

Example: "#7EBAE4"

Declared by:

Maximum of configurations in boot menu. GRUB has problems when there are too many entries.

Type: signed integer

Default: 100

Example: 120

Declared by:

GRUB entry name instead of default.

Type: string

Default: ""

Example: "Stable 2.6.21"

Declared by:

Whether the GRUB menu builder should copy kernels and initial ramdisks to /boot. This is done automatically if /boot is on a different partition than /.

Type: boolean

Default: false

Declared by:

Index of the default menu item to be booted. Can also be set to “saved”, which will make GRUB select the menu item that was used at the last boot.

Type: signed integer or string

Default: "0"

Declared by:

The device on which the GRUB boot loader will be installed. The special value nodev means that a GRUB boot menu will be generated, but GRUB itself will not actually be installed. To install GRUB on multiple devices, use boot.loader.grub.devices.

Type: string

Default: ""

Example: "/dev/disk/by-id/wwn-0x500001234567890a"

Declared by:

The devices on which the boot loader, GRUB, will be installed. Can be used instead of device to install GRUB onto multiple devices.

Type: list of string

Default: [ ]

Example:

[
  "/dev/disk/by-id/wwn-0x500001234567890a"
]

Declared by:

Whether to invoke grub-install with --removable.

Unless you turn this on, GRUB will install itself somewhere in boot.loader.efi.efiSysMountPoint (exactly where depends on other config variables). If you’ve set boot.loader.efi.canTouchEfiVariables AND you are currently booted in UEFI mode, then GRUB will use efibootmgr to modify the boot order in the EFI variables of your firmware to include this location. If you are not booted in UEFI mode at the time GRUB is being installed, the NVRAM will not be modified, and your system will not find GRUB at boot time. However, GRUB will still return success so you may miss the warning that gets printed (“efibootmgr: EFI variables are not supported on this system.”).

If you turn this feature on, GRUB will install itself in a special location within efiSysMountPoint (namely EFI/boot/boot$arch.efi) which the firmwares are hardcoded to try first, regardless of NVRAM EFI variables.

To summarize, turn this on if:

Type: boolean

Default: false

Declared by:

Whether GRUB should be built with EFI support.

Type: boolean

Default: false

Declared by:

Options applied to the primary NixOS menu entry.

Type: null or string

Default: "--class nixos --unrestricted"

Declared by:

Additional GRUB commands inserted in the configuration file just before the menu entries.

Type: strings concatenated with “\n”

Default: ""

Example:

''
  serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1
  terminal_input --append serial
  terminal_output --append serial
''

Declared by:

Any additional entries you want added to the GRUB boot menu.

Type: strings concatenated with “\n”

Default: ""

Example:

''
  # GRUB 2 example
  menuentry "Windows 7" {
    chainloader (hd0,4)+1
  }
  
  # GRUB 2 with UEFI example, chainloading another distro
  menuentry "Fedora" {
    set root=(hd1,1)
    chainloader /efi/fedora/grubx64.efi
  }
''

Declared by:

Whether extraEntries are included before the default option.

Type: boolean

Default: false

Declared by:

A set of files to be copied to /boot. Each attribute name denotes the destination file name in /boot, while the corresponding attribute value specifies the source file.

Type: attribute set of absolute path

Default: { }

Example:

{ "memtest.bin" = "${pkgs.memtest86plus}/memtest.bin"; }

Declared by:

Additional arguments passed to grub-install.

A use case for this is to build specific GRUB2 modules directly into the GRUB2 kernel image, so that they are available and activated even in the grub rescue shell.

They are also necessary when the BIOS/UEFI is bugged and cannot correctly read large disks (e.g. above 2 TB), so GRUB2’s own nativedisk and related modules can be used to use its own disk drivers. The example shows one such case. This is also useful for booting from USB. See the GRUB source code for which disk modules are available.

The list elements are passed directly as argv arguments to the grub-install program, in order.

Type: list of string

Default: [ ]

Example:

[
  "--modules=nativedisk ahci pata part_gpt part_msdos diskfilter mdraid1x lvm ext2"
]

Declared by:

Additional shell commands inserted in the bootloader installer script after generating menu entries.

Type: strings concatenated with “\n”

Default: ""

Example:

''
  # the example below generates detached signatures that GRUB can verify
  # https://www.gnu.org/software/grub/manual/grub/grub.html#Using-digital-signatures
  ''${pkgs.findutils}/bin/find /boot -not -path "/boot/efi/*" -type f -name '*.sig' -delete
  old_gpg_home=$GNUPGHOME
  export GNUPGHOME="$(mktemp -d)"
  ''${pkgs.gnupg}/bin/gpg --import ''${priv_key} > /dev/null 2>&1
  ''${pkgs.findutils}/bin/find /boot -not -path "/boot/efi/*" -type f -exec ''${pkgs.gnupg}/bin/gpg --detach-sign "{}" \; > /dev/null 2>&1
  rm -rf $GNUPGHOME
  export GNUPGHOME=$old_gpg_home
''

Declared by:

Additional GRUB commands inserted in the configuration file at the start of each NixOS menu entry.

Type: strings concatenated with “\n”

Default: ""

Example: "root (hd0)"

Declared by:

Additional bash commands to be run at the script that prepares the GRUB menu entries.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Path to a TrueType, OpenType, or pf2 font to be used by Grub.

Type: null or absolute path

Default: "${pkgs.grub2}/share/grub/unicode.pf2"

Declared by:

Font size for the grub menu. Ignored unless font is set to a ttf or otf font.

Type: null or signed integer

Default: null

Example: 16

Declared by:

Whether to try and forcibly install GRUB even if problems are detected. It is not recommended to enable this unless you know what you are doing.

Type: boolean

Default: false

Declared by:

Whether to force the use of a ia32 boot loader on x64 systems. Required to install and run NixOS on 64bit x86 systems with 32bit (U)EFI.

Type: boolean

Default: false

Declared by:

Determines how GRUB will identify devices when generating the configuration file. A value of uuid / label signifies that grub will always resolve the uuid or label of the device before using it in the configuration. A value of provided means that GRUB will use the device name as show in df or mount. Note, zfs zpools / datasets are ignored and will always be mounted using their labels.

Type: one of “uuid”, “label”, “provided”

Default: "uuid"

Declared by:

The gfxmode to pass to GRUB when loading a graphical boot interface under BIOS.

Type: string

Default: "1024x768"

Example: "auto"

Declared by:

The gfxmode to pass to GRUB when loading a graphical boot interface under EFI.

Type: string

Default: "auto"

Example: "1024x768"

Declared by:

The gfxpayload to pass to GRUB when loading a graphical boot interface under BIOS.

Type: string

Default: "text"

Example: "keep"

Declared by:

The gfxpayload to pass to GRUB when loading a graphical boot interface under EFI.

Type: string

Default: "keep"

Example: "text"

Declared by:

Set of iPXE scripts available for booting from the GRUB boot menu.

Type: attribute set of (absolute path or string)

Default: { }

Example:

{ demo = ''
    #!ipxe
    dhcp
    chain http://boot.ipxe.org/demo/boot.php
  '';
}

Declared by:

Make Memtest86+, a memory testing program, available from the GRUB boot menu.

Type: boolean

Default: false

Declared by:

Parameters added to the Memtest86+ command line. As of memtest86+ 5.01 the following list of (apparently undocumented) parameters are accepted:

This list of command line options was obtained by reading the Memtest86+ source code.

Type: list of string

Default: [ ]

Example:

[
  "console=ttyS0,115200"
]

Declared by:

Mirror the boot configuration to multiple partitions and install grub to the respective devices corresponding to those partitions.

Type: list of (submodule)

Default: [ ]

Example:

[
  {
    devices = [
      "/dev/disk/by-id/wwn-0x500001234567890a"
    ];
    path = "/boot1";
  }
  {
    devices = [
      "/dev/disk/by-id/wwn-0x500009876543210a"
    ];
    path = "/boot2";
  }
]

Declared by:

The path to the devices which will have the GRUB MBR written. Note these are typically device paths and not paths to partitions.

Type: list of string

Default: [ ]

Example:

[
  "/dev/disk/by-id/wwn-0x500001234567890a"
  "/dev/disk/by-id/wwn-0x500009876543210a"
]

Declared by:

The id of the bootloader to store in efi nvram. The default is to name it NixOS and append the path or efiSysMountPoint. This is only used if boot.loader.efi.canTouchEfiVariables is true.

Type: null or string

Default: null

Example: "NixOS-fsid"

Declared by:

The path to the efi system mount point. Usually this is the same partition as the above path and can be left as null.

Type: null or string

Default: null

Example: "/boot1/efi"

Declared by:

The path to the boot directory where GRUB will be written. Generally this boot path should double as an EFI path.

Type: string

Example: "/boot1"

Declared by:

Background image used for GRUB. Set to null to run GRUB in text mode.

Type: null or absolute path

Example: ./my-background.png

Declared by:

Whether to stretch the image or show the image in the top-left corner unstretched.

Type: one of “normal”, “stretch”

Default: "stretch"

Declared by:

Path to the Nix store when looking for kernels at boot. Only makes sense when copyKernels is false.

Type: string

Default: "/nix/store"

Declared by:

Options applied to the secondary NixOS submenu entry.

Type: null or string

Default: "--class nixos"

Declared by:

Path to the grub theme to be used.

Type: null or absolute path

Default: null

Example: "${pkgs.libsForQt5.breeze-grub}/grub/themes/breeze"

Declared by:

When using a theme, the default value (menu) is appropriate for the graphical countdown.

When attempting to do flicker-free boot, hidden should be used.

See the GRUB documentation section about timeout_style.

From: Simple configuration handling page, under GRUB_TIMEOUT_STYLE.

Type: one of “menu”, “countdown”, “hidden”

Default: "menu"

Declared by:

If set to true, append entries for other OSs detected by os-prober.

Type: boolean

Default: false

Declared by:

User accounts for GRUB. When specified, the GRUB command line and all boot options except the default are password-protected. All passwords and hashes provided will be stored in /boot/grub/grub.cfg, and will be visible to any local user who can read this file. Additionally, any passwords and hashes provided directly in a Nix configuration (as opposed to external files) will be copied into the Nix store, and will be visible to all local users.

Type: attribute set of (submodule)

Default: { }

Example:

{
  root = {
    hashedPasswordFile = "/path/to/file";
  };
}

Declared by:

Specifies the password hash for the account, generated with grub-mkpasswd-pbkdf2. This hash will be copied to the Nix store, and will be visible to all local users.

Type: null or string

Default: null

Example: "grub.pbkdf2.sha512.10000.674DFFDEF76E13EA...2CC972B102CF4355"

Declared by:

Specifies the path to a file containing the password hash for the account, generated with grub-mkpasswd-pbkdf2. This hash will be stored in /boot/grub/grub.cfg, and will be visible to any local user who can read this file.

Type: null or string

Default: null

Example: "/path/to/file"

Declared by:

Specifies the clear text password for the account. This password will be copied to the Nix store, and will be visible to all local users.

Type: null or string

Default: null

Example: "Pa$$w0rd!"

Declared by:

Specifies the path to a file containing the clear text password for the account. This password will be stored in /boot/grub/grub.cfg, and will be visible to any local user who can read this file.

Type: null or string

Default: null

Example: "/path/to/file"

Declared by:

Whether GRUB should be built against libzfs.

Type: boolean

Default: false

Declared by:

Some systems require a /sbin/init script which is started. Or having it makes starting NixOS easier. This applies to some kind of hosting services and user mode linux.

Additionally this script will create /boot/init-other-configurations-contents.txt containing contents of remaining configurations. You can copy paste them into /sbin/init manually running a rescue system or such.

Type: boolean

Default: false

Declared by:

Whether to enable the Limine Bootloader.

Type: boolean

Default: false

Example: true

Declared by:

Whether to allow editing the boot entries before booting them. It is recommended to set this to false, as it allows gaining root access by passing init=/bin/sh as a kernel parameter.

Type: boolean

Default: false

Example: true

Declared by:

The limine package to use.

Type: package

Default: pkgs.limine

Declared by:

A set of files to be copied to /boot. Each attribute name denotes the destination file name in /boot, while the corresponding attribute value specifies the source file.

Type: attribute set of absolute path

Default: { }

Example:

{ "efi/memtest86/memtest86.efi" = "${pkgs.memtest86-efi}/BOOTX64.efi"; }

Declared by:

Device to install the BIOS version of limine on.

Type: string

Default: "nodev"

Declared by:

Whether or not to install limine for BIOS.

Type: boolean

Default: !config.boot.loader.limine.efiSupport && pkgs.stdenv.hostPlatform.isx86

Example: true

Declared by:

Whether or not to install the limine EFI files as removable.

See boot.loader.grub.efiInstallAsRemovable

Type: boolean

Default: !config.boot.loader.efi.canTouchEfiVariables

Example: true

Declared by:

Whether or not to install the limine EFI files.

Type: boolean

Default: pkgs.stdenv.hostPlatform.isEfi

Example: true

Declared by:

Whether or not to enroll the config. Only works on EFI!

Type: boolean

Default: boot.loader.limine.panicOnChecksumMismatch

Example: true

Declared by:

A string which is prepended to limine.conf. The config format can be found here.

Type: strings concatenated with “\n”

Default: ""

Example:

serial: yes

Declared by:

A string which is appended to the end of limine.conf. The config format can be found here.

Type: strings concatenated with “\n”

Default: ""

Example:

/memtest86
  protocol: chainload
  path: boot():///efi/memtest86/memtest86.efi

Declared by:

Force MBR detection to work even if the safety checks fail, use absolutely only if necessary!

Type: boolean

Default: false

Example: true

Declared by:

Maximum number of latest generations in the boot menu. Useful to prevent boot partition of running out of disk space. null means no limit i.e. all generations that were not garbage collected yet.

Type: null or signed integer

Default: null

Example: 50

Declared by:

Whether or not checksum validation failure should be a fatal error at boot time.

Type: boolean

Default: false

Example: true

Declared by:

The 1-based index of the dedicated partition for limine’s second stage.

Type: null or signed integer

Default: null

Declared by:

Color to fill the rest of the screen with when wallpaper_style is centered in RRGGBB format.

Type: null or string

Default: null

Example: "7EBAE4"

Declared by:

Text background color (TTRRGGBB). TT is transparency.

Type: null or string

Default: null

Declared by:

Text background bright color (RRGGBB).

Type: null or string

Default: null

Declared by:

Text foreground bright color (RRGGBB).

Type: null or string

Default: null

Declared by:

A ; seperated array of 8 colors in the format RRGGBB: dark gray, bright red, bright green, yellow, bright blue, bright magenta, bright cyan, and white.

Type: null or string

Default: null

Declared by:

The scale of the font in the format <width>x<height>.

Type: null or string

Default: null

Example: 2x2

Declared by:

The horizontal spacing between characters in pixels.

Type: null or signed integer

Default: null

Declared by:

Text foreground color (RRGGBB).

Type: null or string

Default: null

Declared by:

The amount of margin around the terminal.

Type: null or signed integer

Default: null

Declared by:

The thickness in pixels for the margin around the terminal.

Type: null or signed integer

Default: null

Declared by:

A ; seperated array of 8 colors in the format RRGGBB: black, red, green, brown, blue, magenta, cyan, and gray.

Type: null or string

Default: null

Declared by:

The title at the top of the screen.

Type: null or string

Default: null

Declared by:

Color index of the title at the top of the screen in the range of 0-7 (Limine defaults to 6 (cyan)).

Type: null or signed integer

Default: null

Declared by:

Whether or not to hide the keybinds at the top of the screen.

Type: boolean

Default: false

Example: true

Declared by:

The resolution of the interface.

Type: null or string

Default: null

Declared by:

How the wallpaper should be fit to the screen.

Type: one of “centered”, “streched”, “tiled”

Default: "streched"

Declared by:

A list of wallpapers. If more than one is specified, a random one will be selected at boot.

Type: list of absolute path

Default: [ ]

Example: [ pkgs.nixos-artwork.wallpapers.simple-dark-gray-bootloader.gnomeFilePath ]

Declared by:

Whether to validate file checksums before booting.

Type: boolean

Default: true

Example: true

Declared by:

Whether to enable the systemd-boot (formerly gummiboot) EFI boot manager. For more information about systemd-boot: https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/

Type: boolean

Default: false

Declared by:

Maximum number of latest generations in the boot menu. Useful to prevent boot partition running out of disk space.

null means no limit i.e. all generations that have not been garbage collected yet.

Type: null or signed integer

Default: null

Example: 120

Declared by:

The resolution of the console. The following values are valid:

Type: one of “0”, “1”, “2”, “5”, “auto”, “max”, “keep”

Default: "keep"

Declared by:

Whether to allow editing the kernel command-line before boot. It is recommended to set this to false, as it allows gaining root access by passing init=/bin/sh as a kernel parameter. However, it is enabled by default for backwards compatibility.

Type: boolean

Default: true

Declared by:

Make the EDK2 UEFI Shell available from the systemd-boot menu. It can be used to manually boot other operating systems or for debugging.

Type: boolean

Default: false

Declared by:

systemd-boot orders the menu entries by their sort keys, so if you want something to appear after all the NixOS entries, it should start with o or onwards.

See also boot.loader.systemd-boot.sortKey…

Type: string

Default: "o_edk2-uefi-shell"

Declared by:

Any additional entries you want added to the systemd-boot menu. These entries will be copied to $BOOT/loader/entries. Each attribute name denotes the destination file name, and the corresponding attribute value is the contents of the entry.

To control the ordering of the entry in the boot menu, use the sort-key field, see https://uapi-group.org/specifications/specs/boot_loader_specification/#sorting and boot.loader.systemd-boot.sortKey.

Type: attribute set of strings concatenated with “\n”

Default: { }

Example:

{ "memtest86.conf" = ''
  title Memtest86+
  efi /efi/memtest86/memtest.efi
  sort-key z_memtest
''; }

Declared by:

A set of files to be copied to $BOOT. Each attribute name denotes the destination file name in $BOOT, while the corresponding attribute value specifies the source file.

Type: attribute set of absolute path

Default: { }

Example:

{ "efi/memtest86/memtest.efi" = "${pkgs.memtest86plus}/memtest.efi"; }

Declared by:

Additional shell commands inserted in the bootloader installer script after generating menu entries. It can be used to expand on extra boot entries that cannot incorporate certain pieces of information (such as the resulting init= kernel parameter).

Type: strings concatenated with “\n”

Default: ""

Example:

''
  default_cfg=$(cat /boot/loader/loader.conf | grep default | awk '{print $2}')
  init_value=$(cat /boot/loader/entries/$default_cfg | grep init= | awk '{print $2}')
  sed -i "s|@INIT@|$init_value|g" /boot/custom/config_with_placeholder.conf
''

Declared by: