Rolling back

Rollback returns NetBox to the moment the snapshot was taken. Anything written to NetBox after that moment is lost, Netos data and NetBox data alike. Netos database migrations are not guaranteed to be reversible, so a rollback restores the whole database from the snapshot rather than undoing migrations.

Every install and upgrade takes a snapshot first, in /var/backups/netos/<timestamp>/. It holds a database dump, a full copy of the NetBox venv, the static files, configuration.py, the Netos secrets directory and the systemd units it changes.

When to roll back

  • An install or upgrade failed. Its last lines print the exact command, for example:

    FAIL: ...
    Rollback: netos-install rollback --site /root/netos/site.yml --snapshot /var/backups/netos/20261018T201046Z --confirm ROLLBACK
    
  • The install was interrupted: SSH dropped, the process was killed, the host rebooted mid-install.

  • An upgrade succeeded but the new release misbehaves and you want the previous one back.

All three were tested on the offline test host (2026-10-18): a first install rolled back to plain NetBox; an upgrade rolled back to the previous release; and an install killed during the package step and another killed during migrations were each recovered by rollback alone. In every case the venv and configuration.py came back byte-identical to the snapshot.

How

cd /root/netos/netos-bundle-*/
sudo ./netos-install rollback --site /root/netos/site.yml --latest --confirm ROLLBACK

Use --snapshot /var/backups/netos/<timestamp> instead of --latest to pick a specific one. Without --confirm ROLLBACK it asks you to type ROLLBACK.

What it does:

  1. Checks it can restore the database before it changes anything. If it cannot (for example the database is on another server), it stops and prints the commands for your DBA.
  2. Stops NetBox.
  3. Restores the dump into a new database, netbox_netos_restore_<id>, and checks it: the number of tables and the row counts of devices, sites and users must equal the snapshot's.
  4. Stages every file it will restore next to its destination and checks each copy.
  5. Only then swaps the database and the files in. Your current database is kept, renamed netbox_netos_pre_rollback_<id>, and the files it replaced are kept in /var/backups/netos/pre-rollback-<id>/. If any part of the swap fails, it reverses what it had swapped.
  6. Starts NetBox and runs manage.py check. The last line is RESULT: PASS <release> (none when you rolled back to the snapshot taken before Netos was first installed).

It took 1 to 3 minutes on the test host. The end of the output names the database it kept:

Replaced files kept in /var/backups/netos/pre-rollback-20261019t001043z_f7322d10; remove when satisfied.
Pre-rollback database retained: netbox_netos_pre_rollback_20261019t001043z_f7322d10; drop when satisfied: sudo -u postgres dropdb netbox_netos_pre_rollback_20261019t001043z_f7322d10

Remove both once you are satisfied; until then they are your way back from the rollback itself. The kept files include a copy of the previous configuration.py, with your licence and keys, so the directory is root-only.

You may also see Failed to disable unit: Unit file netbox-rq-low.service does not exist. when rolling back a first install. It is harmless: the low-priority worker did not exist before Netos was installed.

If the rollback itself fails

If the database restore fails before the swap, nothing has been changed: the staging database is dropped, NetBox is restarted as it was, and the output says Rollback aborted before any change; services restarted. Send Netos the support bundle (./netos-install support-bundle --site /root/netos/site.yml).

After a rollback, ./netos-install status reports the release you rolled back to.