NixOS declarative configuration as the single source of truth

The problem and the takeaway

A NixOS system can drift out of sync when an administrator installs a package, edits a service file, or changes a user account directly on the running host. Those imperative changes are not tracked by /etc/nixos/configuration.nix, so the next nixos-rebuild switch silently discards them. The practical rule is: treat the NixOS expression tree as the single source of truth, validate changes with nixos-rebuild test before applying them, and keep secrets out of the Nix store.

Requirements

• Every package, service, user, filesystem, and boot loader setting is declared in /etc/nixos/configuration.nix or in imported NixOS modules.
• hardware-configuration.nix, generated during installation or by nixos-generate-config, describes hardware-specific facts such as file systems and devices.
• Rebuilds are performed with nixos-rebuild, not with imperative package managers or manual edits to /etc.

Smallest suitable design

For one host, keep two files under /etc/nixos: configuration.nix and hardware-configuration.nix. A minimal configuration.nix might look like this:

{ config, pkgs, ... }:

{
  networking.hostName = "example-host";
  boot.loader.systemd-boot.enable = true;

  environment.systemPackages = with pkgs; [
    vim
    git
    curl
  ];

  services.openssh.enable = true;
  services.openssh.permitRootLogin = "no";
}

Run rebuild commands on the target NixOS host as root or with sudo. Use nixos-rebuild test to activate the configuration temporarily; it reverts on reboot. Use nixos-rebuild switch to activate immediately and make it the default boot entry. Use nixos-rebuild boot only when you want the change to take effect on the next reboot.

Trust and data boundaries

The Nix store at /nix/store is world-readable and build outputs are immutable after they are created. That means any local user can read expressions and store paths. Never place passwords, private keys, or tokens in configuration.nix or in any module evaluated into the store.

For secrets, use an external encrypted secret manager integrated with NixOS, such as agenix, sops-nix, or systemd credential encryption. The secret is decrypted at activation time and delivered to the service without being stored in plain text in the Nix store.

Mutable state outside the Nix expression tree—for example, databases in /var/lib, logs in /var/log, or files in user home directories—is not managed by NixOS and is not reverted by generation rollback.

Operational checks

Run these checks on the target NixOS host after a rebuild:

1. List system generations:

nix-env --list-generations -p /nix/var/nix/profiles/system

The newly activated generation should appear as the current entry.

1. Confirm no failed units:

systemctl --failed

1. Verify the active system path:

ls -l /run/current-system
nixos-version

The /run/current-system symlink should point to the generation you just activated, and nixos-version should report the corresponding release.

Failure modes and recovery

A syntax error or a bad service option can make the system fail to boot or leave networking unavailable. If the new generation is unbootable, reboot and select the previous generation from the boot loader menu. Once booted, run:

nixos-rebuild switch --rollback

This restores the previous system profile as the active and default generation. Rollback changes system state, so it is appropriate only after a failed or unwanted rebuild.

Rollback does not undo changes to mutable data. If the broken configuration wrote to a database or modified files in /home, those changes remain after rollback.

Conditions that would change the design

Single-host configuration does not scale. When you manage more than a handful of hosts, move shared settings into reusable NixOS modules and consider flakes to pin nixpkgs revisions. Channel-based upgrades can silently pull a new nixpkgs revision, which breaks reproducibility if exact binary substitution matters.

Add a CI evaluator that checks the configuration before any host is rebuilt. Redesign is also warranted when secrets outgrow ad hoc files and require a managed secret service, or when multiple administrators need audited, reviewable changes through version control.

Limitation and verification

This note describes established NixOS behavior; it does not guarantee that a specific rebuild will succeed on your hardware. Verify on a staging host first: apply the configuration with nixos-rebuild test, confirm services are reachable, then run nixos-rebuild switch and confirm the new generation appears in the generation list.