Appendix A. Configuration Options

This is a modular service, which can be imported into a NixOS configuration using the system.services option.

Type: submodule

Package to use for ghostunnel

Type: package

Default:

"The ghostunnel package that provided this module."

Declared by:

If true, allow all clients, do not check client cert subject.

Type: boolean

Default:

false

Declared by:

Allow client if common name appears in the list.

Type: list of string

Default:

[ ]

Declared by:

Allow client if DNS subject alternative name appears in the list.

Type: list of string

Default:

[ ]

Declared by:

Allow client if organizational unit name appears in the list.

Type: list of string

Default:

[ ]

Declared by:

Allow client if URI subject alternative name appears in the list.

Type: list of string

Default:

[ ]

Declared by:

Path to CA bundle file (PEM/X509). Uses system trust store if null.

Type: null or string

Default:

null

Declared by:

Path to certificate (PEM with certificate chain).

Not required if keystore is set.

Type: null or string

Default:

null

Declared by:

Disable client authentication, no client certificate will be required.

Type: boolean

Default:

false

Declared by:

Extra arguments to pass to ghostunnel server

Type: list of string

Default:

[ ]

Declared by:

Path to certificate private key (PEM with private key).

Not required if keystore is set.

Type: null or string

Default:

null

Declared by:

Path to keystore (combined PEM with cert/key, or PKCS12 keystore).

NB: storepass is not supported because it would expose credentials via /proc/*/cmdline.

Specify this or cert and key.

Type: null or string

Default:

null

Declared by:

Address and port to listen on (can be HOST:PORT, unix:PATH).

Type: string

Declared by:

Address to forward connections to (can be HOST:PORT or unix:PATH).

Type: string

Declared by:

If set, does not limit target to localhost, 127.0.0.1, [::1], or UNIX sockets.

This is meant to protect against accidental unencrypted traffic on untrusted networks.

Type: boolean

Default:

false

Declared by:

This is a modular service, which can be imported into a NixOS configuration using the system.services option.

Type: submodule

Package to use for tlshd.

Type: package

Default: The ktls-utils package that provided this module.

Declared by:

Configuration for tlshd in INI format. See tlshd.conf(5) for available options.

Type: attribute set of attribute set of string

Default:

{ }

Example:

{
  "authenticate.server" = {
    "x509.certificate" = "/var/lib/tlshd/cert.pem";
    "x509.private_key" = "/var/lib/tlshd/key.pem";
    "x509.truststore" = "/var/lib/tlshd/truststore.pem";
  };
}

Declared by:

This is a modular service, which can be imported into a NixOS configuration using the system.services option.

Type: submodule

PHP package to use for php-fpm

Type: package

Default: The PHP package that provided this module.

Example:

php.buildEnv {
  extensions =
    { all, ... }:
    with all;
    [
      imagick
      opcache
    ];
  extraConfig = "memory_limit=256M";
}

Declared by:

PHP FPM configuration. Refer to upstream documentation for details on supported values.

Type: open submodule of attribute set of (string or signed integer or boolean or (open submodule of attribute set of (string or signed integer or boolean)))

Default:

{ }

Example:

{
  log_level = "debug";
  log_limit = 2048;

  mypool = {
    "user" = "php";
    "group" = "php";
    "listen.owner" = "caddy";
    "listen.group" = "caddy";
    "pm" = "dynamic";
    "pm.max_children" = 75;
    "pm.start_servers" = 10;
    "pm.min_spare_servers" = 5;
    "pm.max_spare_servers" = 20;
    "pm.max_requests" = 500;
  }
}

Declared by:

Error log level.

Type: one of “alert”, “error”, “warning”, “notice”, “debug”

Default:

"notice"

Declared by:

This is a modular service, which can be imported into a NixOS configuration using the system.services option.

Type: submodule

Package to use for snid.

Type: package

Default:

"The snid package that provided this module."

Declared by:

Subnets to which connections may be forwarded. Connections to addresses outside these subnets are rejected. Used in nat46 and tcp modes.

Type: list of string

Default:

[ ]

Example:

[
  "2001:db8::/64"
  "192.0.2.0/24"
]

Declared by:

Port number to connect to on the backend in TCP mode. If null, snid uses the same port as the inbound connection.

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

Default:

null

Declared by:

Hostname to use if a client does not include the SNI extension. If null, SNI-less connections will be terminated with a TLS alert.

Type: null or string

Default:

null

Declared by:

Addresses to listen on, in go-listener syntax.

Examples: "tcp:443", "tcp:0.0.0.0:443", "tcp:192.0.2.4:443".

Type: list of string

Default:

[ ]

Example:

[
  "tcp:0.0.0.0:443"
]

Declared by:

Proxy mode. One of nat46, tcp, or unix.

Type: one of “nat46”, “tcp”, “unix”

Declared by:

IPv6 prefix for the source address when connecting to the backend in NAT46 mode. The client’s IPv4 address is placed in the lower 4 bytes.

Note: this prefix must be routed to the local host, e.g.

ip route add local 64:ff9b:1::/96 dev lo

Type: null or string

Default:

null

Example:

"64:ff9b:1::"

Declared by:

Use PROXY protocol v2 to convey the client IP address to the backend. Applicable in tcp and unix modes.

Type: boolean

Default:

false

Declared by:

Path to the directory containing UNIX domain sockets, used in unix mode.

Type: null or absolute path

Default:

null

Declared by:

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

Default:

{ }

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.

Type: boolean

Default:

config.containers != { }

Declared by:

Whether to enable bcache mount support.

Type: boolean

Default:

true

Example:

false

Declared by:

The bcachefs-tools package to use. This package should also provide a passthru ‘kernelModule’ attribute to build the out-of-tree kernel module.

Type: package

Default:

pkgs.bcachefs-tools

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:

Set of names of kernel modules that should not be loaded automatically by the hardware probing code. This can either be a list of modules or an attrset. In an attrset, names that are set to true represent modules that will be blacklisted.

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

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:

The bootspec package to use.

Type: package

Default:

pkgs.bootspec

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:

Whether the initrd can be built even though modules listed in boot.initrd.kernelModules or boot.initrd.availableKernelModules are missing from the kernel. This is useful when combining configurations that include a lot of modules, such as hardware.enableAllHardware, with kernels that don’t provide as many modules as typical NixOS kernels.

Note that enabling this is discouraged. Instead, try disabling individual modules by setting e.g. boot.initrd.availableKernelModules.foo = lib.mkForce false;

Type: boolean

Default:

false

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.

This can either be a list of modules, or an attrset. In an attrset, names that are set to true represent modules that will be included. Note that setting these names to false does not prevent the module from being loaded. For that, use boot.blacklistedKernelModules.

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

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:

The clevis package to use.

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:

Whether to enable clevis-luks-askpass in initrd.

Watches for systemd password requests during boot and answers them using clevis tokens bound to LUKS headers. Runs in parallel with the interactive password prompt. If clevis cannot unlock a device (tang unreachable, no binding, etc.) the user can still type the passphrase.

Prerequisites:

Type: boolean

Default:

false

Example:

true

Declared by:

The clevis package to use.

Type: package

Default:

pkgs.clevis

Declared by:

Whether the Clevis headers 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:

Set of modules that are always loaded by the initrd.

This can either be a list of modules, or an attrset. In an attrset, names that are set to true represent modules that will be included. Note that setting these names to false does not prevent the module from being loaded. For that, use boot.blacklistedKernelModules.

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

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"
  "blowfish"
  "twofish"
  "serpent"
  "cbc"
  "xts"
  "lrw"
  "sha1"
  "sha256"
  "sha512"
  "af_alg"
  "algif_skcipher"
  "cryptd"
  "input_leds"
]

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:

Only used with systemd stage 1.

Extra options to append to the last column of the generated crypttab file.

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

Default:

[ ]

Example:

[
  "_netdev"
]

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:

Whether to enable initrd networking using IfState.

Type: boolean

Default:

false

Example:

true

Declared by:

The initrd IfState package to use.

Type: package

Default:

pkgs.ifstate.override { withConfigValidation = false; }

Declared by:

IfState in initrd drastically increases the size of initrd, your boot partition may be too small and/or you may have significantly fewer generations. By setting this option, you acknowledge this fact and keep it in mind when reporting issues.

Type: boolean

Default:

false

Declared by:

Content of IfState’s initrd cleanup configuration file. See https://ifstate.net/2.0/schema/ for details. This configuration gets applied before systemd switches to stage two. The goal is to deconfigurate the whole network in order to prevent access to services, before the firewall is configured. The stage two IfState configuration will start after the firewall is configured.

Type: YAML 1.1 value

Default:

{
  interfaces = { };
}

Declared by:

Content of IfState’s initrd configuration file. See https://ifstate.net/2.2/schema/ for details.

Type: YAML 1.1 value

Default:

{ }

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:

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

Whether to enable nix-store-veritysetup.

Type: boolean

Default:

false

Example:

true

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:

The greeting message displayed during NixOS stage 1 boot.

Type: string

Default:

"<<< ${config.system.nixos.distroName} Stage 1 >>>"

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:

true

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:

true

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.

For emergency access after initrd, use systemd.enableEmergencyMode instead.

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:

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:

''
  {
    PATH = "/bin:/sbin";
  }
''

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 whether to issue the BLKDISCARD I/O control command on the space taken up by any added partitions or on the space in between them. Usually, it’s a good idea to issue this request since it tells the underlying hardware that the covered blocks shall be considered empty, improving performance.

See systemd-repart(8) for details.

Type: boolean

Default:

true

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:

Extra command-line arguments to pass to systemd-repart.

See systemd-repart(8) for all available options.

Type: list of string

Default:

[ ]

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. If root shall be omitted, set this option to null.

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

Options for the global systemd service manager used in initrd. See systemd-system.conf(5) man page for available options.

Type: open submodule of attribute set of (systemd option)

Default:

{
  DefaultEnvironment = "PATH=/bin:/sbin";
}

Example:

{
  KExecWatchdogSec = "5min";
  RebootWatchdogSec = "10min";
  RuntimeWatchdogSec = "30s";
  WatchdogDevice = "/dev/watchdog";
}

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:

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:

Whether to enable systemd initrd boot phase measurements.

Type: boolean

Default:

false

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: open submodule of 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:

"config.boot.isNspawnContainer"

Declared by:

Whether the machine is running in an nspawn container. This option is added because boot.isContainer is heavily used for non-nspawn environments as well, hence nspawn-specific settings are guarded by this option.

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: open submodule of 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:

sysfs attributes to be set as soon as they become available.

Attribute names represent path components in the sysfs filesystem and cannot be . or .. nor contain any slash character (/).

Names may contain shell‐style glob patterns (*, ? and […]) matching a single path component, these should however be used with caution, as they may produce unexpected results if attribute paths overlap.

Values will be converted to strings, with list elements concatenated with commata and booleans converted to numeric values (0 or 1).

null values are ignored, allowing removal of values defined in other modules, as are empty attribute sets.

List values defined in different modules will not be concatenated.

This option may only be used for attributes which can be set idempotently, as the configured values might be written more than once.

Type: open submodule of nested attribute set of null or sysfs attribute values

Default:

{ }

Example:

{
  # enable transparent hugepages with deferred defragmentaion
  kernel.mm.transparent_hugepage = {
    enabled = "always";
    defrag = "defer";
    shmem_enabled = "within_size";
  };

  devices.system.cpu = {
    # configure powesave frequency governor for all CPUs
    # the [0-9]* glob pattern ensures that other paths
    # like cpufreq or cpuidle are not matched
    "cpu[0-9]*" = {
      scaling_governor = "powersave";
      energy_performance_preference = 8;
    };

    # disable frequency boost
    intel_pstate.no_turbo = true;
  };
}

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.

This can either be a list of modules, or an attrset. In an attrset, names that are set to true represent modules that will be included. Note that setting these names to false does not prevent the module from being loaded. For that, use boot.blacklistedKernelModules.

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

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)

  structuredExtraConfig = {     # 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 structuredExtraConfig 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;
    structuredExtraConfig.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 to enable kexec.

Type: boolean

Default:

lib.meta.availableOn pkgs.stdenv.hostPlatform pkgs.kexec-tools

Example:

true

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.efi; }

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: