Configuration reference

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

Everything you may change is in /etc. This is the list.

Files not on this page are the system's, and the system is read-only. The pages that explain each file are linked from its row; this page is the lookup.

Files and keys

/etc/synapseos/update.conf

Read by synapseos-ab-update, which sources it as shell. See Updating.

Key	Default	Effect
UPDATE_BASE_URL	unset	The HTTPS base the unit's channels are published under, specific to your platform. Unset: no channel, offline updates only.
UPDATE_CHANNEL	stable	Which channel the unit follows. canary by convention for a few units that take each release first.
export https_proxy	unset	An HTTP proxy for the update host; export is required. See Network requirements.

/etc/systemd/network/*.network

Read by systemd-networkd; the first file whose [Match] fits an interface applies, in name order. 90-fallback-dhcp.network ships and runs DHCP on en* and eth*; a file numbered below 90 wins. See Configuring the appliance.

Key	Section	Effect
MACAddress=	[Match]	Which interface, by MAC, so a rename does not matter
Address=	[Network]	Address with prefix length, repeatable
Gateway=	[Network]	Default route
DNS=	[Network]	Resolver, repeatable
IPv6AcceptRA=	[Network]	yes to take router advertisements, no to ignore them

/etc/nftables/synapseos-base.nft

Loaded by synapseos-firewall.service before the network comes up. Inbound is dropped except what the services chain accepts; loopback, established traffic and ICMP are accepted above it. See The base firewall.

Line	Ships as	Effect
tcp dport 22 accept comment "ssh"	present	SSH
tcp dport { 80, 443 } accept comment "synapse proxy"	absent	Add when the proxy runs

/etc/axosyslog/conf.d/*.conf

Drop-ins for the log forwarder. One destination block and one log line per collector. See Logs.

Element	Values	Effect
transport()	"tls", "tcp", "udp"	TLS verifies the collector against /etc/ssl/certs
port()	6514 for TLS by convention, 514 otherwise
disk-buffer(disk-buf-size(N) reliable(no) dir("/var/lib/axosyslog"))	268435456 as shipped	How much is held while the collector is unreachable

/etc/systemd/journald.conf.d/10-synapseos.conf

Ships with Storage=persistent, SystemMaxUse=4G, SystemKeepFree=2G, MaxRetentionSec=2week, RateLimitBurst=20000. Change retention here; forward logs rather than growing it.

/etc/synapse/

File	Effect
config.yaml	Synapse's configuration; keys on the Configuration page. platform.api_key is the one every unit needs.
version	The Synapse version that runs, one line. Written by synapseos-synapse use; absent means the newest. See Synapse versions.
config-proxy.yaml	The proxy's configuration, derived from config.yaml. Exists only where the proxy runs. See Running the proxy.
upstreams.yaml	The proxy's routes, hot-reloaded. Format on the Configuration page.
certs/	TLS certificates and private keys the proxy serves

/etc/systemd/system/synapse-proxy.service.d/*.conf

Drop-ins that point the proxy at its own configuration. 10-separate-config.conf as on Running the proxy.

/etc/keepalived/keepalived.conf

The pair configuration, written at delivery. See High availability.

Setting	Effect
interface	The leg the election runs on
virtual_router_id	The pair's id; also the last byte of the virtual MAC
priority	Higher wins while healthy
nopreempt	A recovered unit does not take the address back
use_vmac	The address lives on vrrp.<id> with a fixed MAC
unicast_peer { }	The other unit's address on the election leg
virtual_ipaddress { }	The floating address
track_interface { }	The leg whose failure withdraws this unit. Present only when the address lives on a different leg from the election; when they share a leg, that leg's failure ends the advertisements by itself

Identity and trust

File	Effect
/etc/hostname	The unit's name, set with hostnamectl set-hostname
/root/.ssh/authorized_keys	Who may log in
/etc/ssl/certs/	The trust store; your CA goes here, then openssl rehash
/etc/systemd/timesyncd.conf	NTP= servers, once systemd-timesyncd is enabled

Reference configurations

A single unit, as delivered

Nothing beyond the first credential and the API key.

/etc/synapse/config.yaml

platform:
  api_key: "<your API key>"

/etc/synapseos/update.conf

UPDATE_BASE_URL=<provided by Gen0Sec>
UPDATE_CHANNEL=stable

Addressing by DHCP on every en* or eth* interface; inbound SSH only; logs kept locally for two weeks.

A single unit with static addressing and log forwarding

The delivered files above, plus:

/etc/systemd/network/30-external.network

[Match]
MACAddress=52:54:00:12:34:56

[Network]
Address=203.0.113.10/24
Gateway=203.0.113.1
DNS=203.0.113.53

/etc/axosyslog/conf.d/10-remote.conf

destination d_remote {
    syslog("logs.example.com" transport("tls") port(6514)
        tls(ca-dir("/etc/ssl/certs") peer-verify(required-trusted))
        disk-buffer(disk-buf-size(268435456) reliable(no) dir("/var/lib/axosyslog")));
};
log { source(s_journal); destination(d_remote); };

Outbound: the Network requirements table plus the collector.

A pair

Each unit has the single-unit files, with its own addresses on both legs, and the pair configuration written at delivery with the same virtual_router_id, virtual_ipaddress and nopreempt on both, a different priority, and each other's internal address as the unicast_peer. Inbound VRRP on the internal leg. Everything else identical on both units. See High availability.