NixOS Generations: Why Your Rollback Plan Lives in the Bootloader

The config change that breaks SSH

You add a firewall rule or tweak a service in configuration.nix, run sudo nixos-rebuild switch, and immediately lose remote access. On a conventional Linux distribution you are now editing rescue media or praying the provider console works. On NixOS, the previous working state is still sitting in your bootloader as a selectable generation. The catch is that this safety net only covers state NixOS built, and it disappears if you garbage-collect too aggressively.

What a NixOS generation actually is

NixOS does not configure a live system by mutating files in place. Instead, the Nix package manager evaluates your configuration.nix into a set of immutable paths under /nix/store. Each path is content-addressed, so the same inputs always produce the same output. When you activate a configuration, NixOS creates a new generation: a profile entry under /nix/var/nix/profiles/system that points to that specific set of store paths. The symlink /run/current-system points to the active generation.

Because old store paths are never overwritten, a previous generation remains bit-identical to the moment it was activated. Rolling back does not reinstall packages or replay edits; it simply re-points the system profile to an older, immutable directory tree.

A worked rollback: from bad switch to clean boot

Suppose you enable nginx and accidentally close the SSH port with a firewall change:

{ config, pkgs, ... }:
{
  services.nginx.enable = true;
  networking.firewall.enable = true;
  networking.firewall.allowedTCPPorts = [ 80 ];
}

Run the rebuild on the NixOS host as root:

sudo nixos-rebuild switch

After the switch completes, verify the new generation is active by checking the symlink target (run as any user):

ls -l /run/current-system

You should see a path under /nix/var/nix/profiles/ that includes a generation number. If the new generation locks you out, reboot the machine and use the bootloader menu—typically GRUB—to select the previous generation. NixOS lists each generation as a separate boot entry, so you can pick the one that worked before your change.

Once the older generation boots, confirm the rollback (run as any user):

nixos-version

The output should report the generation number you selected, not the newer one. If you want that older generation to become the default profile again without relying on the bootloader next time, run as root:

sudo nixos-rebuild switch --rollback

This re-activates the previous generation as the current system profile.

The limits: what generations do not save

Rollback is atomic for NixOS-managed state, but it is not a time machine for the whole filesystem. If you edited a file by hand—say you adjusted /etc/ssh/sshd_config directly instead of declaring it in Nix—that change lives outside the Nix store. A rollback will not revert it, and the next nixos-rebuild switch may overwrite it anyway. Treat /etc as generated output, not a place for manual edits.

Generations also accumulate. Every switch leaves another profile entry and another set of store paths on disk. Without cleanup, /nix/store grows until the partition fills. After you have confirmed a rollback works and you no longer need the broken generation, clean up as root:

sudo nix-collect-garbage -d

The risk here is timing: this command removes generations older than the current one. If you delete the generation you might still want to boot into, your rollback target is gone. Keep at least one known-good generation until you are confident the current one is stable.

A practical habit

Before any risky nixos-rebuild switch, note the current generation number from nixos-version. After the switch, check /run/current-system to confirm activation. If the machine misbehaves, reboot into the previous generation from the bootloader, verify with nixos-version, and only then run garbage collection. That sequence turns NixOS generations from an abstract feature into a repeatable recovery procedure.