Backup, restore and decommission

Applies to SynapseOS builds from 2026-10-09 (20261009-141152 and later). See What changed.

Back up /etc before every update. Wipe the writable partition before a unit leaves.

What to back up

Everything you have changed on a unit is on the writable partition, and all of it is small:

Path	What it holds
/etc/synapse/	Synapse's configuration, the version pin, the upstreams file, and certs/ with your private keys
/etc/synapseos/update.conf	The update channel
/etc/systemd/network/	Static addressing
/etc/nftables/synapseos-base.nft	The base firewall, with the ports you opened
/etc/axosyslog/conf.d/	Log forwarding
/etc/systemd/system/	Unit drop-ins, such as the proxy's
/etc/keepalived/	The pair configuration, on a pair
/etc/hostname, /root/.ssh/authorized_keys, /etc/ssl/certs/ (your CA, if any)	Identity and trust

Not worth backing up: /usr (it is the signed system, replaced by updates), the journal (forward it instead, see Logs), and /var/lib/synapse (databases and managed rules the agent downloads again).

Taking a backup

From a machine that can reach the unit over SSH:

ssh root@<address> 'tar -C / --exclude=etc/machine-id --exclude=etc/os-release -czf - etc root/.ssh' \
  > synapseos-$(date -u +%F).tar.gz

That is the whole of a unit's configuration. Keep it with the care you keep the private keys in it, since etc/synapse/certs/ and the SSH host keys are in there. Take one before every update and after every change you mean to keep.

The two exclusions are the unit's identity, which must not travel to another unit: machine-id (two units sharing one collide on DHCP leases and in logs) and os-release (it names the build the unit was delivered with). The SSH host keys are carried on purpose, so clients that knew the old unit accept the replacement; leave them out if you would rather the replacement have its own.

Restoring onto a replacement unit

A replacement arrives like the first unit did: installed, with its own first credential. Restore in this order, over SSH, on a unit of the same platform.

1. Check it runs the same or a newer SynapseOS build as the backup came from (/etc/os-release, VERSION), and update it first if not; see Updating.

2. Copy the archive to the unit and unpack it over /:

   scp synapseos-2026-10-10.tar.gz root@<address>:/var/tmp/
   ssh root@<address> 'tar -C / -xzf /var/tmp/synapseos-2026-10-10.tar.gz && rm /var/tmp/synapseos-*.tar.gz'

3. Apply what needs a reload, then reboot so everything else is picked up together:

   systemctl daemon-reload
   networkctl reload
   systemctl restart synapseos-firewall
   systemctl reboot

4. After the reboot: synapseos-synapse status (the pin from the backup is applied, and a version the new image no longer ships falls back to the newest, so check), systemctl status synapse-agent, and on a pair, ip -br addr on both units.

The unit's machine identity (/etc/machine-id) is not in the backup, so the replacement keeps its own; it registers with the platform under the hostname from the backup.

Decommissioning a unit

The writable partition is not encrypted, and it holds the private keys and credentials listed above. Before a unit is returned, resold or scrapped, wipe it from the console.

1. Take a final backup if anything on it matters.

2. From the console, identify the writable partition: it is the last one on the disk, mounted at /.

   findmnt -no SOURCE /          # for example /dev/sda6 or /dev/nvme0n1p6

3. Reboot into the other slot's system is not enough: both slots share the same writable partition. Discard it instead. On flash and NVMe, blkdiscard tells the device to erase it; on disks that do not support discard, overwrite it:

   blkdiscard -f /dev/sda6                      # or
   shred -n 1 -v /dev/sda6

   Both destroy the running system's root filesystem; the command runs from memory and the unit will not boot again until re-imaged.

4. Power off. The system partitions that remain hold nothing of yours: they are the signed image every unit of that platform ships with.

For a unit under a support contract, a wipe followed by a return is what Gen0Sec expects; a unit sent back without one still holds your keys.