Skip to content

Back up & restore configuration

An AryaOS box holds a lot of hard-won state. Your site config, the sensor role, cotbridge lanes, TAK client certificates, saved Wi-Fi networks, and the Node-RED flows. The aryaos-config-backup helper packs all of it into one restorable tarball. So you can snapshot a working unit before a change. Alternatively, migrate a whole configuration onto a replacement box in minutes.

Make a backup

  1. Open Cockpit > AryaOS Site > Backup & restore.
  2. Click Create backup. AryaOS packs the config set into a tarball on The box and lists it under existing backups.
  3. Download it to your machine to keep a copy off the unit.
sudo aryaos-config-backup backup                 # full backup (includes secrets)
sudo aryaos-config-backup backup --no-secrets    # shareable, key material excluded
sudo aryaos-config-backup list                   # list existing backups (JSON)

The command prints a one-line summary and the archive path on the last line of stdout:

Backup written (18422 bytes).
/var/lib/aryaos/backups/aryaos-config_aryaos-1a2b_20260718T140355Z.tar.gz

What's in a backup

The backup (/usr/local/sbin/aryaos-config-backup) captures the AryaOS configuration set. Missing paths are skipped, not errors.

Area Contents
Site & CoT config /etc/aryaos (site config + TLS material), /etc/cotbridge.ini, /etc/cotbridge (lanes + TLS).
Onboarding / hotspot /etc/comitup.conf, /etc/comitup.json.
Gateway and decoder defaults /etc/default/{acarsdec,adsbcot,aiscot,dronecot,lincot,gpscot,gdlcot,sikw00fcot,cotbridge,gpsd} and the /etc/{adsbcot,aiscot,dronecot,lincot} config trees.
Secrets (full backup only) /etc/NetworkManager/system-connections (Wi-Fi PSKs), /etc/default/gutcheck (web token and runtime settings), Node-RED settings.js and flows_cred.json, and the TLS key material inside the config trees above.

Every archive carries a MANIFEST.txt with its time, hostname, AryaOS version, secret status, and captured paths. A restore uses this manifest to validate a genuine AryaOS backup.

A full backup contains private keys and Wi-Fi passwords

The default backup includes TAK client certificates and TLS private keys, NetworkManager Wi-Fi PSKs, the Gutcheck web token, and Node-RED credentials. Anyone holding that archive can impersonate the unit and its TAK connection. AryaOS writes every archive 0600 root and keeps the directory 0700, but once you copy it off the box it is your responsibility - store full backups securely.

Use --no-secrets for a shareable copy. It omits TLS keys and the network, GutCheck, and Node-RED secret files. The archive keeps the configuration structure without credentials.

Where backups land

Backups are written to /var/lib/aryaos/backups/ as aryaos-config_<hostname>_<timestamp>.tar.gz.

  • Each archive is mode 0600 (root-only) and the directory is 0700.
  • Only the five newest backups are kept - older ones are pruned automatically each time you create a new one.
  • The most recent backup's path and size are recorded in /var/lib/aryaos/config-backup.json, which is how the Cockpit card lists it.

Restore a backup

Open Cockpit > AryaOS Site > Backup & restore, pick a backup, and click Restore. The card confirms with you first, then unpacks the archive and restarts the affected services.

sudo aryaos-config-backup restore /var/lib/aryaos/backups/aryaos-config_aryaos-1a2b_20260718T140355Z.tar.gz

Restore prompts for confirmation before it overwrites current config (the Cockpit card, which already confirmed with you, passes --service to skip The prompt).

The restore validates the archive, unpacks it in place preserving permissions. Ownership, runs systemctl daemon-reload, and does a try-restart of the CoT fleet (cotbridge, gpscot, aiscot, lincot, adsbcot, dronecot) plus lighttpd.

Restore is additive

Restore overlays the backed-up files onto the device - it brings back everything in the archive but does not remove files created since the backup (for example, a TAK certificate uploaded afterwards stays in place). If you need an exact return to the backed-up state, do a factory reset first, then restore.

Reboot after a restore

The restore finishes with:

Restore complete. A reboot is recommended to fully apply network and identity changes.

Reboot the unit so network connections and device identity are fully re-applied.

Migrating to a replacement box

Backups are the fast path when hardware fails or you are swapping a fielded unit:

  1. On the old box (or from your last saved backup), make a full backup and download it - you want the TAK certs and Wi-Fi PSKs, so do not use --no-secrets here.
  2. Flash AryaOS onto the replacement box and let it complete first boot.
  3. Copy the archive onto the new box (over SSH or the VPN) and run aryaos-config-backup restore FILE.
  4. Reboot. The unit comes up with your site config, sensor role, TAK connection, lanes, and saved networks in place.

The replacement keeps its own identity

A restore puts your configuration on the new device. The device keeps its own DEVICE_SUFFIX, hostname, and web TLS certificate. You migrate configuration, not identity.

  • Factory reset - clear config back to defaults (back up first). Factory reset
  • Zeroize - securely sanitize a box for decommission. Zeroize
  • CLI helpers - the full aryaos-config-backup reference. CLI helpers
  • AryaOS Site - the admin page hosting the backup card. AryaOS Site