Configuring the appliance

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

Everything you change lives in /etc. Everything else is sealed.

What is writable

Path	Status
/etc, /var, /root	Writable. Configuration, state, journals and your SSH keys live here, and an update leaves them alone
/usr	Read-only and verified on every boot. An edit there is refused, and one forced through by other means makes the next boot fail verification

There is no package manager and nothing to install. If a tool you need is not on the unit, it is not available until an update brings it. Every file this page touches is listed with its keys on the Configuration reference; what the unit needs to reach is on Network requirements.

Network

The default

With no addressing configured, every interface named en* or eth* runs DHCP for IPv4 and IPv6 and takes its DNS servers from the lease. Interfaces are managed by systemd-networkd; networkctl status shows what each one got.

A static address

systemd-networkd applies the first .network file whose [Match] fits an interface, in name order. The DHCP fallback is 90-fallback-dhcp.network, so a file that sorts before it wins. Match on the MAC address rather than the name, so the file survives a rename:

/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
IPv6AcceptRA=yes

networkctl reload
networkctl status

Change addressing from the console, or with a second way in, and keep the old address until the new one answers.

DNS

Name resolution goes through systemd-resolved, with the servers that DHCP or your .network file supplied. resolvectl status shows them. Link-local discovery (LLMNR and mDNS) is turned off; the appliance resolves through configured servers only.

The base firewall

Inbound traffic is dropped unless a rule accepts it. The rules are in /etc/nftables/synapseos-base.nft, loaded by synapseos-firewall.service before the network comes up, and the only service open by default is SSH:

chain services {
    tcp dport 22 accept comment "ssh"
}

To open another port, add a line to that chain, check the file, and reload it:

nft -c -f /etc/nftables/synapseos-base.nft      # syntax check, changes nothing
systemctl restart synapseos-firewall
nft list chain inet synapseos_base services     # the new line is in the live ruleset

Established connections, loopback and ICMP are always accepted; forwarding is dropped; outbound is open.

Two firewalls

This is the appliance's own perimeter. Synapse's packet filter, the one that enforces access rules and bans in the kernel, is separate and is configured through Synapse. See Firewall Rules.

Synapse

Synapse reads /etc/synapse/config.yaml. The one value every unit needs before it does anything useful is the key that connects it to the platform:

/etc/synapse/config.yaml

platform:
  api_key: "<your API key>"

systemctl restart synapse-agent
systemctl is-active synapse-agent          # active
journalctl -u synapse-agent -b -n 20       # "Started Synapse", then nothing that says failed

The full key reference is on the Configuration page. Two things are specific to the appliance:

• The file is seeded once, from the reference configuration of the newest Synapse version on the unit, and then left alone. Each version's reference copy stays readable at /usr/share/synapse/<version>/config.yaml for comparison.
• /etc/synapse/version records which Synapse version runs. Do not edit it by hand; use synapseos-synapse, which checks the version before switching to it. See Synapse versions on the appliance.

The proxy mode is on the unit as well, disabled, and needs a configuration of its own before it is started. See Running the proxy.

Logs

Retention

The journal is the local log store for every service. As shipped it is persistent, capped at 4 GB and two weeks, and keeps 2 GB of the root filesystem free. The rate limit is raised so a burst of detections is kept rather than dropped. The forwarder also writes the classic files /var/log/messages, auth.log, kern.log and daemon.log from the same journal, and the audit log is separate; see below.

journalctl -u synapse-agent -f
journalctl --disk-usage

Forwarding

An axosyslog forwarder reads the journal and ships it. Its destination is a drop-in under /etc/axosyslog/conf.d/; a unit delivered with forwarding configured has one there already. To add or change a collector, write the file and reload:

/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); };

systemctl reload axosyslog

TLS verifies the collector against the system trust store. tcp and udp transports work too, on port 514 by convention, but neither authenticates the collector. The disk buffer holds up to 256 MB while a collector is unreachable and replays it afterwards.

Audit

auditd runs with a rule set that records changes to the configuration above, to credentials and to the system's own files. Its records go to /var/log/audit/audit.log, which auditd rotates itself (8 MB, five files), not to the journal; read them with ausearch -ts boot or ausearch -k <key>.