Updating
Applies to SynapseOS builds from 2026-10-09 (20261009-141152 and later). See What changed.
One update, the whole system, and the old one stays on disk.
Where updates come from
A unit follows a channel, named in /etc/synapseos/update.conf:
UPDATE_BASE_URL=<provided by Gen0Sec, specific to your platform>
UPDATE_CHANNEL=stable
stable is the default. A unit delivered with network updates has UPDATE_BASE_URL set
already; with it unset the unit has no channel and takes updates from external media only.
Each platform build has its own channels, so the URL you were given applies to units of
that platform and no other.
Checking
synapseos-ab-update check
It prints the version you are running and the version the channel names, then either
=> up to date or => an update is available. It changes nothing. In a script, note that
it exits non-zero when the unit is up to date.
synapseos-ab-update status
prints, on a unit that has taken one update and confirmed it:
disk : /dev/sda
active slot : B (verified)
slot A : 20260917155226-6.18.48 serial 20260917155226 kernel 6.18.48-synapseos
slot B : 20260918191637-6.18.48 serial 20260918191637 kernel 6.18.48-synapseos <- running
channel : stable @ <your UPDATE_BASE_URL>
boot entries : synapseos_a.efi synapseos_b.efi
loader defaul: synapseos_b.efi
| Line | Meaning |
|---|---|
active slot | Which of the two slots is running. (verified) means its system passed the integrity check for this boot; it does not say whether the slot has been confirmed good |
slot A, slot B | The version, serial and kernel each slot holds; <- running marks the active one. A slot never written says empty (never installed) |
channel | The channel followed and the base it is read from; unset means offline updates only |
boot entries | The files the bootloader can boot. A slot still on trial carries a counter in its name, synapseos_b+3.efi; a confirmed one does not. That counter, not (verified), is what says a slot was confirmed |
loader defaul | Which entry boots next |
Installing over the network
synapseos-ab-update update
systemctl reboot
synapseos-ab-update status
update downloads, verifies and writes the update into the inactive slot, then points the
bootloader at it. The reboot is yours to schedule: nothing changes until then. Take a
backup of /etc before it, as a rule; the update does not touch /etc,
but a configuration you cannot restore is the one thing a rollback does not give back.
After the reboot, confirm the unit is doing its job, not only that it booted:
synapseos-ab-update status # the new version is the running slot, the previous one beside it
synapseos-synapse status # every service runs the Synapse version you expect
systemctl is-active synapse-agent # active
journalctl -u synapse-agent -b -n 20 # "Started Synapse", and nothing after it that says failed
On a pair, update the standby first; see High availability.
The update refuses, before writing anything:
- an update that is not newer than the running system, the same version included;
- an update of a different variant, which would silently change the unit's security posture;
- anything whose signature does not verify.
--allow-downgrade overrides the first check only: reinstalling an older or equal version
is a decision, and the flag records it. The variant check cannot be overridden, although
the refusal message suggests the same flag; a unit changes variant by being re-imaged. The
signature check is never overridden.
Installing from external media
A unit with no network path to updates installs from a copy on external media. An offline
update is delivered as one archive, <name>.bundle.tar.zst, which holds a directory of
files. Unpack it on the media, or on the machine preparing the media, never on the
unit: the appliance's root filesystem is small, and the installer streams the update from
where it is straight into the inactive slot.
# on the machine preparing the media
tar --zstd -xf <name>.bundle.tar.zst -C /path/to/media
# on the unit
mkdir -p /mnt/media
mount -o ro /dev/disk/by-label/SYNAPSEOS-UPD /mnt/media
synapseos-ab-update install /mnt/media/<unpacked directory>
umount /mnt/media
systemctl reboot
install takes the unpacked directory, the one holding manifest.json. Read-only media is
fine; nothing is written to it. The archive is stored sparse, so the system image inside it
takes the space of its contents on the media rather than its full size; any tar extracts
it that way.
What happens on the first boot after an update
The new slot boots as a counted entry. If the kernel does not come up, or the unit boots but Synapse (and the jailer, on hardened units) does not reach a running state, the bootloader stops trying after three attempts and returns to the previous slot by itself. Only once the appliance's services are up is the new slot confirmed good: the counter disappears from its boot entry, and from then on it boots like any other slot. A boot that fails for any other reason later, once a slot is confirmed, is not caught by this: the safety net exists for the trial boots after an update.
Going back
If the new version runs but behaves worse than the old one:
synapseos-ab-update rollback
systemctl reboot
The previous slot is still on disk, exactly as it was. Rolling back the OS does not change
anything in /etc.
What an update is
A SynapseOS update is not a set of packages. It is a complete new system (/usr, with
every binary, library and kernel module) together with the kernel that matches it, signed
as one. The unit holds two copies of the system, called slots A and B. An update is written
into the slot that is not running, verified in place, and only then made the one to boot
next. The running slot is never touched, which is what makes going back possible.
Two signatures are checked before anything is written, and a third on every boot:
| Signature | Covers | Checked by |
|---|---|---|
| The update's manifest | Its version and the digest of every file in it | The updater, before writing |
| The channel pointer | Which update the channel currently names | The updater, on every check |
| The kernel image | Kernel, initrd and command line, which carries the hash of the new system | The firmware, at every boot |
Hosting adds nothing to this: an update served from a mirror you do not trust can be withheld, but not forged.
Synapse versions and OS updates
An update brings new Synapse versions with it, but does not change which one runs. A unit
with a version pinned keeps it, as long as the new image still carries that version; one
with no pin runs the newest. If a pinned version is no longer shipped, the newest runs
instead, and synapseos-synapse status is where that shows. After the update:
synapseos-synapse list
synapseos-synapse use <version>
Switching Synapse versions is a service restart, not an OS update, and it does not use the other slot, which stays free for rolling back the OS itself. See Synapse versions on the appliance.