Skip to main content

Known limitations

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

If you meet something that is not on this page, we would like to hear about it at [email protected].

An update for another platform is accepted​

What it means. The update channel URL you were given is specific to your platform build. An update published for a different platform carries a valid signature, and the unit does not check which platform it was built for, so a unit pointed at the wrong channel installs it.

What you see. It depends on how different the platform is. A build for another CPU architecture does not boot at all: after three attempts the bootloader returns to the previous slot by itself. A build for another platform of the same architecture can boot, bring Synapse up and be confirmed good, leaving the unit on a kernel and drivers that were not meant for it, with no automatic return.

What to do. Before the first update, check UPDATE_BASE_URL in /etc/synapseos/update.conf against what Gen0Sec gave you for this platform. If a wrong build was installed, synapseos-ab-update rollback returns to the previous slot while it is still there, then fix the URL. See Updating.

A service introduced by an update starts disabled​

What it means. An update replaces the system and the kernel, and leaves /etc alone. For most services, whether they start at boot is recorded in /etc, so a service that an update brings for the first time can arrive installed but not enabled. Services the unit already had keep their state.

What you see. The release notes name a new service; after the update systemctl status <unit> reports disabled.

What to do. Check its state first, since some services are enabled by the system itself and need nothing. For one that reports disabled, once per unit:

systemctl enable --now <unit>

Synapse versions are fixed per image​

What it means. The system is read-only, so the Synapse releases on a unit are the ones its image was built with. synapseos-synapse use can only choose among them.

What to do. A newer release arrives with the next OS update. See Synapse versions.

Data at rest is not encrypted​

What it means. The system itself is integrity-checked, but the writable partition that holds configuration, keys and logs is not encrypted. Anyone with the disk can read it.

What to do. Treat the unit's storage as sensitive when a unit is transported, returned or disposed of. See Security model.

Log retention is bounded​

What it means. The journal is the unit's local log store, capped at 4 GB and two weeks as shipped. Older entries are gone from the unit.

What to do. Forward logs to a collector of yours; the forwarder buffers while the collector is unreachable. See Logs.

Updates are all-or-nothing per channel​

What it means. A channel names one update, and every unit following it takes that update when it next checks. There is no staged rollout within a channel beyond the canary and stable convention.

What to do. Point a few units at canary and the rest at stable, and ask Gen0Sec to move stable once the canary units have run the release. The channel is UPDATE_CHANNEL in /etc/synapseos/update.conf.

No HTTP proxy for the agent​

What it means. Synapse connects to api.gen0sec.com and download.gen0sec.com directly; it has no proxy setting. Only the updater honours one.

What you see. On a network that allows outbound traffic through a proxy only, the agent logs connection failures and runs without the platform's rules and verdicts.

What to do. Allow the two hosts directly for the unit, on 443. See Network requirements.

The clock is not synchronised as delivered​

What it means. systemd-timesyncd ships disabled, so the unit's clock runs free from the moment it is powered on. TLS verification and certificate expiry depend on the clock.

What you see. After a long power-off, connections to the platform or a collector fail certificate checks, or a certificate appears expired early.

What to do. Enable time synchronisation once, and allow 123/UDP to the servers you name. See Network requirements.

The variant check cannot be overridden, although its message says it can​

What it means. An update of another variant (hardened versus baseline) is refused with bundle is variant 'X' but this appliance runs 'Y' ... override deliberately with --allow-downgrade. The flag does not override this check; only the version check honours it.

What you see. The same refusal with the flag.

What to do. Check the channel: this almost always means the wrong one. A unit that is meant to change variant is re-imaged by Gen0Sec. See Troubleshooting.

No self-service evaluation image​

What it means. A unit arrives installed, or Gen0Sec deploys a VM for you. These pages describe no way to download an image and try the appliance on your own hardware.

What to do. Ask Gen0Sec for an evaluation unit or VM; the first credential comes with it. See Logging in.