Switching and rollback

Selecting a system generation

Run these commands from your configuration directory, such as ~/copland-config. They apply the configuration of the machine you are currently using, selected by its host name.

Build

build builds the system and prints its Nix store path. It does not activate the configuration or change the boot selection.

just build

To build another machine from the same configuration, pass its host name, for example just build vps. The other actions also build the selected configuration first, so a separate build is optional.

Test

test activates the new configuration now without changing the generation selected for the next boot. Use it to try a change before making it the boot default.

just test

This is a live activation, not a dry run. Services and system configuration change immediately, while the next normal boot still uses the previously selected generation.

Boot

boot selects the new generation for the next boot without activating it now. The currently running configuration stays in place, and the command does not reboot the machine.

just boot

Switch

switch activates the new configuration now and selects it for the next boot. This is the usual command for applying a system update.

just switch

Home activation is included for users enabled through homeEnvironment.users. Some changes, such as a new kernel, cannot be applied to the running system and need a reboot instead.

Changes that need a reboot

Before test or switch activates anything, Copland checks whether the new configuration changes components that cannot safely be replaced while the system is running:

the kernel and its modules
the NVIDIA driver and its settings
static network configuration
whether udev is enabled
the dbus, elogind and greetd services

If one of them changes, the command stops with a message that live activation is blocked. Nothing has been changed at that point, and the running system and boot selection stay as they were. Use just boot instead and reboot the machine to start the new generation.

Setting COPLAND_NO_CHECK=1 skips this check. The live switch can then leave the running system in an inconsistent state, so use it only if you understand the affected component.

Remote machines

The just commands call Copland's deploy.sh for the local machine. To apply a configuration to another machine over SSH, run deploy.sh from a Copland checkout and point it at your configuration directory:

./deploy.sh --configuration ~/copland-config switch vps root@192.0.2.10

vps names the host below hosts/ in your configuration, and root@192.0.2.10 is its SSH destination. test and boot work the same way. The target must already run Copland; a new machine is installed first as described in Installation.

Rollback

Automatic rollback

If activation or service startup fails during a switch, Copland runs the previous generation's activation and restores its service setup. If stopping an old service fails, it does not start replacements. deploy.sh also restores the previous system profile and boot selection when an operation that changed them fails.

This recovery belongs to the switch process. It does not monitor later application failures or restore application data from ZFS snapshots.

Available generations

The system profile records the generations available for selection. List them with:

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

The current marker refers to the profile's selected generation. After test or boot, that can differ from the running system, whose store path is available through:

readlink -f /run/current-system

Trying an older generation

Use an older generation's own activation command to run it without rebuilding your configuration. Replace 42 with a generation number from the list:

doas /nix/var/nix/profiles/system-42-link/bin/switch-to-configuration test

This activates generation 42 without changing the boot selection. Your repository files remain as they are. The same check applies here, so an older generation with a different kernel has to be selected for boot as described below.

Keeping the older generation

After testing the older generation, select it in the system profile:

doas nix-env --profile /nix/var/nix/profiles/system --switch-generation 42

Once that succeeds, update the boot selection using the selected generation:

doas /nix/var/nix/profiles/system/bin/switch-to-configuration boot

These are separate operations. Selecting the Nix profile generation changes the profile link, and the second command updates the bootloader. A later just switch builds from your configuration again, so keep it aligned with the version you want to run.