Module option reference¶
The guide build generates this reference from the selected modules through
nixosOptionsDoc. It includes types, descriptions, defaults and declarations.
Build .#feature-options for the corresponding JSON. The current bounded set
covers Secure Boot preparation, libvirt workstation interfaces, application
recovery recipes and desktop-local service/backup health.
A declared default does not establish that a host selected the feature, that its external prerequisites exist, or that it passed a native test. Use the feature catalog and support table together.
The following types, descriptions and defaults come from the current Nix module declarations. Defaults are not proof that a feature is enabled or deployed.
hardware.storage.encryptedRoot.health.notificationCommand¶
Type:
null or (list of string)
Optional session-independent delivery command. Receives redacted event JSON on stdin and must return success only after accepting delivery. Credentials belong in runtime files; null retains pending warnings locally.
Default:
null
hardware.storage.encryptedRoot.health.probes¶
Type:
attribute set of (submodule)
Additional bounded health commands and successful-work freshness checks. Probe names are public notification labels.
Default:
{ }
hardware.storage.encryptedRoot.health.probes.<name>.command¶
Type:
list of string
Command arguments with an absolute executable; nonzero exit is an alert. Output is never included in notifications.
Default:
[ ]
hardware.storage.encryptedRoot.health.probes.<name>.maxAgeSeconds¶
Type:
positive integer, meaning >0
Maximum age of successful work.
Default:
86400
hardware.storage.encryptedRoot.health.probes.<name>.receipt¶
Type:
null or string
Runtime JSON containing completed Unix seconds and optional result, which must be success. Missing, malformed and future records alert.
Default:
null
hardware.storage.encryptedRoot.health.probes.<name>.timeoutSeconds¶
Type:
positive integer, meaning >0
Maximum command duration.
Default:
15
security.secureBootLanzaboote.bootCountingInitialTries¶
Type:
integer between 1 and 8 (both inclusive)
Number of unsuccessful boot attempts before a newly installed entry is treated as bad and the loader falls back to an older generation.
Default:
3
security.secureBootLanzaboote.configurationLimit¶
Type:
integer between 1 and 8 (both inclusive)
Number of signed boot generations retained on the ESP. Eight is the maximum supported by systemd-pcrlock and leaves practical headroom on small ESPs for UKIs and firmware capsules.
Default:
8
security.secureBootLanzaboote.enable¶
Type:
boolean
Whether to enable a manually provisioned Lanzaboote Secure Boot chain .
Default:
false
security.secureBootLanzaboote.measuredBoot.enable¶
Type:
boolean
Whether to enable systemd-pcrlock policy generation for a future LUKS2 TPM2-unlock policy .
Default:
false
security.secureBootLanzaboote.measuredBoot.pcrs¶
Type:
list of (one of 0, 1, 2, 3, 4, 7)
PCRs represented by the generated policy. PCR 4 covers the measured loader/Lanzaboote boot chain, while PCR 7 covers Secure Boot policy. Firmware PCRs 0-3 are intentionally not selected by default because they make firmware configuration and update recovery more brittle.
Default:
[
4
7
]
security.secureBootLanzaboote.pkiBundle¶
Type:
null or string
Persistent directory containing the Secure Boot signing keys managed outside the Nix store. Set this in host-local configuration.
Default:
null
services.applicationRecovery.applications¶
Type:
attribute set of (submodule)
Application-owned backup exports and isolated recovery drills. Declaring a recipe does not provision backup storage or prove live recovery.
Default:
{ }
services.applicationRecovery.applications.<name>.backup¶
Type:
strings concatenated with "\n"
Persist RECOVERY_EXPORT to a provisioned repository. Return failure unless backup completes. Use a stable application tag because scratch paths change.
services.applicationRecovery.applications.<name>.check¶
Type:
strings concatenated with "\n"
Verify application semantics in RECOVERY_TARGET and fail on mismatch. Successful execution records an isolated drill, never a live recovery claim.
services.applicationRecovery.applications.<name>.export¶
Type:
strings concatenated with "\n"
Export consistent application data into RECOVERY_EXPORT, with declared writers stopped.
services.applicationRecovery.applications.<name>.packages¶
Type:
list of package
Tools used by the declared lifecycle hooks.
Default:
[ ]
services.applicationRecovery.applications.<name>.recover¶
Type:
strings concatenated with "\n"
Fetch one identified application backup into RECOVERY_EXPORT, failing if absent or ambiguous.
services.applicationRecovery.applications.<name>.restore¶
Type:
strings concatenated with "\n"
Restore the recovered export into RECOVERY_TARGET only. Never target live state; the directory is disposable.
services.applicationRecovery.applications.<name>.timeoutSeconds¶
Type:
positive integer, meaning >0
Maximum time for each lifecycle hook and writer control operation.
Default:
3600
services.applicationRecovery.applications.<name>.units¶
Type:
list of string matching the pattern [a-zA-Z0-9@_.:-]+\.service
Writer services stopped during export and backup; only originally active units restart, including on failure. Include socket/timer activation guards in the owning application's configuration.
Default:
[ ]
virtualisation.libvirtWorkstation.emulateAarch64¶
Type:
boolean
Install full-system QEMU so this host can emulate trusted AArch64 guests. Cross-ISA TCG is slow and is not a supported security boundary.
Default:
false
virtualisation.libvirtWorkstation.enable¶
Type:
boolean
Whether to enable a hardened libvirt/QEMU development workstation with declarative private networks, managed storage, a narrow VM lifecycle CLI, and virt-manager .
Default:
false
virtualisation.libvirtWorkstation.guests¶
Type:
attribute set of (submodule)
Existing libvirt domain names exposed to the routine vm command.
This is a lifecycle allowlist, not domain XML or mutable disk state.
Default:
{ }
virtualisation.libvirtWorkstation.guests.<name>.autostart¶
Type:
boolean
Start this domain with libvirtd. Keep this false on an interactive workstation; enabling it is appropriate only after unattended boot, shutdown, update, and recovery tests pass.
Default:
false
virtualisation.libvirtWorkstation.guests.<name>.exclusiveGroup¶
Type:
null or string matching the pattern ^[A-Za-z0-9][A-Za-z0-9_.-]*$
Optional local scheduling group. The vm start command refuses to
start a guest while another allowlisted guest in this group is active.
Default:
null
virtualisation.libvirtWorkstation.guests.<name>.inhibitSleep¶
Type:
boolean
Hold a systemd-logind sleep inhibitor while this domain is active. Use this for guests whose network availability must not be silently interrupted by workstation idle-suspend policy.
Default:
false
virtualisation.libvirtWorkstation.guests.<name>.requiredProfile¶
Type:
null or string matching the pattern ^[A-Za-z0-9][A-Za-z0-9_.-]*$
Boot profile required to start this guest. Libvirt's QEMU hook also
enforces this guard when a graphical manager bypasses the vm CLI.
Default:
null
virtualisation.libvirtWorkstation.guests.<name>.sshHost¶
Type:
null or string matching the pattern ^[A-Za-z0-9][A-Za-z0-9_.-]*$
Existing OpenSSH alias used by vm ssh. Keep this null until the
guest has a unique key and a pinned host-key entry.
Default:
null
virtualisation.libvirtWorkstation.networks¶
Type:
attribute set of (submodule)
Private libvirt networks reconciled at boot. Existing networks are updated persistently but never restarted while guests may be using them.
Default:
{
development = {
bridge = "virbr-dev";
domain = "vm.internal";
ipv4Prefix = "192.168.122";
mode = "nat";
};
}
virtualisation.libvirtWorkstation.networks.<name>.allowHostPing¶
Type:
boolean
Allow IPv4 ICMP echo requests from this network to the host bridge address.
Default:
true
virtualisation.libvirtWorkstation.networks.<name>.allowPrivateEgress¶
Type:
boolean
Allow a NAT guest to initiate connections to private, shared, link-local, multicast, and reserved IPv4 destinations. Public internet egress remains available when this is false.
Default:
false
virtualisation.libvirtWorkstation.networks.<name>.bridge¶
Type:
string matching the pattern ^[A-Za-z0-9][A-Za-z0-9_.-]{0,14}$
Linux bridge name. Linux interface names are limited to 15 characters.
Default:
"virbr-‹name›"
virtualisation.libvirtWorkstation.networks.<name>.dhcp.end¶
Type:
integer between 2 and 254 (both inclusive)
Last dynamic DHCP address in the /24.
Default:
199
virtualisation.libvirtWorkstation.networks.<name>.dhcp.start¶
Type:
integer between 2 and 254 (both inclusive)
First dynamic DHCP address in the /24.
Default:
100
virtualisation.libvirtWorkstation.networks.<name>.domain¶
Type:
string matching the pattern ^[A-Za-z0-9][A-Za-z0-9_.-]*$
Local DNS domain advertised by libvirt's DNS service.
Default:
"‹name›.vm.internal"
virtualisation.libvirtWorkstation.networks.<name>.hostTcpPorts¶
Type:
list of 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Additional TCP ports guests on this network may reach on the host.
Default:
[ ]
virtualisation.libvirtWorkstation.networks.<name>.hostUdpPorts¶
Type:
list of 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Additional UDP ports guests on this network may reach on the host.
Default:
[ ]
virtualisation.libvirtWorkstation.networks.<name>.ipv4Prefix¶
Type:
string matching the pattern ^(10[.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])[.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])|172[.](1[6-9]|2[0-9]|3[01])[.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])|192[.]168[.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9]))$
First three octets of this RFC 1918 private /24 subnet.
virtualisation.libvirtWorkstation.networks.<name>.isolateGuests¶
Type:
boolean
Prevent guests on this libvirt network from directly talking to one another.
Default:
true
virtualisation.libvirtWorkstation.networks.<name>.mode¶
Type:
one of "isolated", "nat"
Whether this network is host-only or has outbound NAT.
Default:
"nat"
virtualisation.libvirtWorkstation.networks.<name>.reservations¶
Type:
attribute set of (submodule)
Fixed DHCP leases keyed by guest DNS name.
Default:
{ }
virtualisation.libvirtWorkstation.networks.<name>.reservations.<name>.address¶
Type:
integer between 2 and 254 (both inclusive)
Final octet of this guest's fixed address on the network.
virtualisation.libvirtWorkstation.networks.<name>.reservations.<name>.macAddress¶
Type:
string matching the pattern ^[0-9a-fA-F][26aAeE](:[0-9a-fA-F]{2}){5}$
Stable, locally administered guest interface MAC address.
virtualisation.libvirtWorkstation.operators¶
Type:
list of non-empty string
Existing local accounts allowed to use the allowlisted vm lifecycle
command and write installation media. This does not grant membership in
libvirtd, kvm, disk, or a VFIO group.
Default:
[ ]
virtualisation.libvirtWorkstation.storage.installationMedia¶
Type:
string matching the pattern ^/[A-Za-z0-9._+/-]+$
Absolute directory where operators may stage trusted ISO images.
Default:
"/var/lib/libvirt/boot"
virtualisation.libvirtWorkstation.storage.nocow¶
Type:
boolean
Set the NOCOW directory attribute for newly created images. Enable this only when the storage filesystem supports it, such as Btrfs.
Default:
false
virtualisation.libvirtWorkstation.storage.poolName¶
Type:
string matching the pattern ^[A-Za-z0-9][A-Za-z0-9_.-]*$
Name of the managed directory storage pool.
Default:
"default"
virtualisation.libvirtWorkstation.storage.root¶
Type:
string matching the pattern ^/[A-Za-z0-9._+/-]+$
Absolute directory containing mutable guest disks.
Default:
"/var/lib/libvirt/images"
virtualisation.libvirtWorkstation.usbRedirection.enable¶
Type:
boolean
Whether to enable SPICE USB redirection. It installs a privileged helper that lets VM operators access arbitrary USB devices, so it remains opt-in .
Default:
false
virtualisation.libvirtWorkstation.vfio.blacklistedModules¶
Type:
list of non-empty string
Host drivers prevented from claiming the passed device functions.
Default:
[ ]
virtualisation.libvirtWorkstation.vfio.devices¶
Type:
attribute set of (submodule)
Every PCI function in each passed IOMMU group. These host-local facts are checked at runtime before a guarded guest starts.
Default:
{ }
virtualisation.libvirtWorkstation.vfio.devices.<name>.iommuGroup¶
Type:
unsigned integer, meaning >=0
Expected IOMMU group, rechecked by vm doctor before use.
virtualisation.libvirtWorkstation.vfio.devices.<name>.pciAddress¶
Type:
string matching the pattern ^[0-9a-fA-F]{4}:[0-9a-fA-F]{2}:[0-9a-fA-F]{2}[.][0-7]$
Full PCI address of this function.
virtualisation.libvirtWorkstation.vfio.devices.<name>.vendorDeviceId¶
Type:
string matching the pattern ^[0-9a-fA-F]{4}:[0-9a-fA-F]{4}$
Lower- or upper-case PCI vendor and device ID used by vfio-pci.
virtualisation.libvirtWorkstation.vfio.disableSunshine¶
Type:
boolean
Disable the NixOS Sunshine service in the VFIO specialization when present.
Default:
true
virtualisation.libvirtWorkstation.vfio.enable¶
Type:
boolean
Whether to enable a reboot-selected VFIO boot specialization for explicitly declared PCI functions .
Default:
false
virtualisation.libvirtWorkstation.vfio.hostInitrdModules¶
Type:
list of non-empty string
Host display modules loaded before VFIO in the specialization initrd.
Default:
[ ]
virtualisation.libvirtWorkstation.vfio.hostVideoDrivers¶
Type:
list of non-empty string
Display drivers retained by the NixOS host in the VFIO specialization.
Default:
[ ]
virtualisation.libvirtWorkstation.vfio.specialisationName¶
Type:
string matching the pattern ^[A-Za-z0-9][A-Za-z0-9_.-]*$
Boot specialization name and runtime profile marker.
Default:
"windows-vfio"
virtualisation.libvirtWorkstation.windowsVm.administrator.disableUac¶
Type:
boolean
Disable UAC so every process in the administrator session gets its full token. This intentionally removes a Windows security boundary.
Default:
false
virtualisation.libvirtWorkstation.windowsVm.administrator.name¶
Type:
string matching the pattern ^[A-Za-z][A-Za-z0-9._-]{0,19}$
Local administrator used for autologon, debugging, and the private runtime.
Default:
"vmadmin"
virtualisation.libvirtWorkstation.windowsVm.autostart¶
Type:
boolean
Start Windows with libvirtd after unattended recovery has been tested.
Default:
false
virtualisation.libvirtWorkstation.windowsVm.baseline.profile¶
Type:
one of "balanced", "headless-runtime"
Coherent Windows policy profile. The headless-runtime profile removes interactive shell overhead and browser background startup while preserving Windows security, update, Store, and WebView components.
Default:
"balanced"
virtualisation.libvirtWorkstation.windowsVm.baseline.removeAppxPackages¶
Type:
list of string matching the pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$
Exact Appx DisplayName selectors to remove from installed and provisioned packages. This is intentionally an explicit allowlist; core Windows packages must not be included.
Default:
[ ]
virtualisation.libvirtWorkstation.windowsVm.computerName¶
Type:
string matching the pattern ^[A-Za-z][A-Za-z0-9-]{0,14}$
Windows computer name, limited to the NetBIOS-compatible 15-character form.
Default:
"WIN-RUNTIME"
virtualisation.libvirtWorkstation.windowsVm.diskSerial¶
Type:
string matching the pattern ^[A-Z0-9]{4,20}$
Stable virtual system-disk serial number.
Default:
"WINRUNTIME001"
virtualisation.libvirtWorkstation.windowsVm.enable¶
Type:
boolean
Whether to enable a declaratively defined, unattended Windows 11 libvirt guest.
Default:
false
virtualisation.libvirtWorkstation.windowsVm.generationId¶
Type:
string matching the pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
Stable Windows VM generation identifier used for snapshot and restore detection.
virtualisation.libvirtWorkstation.windowsVm.installation.downloadPage¶
Type:
string matching the pattern ^https://.+
Stable official source page for acquiring the ISO. This is kept separate from short-lived or authenticated artifact URLs.
virtualisation.libvirtWorkstation.windowsVm.installation.editionId¶
Type:
non-empty string
Expected Windows CurrentVersion EditionID after installation.
virtualisation.libvirtWorkstation.windowsVm.installation.imageName¶
Type:
non-empty string
Exact /IMAGE/NAME value from install.wim or install.esd. Media verification fails before installation unless this image exists.
virtualisation.libvirtWorkstation.windowsVm.installation.isoFileName¶
Type:
string matching the pattern ^[A-Za-z0-9][A-Za-z0-9._-]*[.]iso$
Fixed filename below the libvirt installation-media directory.
Default:
"windows-11.iso"
virtualisation.libvirtWorkstation.windowsVm.installation.isoSha256¶
Type:
string matching the pattern ^[0-9a-fA-F]{64}$
Exact SHA-256 published by Microsoft for the selected ISO. The installer refuses any staged media whose bytes do not match it.
virtualisation.libvirtWorkstation.windowsVm.installation.locale¶
Type:
string matching the pattern ^[a-z]{2}-[A-Z]{2}$
Windows Setup locale.
Default:
"en-US"
virtualisation.libvirtWorkstation.windowsVm.installation.mediaDescription¶
Type:
non-empty string
Human-readable description of the exact Microsoft installation media.
virtualisation.libvirtWorkstation.windowsVm.installation.release¶
Type:
non-empty string
Pinned Windows release identifier represented by the ISO.
virtualisation.libvirtWorkstation.windowsVm.installation.timeZone¶
Type:
non-empty string
Windows time-zone identifier.
Default:
"Pacific Standard Time"
virtualisation.libvirtWorkstation.windowsVm.machine¶
Type:
string matching the pattern ^pc-q35-[0-9]+[.][0-9]+$
Pinned QEMU machine ABI for durable Windows virtual hardware.
Default:
"pc-q35-10.2"
virtualisation.libvirtWorkstation.windowsVm.maintenance.activeHoursEnd¶
Type:
integer between 0 and 23 (both inclusive)
End of Windows Update active hours.
Default:
23
virtualisation.libvirtWorkstation.windowsVm.maintenance.activeHoursStart¶
Type:
integer between 0 and 23 (both inclusive)
Start of Windows Update active hours.
Default:
5
virtualisation.libvirtWorkstation.windowsVm.managementNetwork¶
Type:
non-empty string
Host-only network used for the host-restricted OpenSSH rule.
virtualisation.libvirtWorkstation.windowsVm.name¶
Type:
string matching the pattern ^[A-Za-z0-9][A-Za-z0-9_.-]*$
Stable libvirt domain and disk basename.
Default:
"windows-runtime"
virtualisation.libvirtWorkstation.windowsVm.networks¶
Type:
list of non-empty string
Ordered libvirt network names. Each must reserve this guest's stable MAC address.
Default:
[ ]
virtualisation.libvirtWorkstation.windowsVm.resources.cpuShares¶
Type:
integer between 2 and 262144 (both inclusive)
Relative libvirt CPU shares; unused host CPU remains available to the guest.
Default:
512
virtualisation.libvirtWorkstation.windowsVm.resources.diskSizeGiB¶
Type:
integer between 64 and 1024 (both inclusive)
Sparse qcow2 virtual disk capacity in GiB.
Default:
128
virtualisation.libvirtWorkstation.windowsVm.resources.memoryMiB¶
Type:
integer between 4096 and 24576 (both inclusive)
Guest memory ceiling in MiB.
Default:
8192
virtualisation.libvirtWorkstation.windowsVm.resources.vcpus¶
Type:
integer between 2 and 16 (both inclusive)
Unpinned virtual CPUs. Idle vCPUs consume no dedicated host core.
Default:
4
virtualisation.libvirtWorkstation.windowsVm.uuid¶
Type:
string matching the pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
Stable libvirt and SMBIOS UUID. Never change this after Windows activation.