Skip to main content

Synapse versions on the appliance

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

Several releases on the unit; one of them runs.

How it works​

The system is read-only, so the set of Synapse versions on a unit is fixed by the image it runs. What is not fixed is which one is used: that choice lives in /etc, which is writable.

/usr/lib/synapse/0.8.5/synapse     one directory per version, read-only
/usr/lib/synapse/0.8.6/synapse
/usr/bin/synapse                   reads the selection and runs that version
/etc/synapse/version               the selection: one line, writable

With no selection made, the newest version on the unit runs. A selection is called a pin, and it stays in place across OS updates.

Commands​

synapseos-synapse list        # versions on the unit, and which one runs
synapseos-synapse use 0.8.6   # select a version and restart the active services
synapseos-synapse status      # the selection, against what each process is running
synapseos-synapse reset       # drop the pin; the newest version is selected

use refuses a version that is not on the unit, and runs the chosen binary once before selecting it, so a release that cannot start on this kernel fails there rather than after the running service has been stopped. If the restart fails anyway, the selection is put back automatically.

reset only removes the pin. Unlike use, it restarts nothing: run systemctl restart synapse-agent (and synapse-proxy, if it runs) afterwards, or use the newest version instead, which restarts for you.

status matters after any change: a running process keeps the binary it started with, so a pin changed without a restart is otherwise invisible.

What switching does not do​

  • It does not change your configuration. /etc/synapse/config.yaml is seeded once and left alone. Each version's reference configuration stays readable at /usr/share/synapse/<version>/config.yaml, so a release that changes a setting can be compared against the file you have. See Configuring the appliance.
  • It does not touch the OS. Going back to a previous Synapse version is a restart and leaves the other OS slot free for rolling back the OS itself.

Getting a version that is not on the unit​

A release that is not in the image cannot be selected, only shipped. It arrives with the next OS update, beside the versions already there, and the pin you have is kept. See Updating.