Validate NixOS Configuration Changes in a QEMU VM Before Rebuilding Hardware

Decision: validate before you switch

Running nixos-rebuild switch applies a new NixOS configuration to the running host immediately. If the configuration breaks networking, a critical service, or the bootloader, the failure happens on physical hardware and may require physical access to fix. The useful takeaway is to build and boot the same configuration in a QEMU/KVM virtual machine first, confirm it works, and only then run nixos-rebuild switch on the host.

Constraints and what the VM can and cannot test

nixos-rebuild build-vm constructs a QEMU/KVM virtual machine from your active NixOS configuration without modifying the running host. The VM uses the same systemd units, services, kernel, and boot configuration as the target system. It is useful for validating service startup, networking configuration, firewall rules, and systemd unit behavior.

The VM cannot test physical hardware drivers, firmware, Wi-Fi cards, or devices that exist only on the bare-metal machine. A configuration that boots in the VM may still fail after nixos-rebuild switch if it depends on a specific physical NIC, GPU driver, or disk controller.

Supported options compared

Option	What it validates	Risk to running host	Physical hardware coverage	Best used for
nixos-rebuild build-vm plus ./result/bin/run-nixos-vm	Boot process, systemd services, networking, firewall, and configuration syntax in a VM	Low; does not alter the host system	None; emulated hardware only	Pre-deployment validation of configuration changes
nixos-rebuild build	That the configuration derivation builds without errors	Low; no runtime behavior	None	CI pipelines and build-cache checks
nixos-rebuild switch	Actual behavior on the host, including physical hardware and bootloader	High; can break boot, network, or services	Full; runs on bare metal	Applying validated changes to production hardware

Trade-offs

• Safety versus hardware fidelity. The VM catches configuration logic errors and broken services, but it cannot reveal a missing physical driver or firmware issue.
• Ephemeral state. Changes made inside the VM are discarded when it stops. Only the host switch persists configuration.
• Resource cost. Building a VM image consumes disk space and RAM. Large configurations may take several minutes before the VM is ready to boot.
• Permissions. nixos-rebuild requires root access to write system profiles and bootloader entries. The VM typically needs access to /dev/kvm, either through kvm group membership or root privileges.

Implementation: validate, then apply

1. Prepare the host

Run these commands on the NixOS host where you intend to apply the change. Ensure QEMU and KVM are available and that your user can access /dev/kvm.

# Check KVM device access
ls -l /dev/kvm

# If your user is not in the kvm group, use sudo for the VM step or add yourself:
sudo usermod -aG kvm "$USER"

Group membership changes require a new login session to take effect.

2. Edit the configuration

Make your intended change in /etc/nixos/configuration.nix. For example, enable the OpenSSH server, set a hostname, and open SSH in the firewall:

{ config, pkgs, ... }:

{
  networking.hostname = "nixos-validation-host";
  networking.firewall.allowedTCPPorts = [ 22 ];

  services.openssh.enable = true;
}

Replace nixos-validation-host with your intended hostname.

3. Build the VM

Run nixos-rebuild build-vm as root on the host. This creates a result symlink in the current directory pointing to the Nix build output.

sudo nixos-rebuild build-vm

Expected result: a ./result/bin/run-nixos-vm executable script. If the command fails, the configuration has a build or evaluation error and should be fixed before proceeding.

4. Boot and validate inside the VM

Start the VM. If your user lacks /dev/kvm access, run with sudo.

./result/bin/run-nixos-vm

Inside the booted VM, verify the configuration you changed:

systemctl status sshd
ip addr
cat /etc/hostname

Check that sshd is active, the expected network interfaces are present, and the hostname matches configuration.nix. If a service is failed or networking is missing, edit the host configuration, rebuild the VM, and retest.

5. Apply to physical hardware

Only after the VM passes validation, run nixos-rebuild switch on the host. This changes system state: it activates the new configuration, updates systemd units, and adds a new bootloader generation.

sudo nixos-rebuild switch

Expected check: the command completes without error and reports the new generation number.

6. Confirm the result and rollback path

Because switch modifies the host, confirm the new generation and keep the rollback path available:

nixos-rebuild list-generations

If the new generation breaks boot or networking, reboot the physical machine and select the previous generation from the bootloader menu. NixOS keeps older generations as bootable entries specifically for this rollback.

Practical verification after switch

After applying the change on bare metal, run these checks:

• systemctl --failed — should list no failed units.
• ip addr and ping to a known address — confirms networking survived the rebuild.
• sudo journalctl -xb -p 3 — surfaces boot-time errors from the new generation.

If any check fails, reboot into the previous generation and revise the configuration before trying again.

Limitations

build-vm does not emulate physical hardware, so hardware-specific failures may still occur after nixos-rebuild switch. It also cannot test suspend/resume behavior, proprietary GPU drivers bound to physical cards, or hardware encryption features. Treat the VM as a gate for configuration logic, not a substitute for a hardware maintenance window.