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:

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: 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: 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:

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: 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: 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: 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: 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 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 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 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 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 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: path

Declared by:

Path of the symlink.

Type: null or 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 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:

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 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 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: path

Declared by:

Path of the symlink.

Type: null or 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: https://www.freedesktop.org/software/systemd/man/tmpfiles.d

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: https://www.freedesktop.org/software/systemd/man/tmpfiles.d

Type: string

Default: "‹name›"

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.withTpm2Tss"

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: 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:

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.com/postmarketOS/buffybox/-/blob/unl0kr-2.0.0/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;
  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: 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 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 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 (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 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 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 create files with the system generations in /boot. /boot/old will hold files from old generations.

Type: boolean

Default: false

Declared by:

Extra options that will be appended to /boot/config.txt file. For possible values, see: https://www.raspberrypi.com/documentation/computers/config_txt.html

Type: null or strings concatenated with “\n”

Default: null

Declared by:

Enable using uboot as bootmanager for the raspberry pi.

Type: boolean

Default: false

Declared by:

Maximum number of configurations in the boot menu.

Type: signed integer

Default: 20

Example: 10

Declared by:

Type: one of 0, 1, 2, 3, 4

Default: 2

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 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:

Invoke bootctl install with the --graceful option, which ignores errors when EFI variables cannot be written or when the EFI System Partition cannot be found. Currently only applies to random seed operations.

Only enable this option if systemd-boot otherwise fails to install, as the scope or implication of the --graceful option may change in the future.

Type: boolean

Default: false

Declared by:

Install the devicetree blob specified by config.hardware.deviceTree.name to the ESP and instruct systemd-boot to pass this DTB to linux.

Type: unspecified value

Default: "with config.hardware.deviceTree; enable && name != null"

Declared by:

Make Memtest86+ available from the systemd-boot menu. Memtest86+ is a program for testing memory.

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_memtest86"

Declared by:

Make netboot.xyz available from the systemd-boot menu. netboot.xyz is a menu system that allows you to boot OS installers and utilities over the network.

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_netbootxyz"

Declared by:

Enable EXPERIMENTAL BitLocker support.

Try to detect BitLocker encrypted drives along with an active TPM. If both are found and Windows Boot Manager is selected in the boot menu, set the “BootNext” EFI variable and restart the system. The firmware will then start Windows Boot Manager directly, leaving the TPM PCRs in expected states so that Windows can unseal the encryption key.

Type: boolean

Default: false

Declared by:

The sort key used for the NixOS bootloader entries. This key determines sorting relative to non-NixOS entries. See also https://uapi-group.org/specifications/specs/boot_loader_specification/#sorting

This option can also be used to control the sorting of NixOS specialisations.

By default, specialisations inherit the sort key of their parent generation and will have the same value for both the sort-key and the version (i.e. the generation number), systemd-boot will therefore sort them based on their file name, meaning that in your boot menu you will have each main generation directly followed by its specialisations sorted alphabetically by their names.

If you want a different ordering for a specialisation, you can override its sort-key which will cause the specialisation to be uncoupled from its parent generation. It will then be sorted by its new sort-key just like any other boot entry.

The sort-key is stored in the generation’s bootspec, which means that generations keep their sort-keys even if the original definition of the generation was removed from the NixOS configuration. It also means that updating the sort-key will only affect new generations, while old ones will keep the sort-key that they were originally built with.

Type: string

Default: "nixos"

Declared by:

Make Windows bootable from systemd-boot. This option is not necessary when Windows and NixOS use the same EFI System Partition (ESP). In that case, Windows will automatically be detected by systemd-boot.

However, if Windows is installed on a separate drive or ESP, you can use this option to add a menu entry for each installation manually.

The attribute name is used for the title of the menu entry and internal file names.

Type: attribute set of (submodule)

Default: { }

Example:

{
  "10".efiDeviceHandle = "HD0c3";
  "11-ame" = {
    title = "Windows 11 Ameliorated Edition";
    efiDeviceHandle = "HD0b1";
  };
  "11-home" = {
    title = "Windows 11 Home";
    efiDeviceHandle = "FS1";
    sortKey = "z_windows";
  };
}

Declared by:

The device handle of the EFI System Partition (ESP) where the Windows bootloader is located. This is the device handle that the EDK2 UEFI Shell uses to load the bootloader.

To find this handle, follow these steps:

This option is required, there is no useful default.

Type: string

Example: "HD1b3"

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: "attribute name of this entry, prefixed with \"o_windows_\""

Declared by:

The title of the boot menu entry.

Type: string

Default: "attribute name of this entry, prefixed with \"Windows \""

Example: "Michaelsoft Binbows"

Declared by:

Where the XBOOTLDR partition is mounted.

If set, this partition will be used as $BOOT to store boot loader entries and extra files instead of the EFI partition. As per the bootloader specification, it is recommended that the EFI and XBOOTLDR partitions be mounted at /efi and /boot, respectively.

Type: null or string

Default: null

Declared by:

Timeout (in seconds) until loader boots the default menu item. Use null if the loader menu should be displayed indefinitely.

Type: null or signed integer

Default: 5

Declared by:

Whether to enable modprobe config. This is useful for systems like containers which do not require a kernel.

Type: boolean

Default: true

Example: true

Declared by:

Whether to enable Plymouth boot splash screen.

Type: boolean

Default: false

Example: true

Declared by:

Literal string to append to configFile and the config file generated by the plymouth module.

Type: strings concatenated with “\n”

Default: ""

Declared by:

Font file made available for displaying text on the splash screen.

Type: path

Default: "${pkgs.dejavu_fonts.minimal}/share/fonts/truetype/DejaVuSans.ttf"

Declared by:

Logo which is displayed on the splash screen. Currently supports PNG file format only.

Type: path

Default: "${pkgs.nixos-icons}/share/icons/hicolor/48x48/apps/nix-snowflake-white.png"

Example:

pkgs.fetchurl {
  url = "https://nixos.org/logo/nixos-hires.png";
  sha256 = "1ivzgd7iz0i06y36p8m5w48fd8pjqwxhdaavc0pxs7w1g7mcy5si";
}

Declared by:

Splash screen theme.

Type: string

Default: "bgrt"

Declared by:

Extra theme packages for plymouth.

Type: list of package

Default: A NixOS branded variant of the breeze theme when config.boot.plymouth.theme == "breeze", otherwise [ ].

Declared by:

Shell commands to be executed just before systemd is started.

Type: strings concatenated with “\n”

Default: ""

Example: "rm -f /var/log/messages"

Declared by:

If set, NixOS will enforce the immutability of the Nix store by making /nix/store a read-only bind mount. Nix will automatically make the store writable when needed.

Type: boolean

Default: true

Declared by:

Device for manual resume attempt during boot. This should be used primarily if you want to resume from file. If left empty, the swap partitions are used. Specify here the device where the file resides. You should also use boot.kernelParams to specify «resume_offset».

Type: string

Default: ""

Example: "/dev/sda3"

Declared by:

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

Type: string

Default: "25%"

Example: "256m"

Declared by:

List of paths that should be mounted before this one. This filesystem’s device and mountPoint are always checked and do not need to be included explicitly. If a path is added to this list, any other filesystem whose mount point is a parent of the path will be mounted before this filesystem. The paths do not need to actually be the mountPoint of some other filesystem.

Type: list of string (with check: non-empty without trailing slash)

Default: [ ]

Example:

[
  "/persist"
]

Declared by:

Location of the device.

Type: null or string (with check: non-empty)

Default: null

Example: "/dev/sda"

Declared by:

Type of the file system.

Type: string (with check: non-empty)

Default: "auto"

Example: "ext3"

Declared by:

Location of the mounted file system.

Type: string (with check: non-empty without trailing slash)

Example: "/mnt/usb"

Declared by:

Options used to mount the file system.

Type: non-empty (list of string (with check: non-empty))

Default:

[
  "defaults"
]

Example:

[
  "data=journal"
]

Declared by:

UUID of the stratis pool that the fs is located in

Type: null or string

Default: null

Example: "04c68063-90a5-4235-b9dd-6180098a20d9"

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