Operations

This page covers the operator procedures for protecting and recovering appliance data: taking and restoring database backups, and rolling back to the previous system generation if an update misbehaves. Applying a system update has its own page — see System Updates. Each section is anchored to one TUI screen, so you can match the on-screen wizard to the steps described here.

Updating the system

Applying a signed update bundle has its own page — see System Updates for the full walkthrough: which delivery path to use for virtualized versus physical appliances, the built-in backup-and-rollback safety net, and troubleshooting.

Backup and restore

The Backup / Restore screen manages database backups. The appliance takes automatic backups on a schedule; you can also create an ad-hoc one before risky operations, and you can restore from any backup the screen lists.

What you see

The top-level menu has two entries:

• Create Backup — runs a backup immediately. The screen shows a green status line with the output of the backup command on success, or a red error on failure.
• List / Restore Backups — opens the picker described below.

Picking List / Restore Backups shows every backup file the appliance has on disk, one per line, with the file name, size (KB, MB, or GB), and last-modified timestamp. The most recently modified backup is the one you usually want when recovering from a problem; the older entries are the rolling automatic backups.

Creating an ad-hoc backup

Before doing anything risky — an update, a large configuration change, a customer-supplied import — pick Create Backup and wait for the green confirmation. The result is a fresh backup file alongside the automatic ones, and it gives you a known-good rollback point for the database that does not depend on the next scheduled backup running.

Restoring a backup

Restoring overwrites the live database with the contents of the chosen backup file. The screen takes that seriously:

1. From List / Restore Backups, move the cursor to the backup you want to restore and press Enter.
2. A confirmation screen appears with a yellow warning — WARNING: This will replace the current database! — and the name of the backup file. Press y to confirm or n/Esc to back out.
3. On confirmation, the restore runs and the screen shows Database restored successfully (green) or the underlying error (red).

While the restore is running the database is being replaced wholesale: any rows written since the chosen backup are lost, and any user logged into the web interface will see their session blow up the moment the database goes away. Restoring is not a partial or merge operation — it is a full replacement, which is exactly why the warning is loud.

Backup vs rollback

Backups cover the database. The system itself — the NixOS generation, configuration, installed software — is covered by Rollback. The two are complementary: a backup will not bring back an old kernel, and a rollback will not bring back deleted records. When in doubt about which one you need, see the next section.

Rollback

The Rollback screen switches the appliance to a previous system generation. Use it when an update misbehaves and you need the old version back fast.

What rollback does

The screen lists every NixOS generation the appliance retains, newest first, with its number, build date, and a green (current) marker on the one that is running. Move the cursor with the arrow keys (or j/k), press r to refresh the list, and press Enter on a non-current generation to start the switch.

A confirmation prompt appears asking Switch to generation N (date)?. Press y to commit or n/Esc to back out. On confirmation the appliance updates its boot configuration and reports Switched to selected generation. A reboot is required for the change to take effect — the running services are still on the old (now-newer) generation until the box restarts. Reboot from the main menu's Reboot System entry once the rollback is confirmed.

What rollback preserves — and what it doesn't

Rollback is a system-level operation, not a data-level one. Concretely:

• Replaced: the root partition. The Nix store, kernel, system configuration, and installed software all revert to what the previous generation looked like.
• Preserved: /var and everything below it. That includes the Pulse PostgreSQL database, your database backups, log files, the SFTP exchange directory, and any configuration written through the TUI (TLS certs, SFTP keys, network settings). None of that is touched by switching generations.

In practice, rolling back undoes the software part of the last update but keeps every byte of customer data the appliance has accumulated since then.

When to roll back vs. restore a backup

The two recovery tools cover different failure modes; picking the right one matters.

• Roll back when the new software is the problem: a service that won't start, a regression in behaviour, a kernel issue introduced by the update, a TUI screen that crashes. The data is fine; the code is not. Rollback restores the previous generation without losing any rows in the database.
• Restore a backup when the data is the problem: corruption, an accidental mass delete, a bad import that polluted the schema. The code is fine; the data is not. Backup restore returns the database to a known-good snapshot.

If both are needed — an update went wrong and corrupted state on the way out — roll back first to get the appliance onto a working software version, then restore the most recent pre-update backup.

Generations that no longer appear

NixOS only retains a bounded number of generations on disk. Older generations are garbage-collected on the appliance's normal schedule, so the list does not grow forever. If the generation you want to roll back to is no longer listed, you are past the point where rollback can help and the appliance needs to be re-imaged or repaired via support — the rollback screen is a short-term safety net, not a long-term recovery archive.

After a successful rollback

Once the appliance has rebooted onto the previous generation and you have confirmed the system is healthy again, take a fresh database backup from the Backup and restore screen. The post-rollback state is now your known-good baseline; capturing it explicitly means the next risky operation has a clean snapshot to fall back on instead of the older automatic backups that predate whatever you just recovered from.

If the update that triggered the rollback was delivered over SFTP, the bundle has already been cleaned up by the post-update flow on the original (failed) attempt. If it was delivered over USB, the stick is no longer mounted — pull it out, work out with support what was wrong with that bundle, and only retry once a corrected build is available. If it was delivered via CD/DVD-ROM, the drive is automatically unmounted and you can safely disconnect the ISO from the VM. There is no value in re-applying the same bundle that failed last time.