Settings Sync: Trusting a Peer Server

Settings Sync pushes configuration from one Athena server to another over HTTPS. Before that push can connect, the sending server has to trust the receiving server's certificate. Every Athena server mints its own private certificate authority the first time it starts, so a fresh peer looks untrusted to everyone else — and the very first Test fails, usually with nothing more than a vague connection error. This page is the one-time setup that gets that trust in place so pushes go through.

The recommended way is to upload the receiver's CA under Settings → Sync → Outgoing peers → Trusted CAs on the sender. It needs no operating-system trust store changes, so it works the same on the virtual appliance, in Docker, and on Windows and Linux server installs. Importing the CA into the Windows machine trust store still works too, and is described as an alternative.

Why trust is needed#

Each Athena server generates its own Root Certificate Authority on first start, and that CA signs the server's own HTTPS certificate. The sending server has never seen the receiver's CA, so when it opens the HTTPS connection to push a bundle it treats the receiver's certificate as untrusted and refuses to continue.

The fix is one-directional: the sender must trust the receiver's CA. The receiver does not need to trust the sender — it authenticates the sender with the sync token instead. Repeat this step once per receiver: three receivers means three CA certificates trusted on the sender.

1 · Get the receiver's CA certificate onto the sender#

Two servers are involved, so be precise about which is which: the certificate belongs to the receiver, and it has to end up on the sender — the sender is what needs to trust it. The quickest way to do both at once is to sit at the sender and download it straight from the receiver.

1. Sit at the sender and open a browser there.
2. Browse to the receiver's address — the hostname in this URL is the receiver's, not the sender's:

   https://RECEIVER-HOSTNAME:8443/api/pki/ca/download?format=cer

3. Save the file. It is named athena-root-ca.cer.

No sign-in is required — the CA certificate is public information, so this endpoint is open. Your browser will warn that the site is untrusted; that warning is the problem you are fixing, so continue past it.

Prefer the interface? Sign in on the receiver, open Settings → Security → Certificate, and use Download CER (Windows/GPO) or Download PEM (Linux/macOS), then copy that file across to the sender yourself. Same certificate, one extra step.

Either format can be uploaded to Trusted CAs. Use the CER file if you will import it into the Windows store instead.

2 · Add it under Trusted CAs on the sender#

Sign in on the sender and open Settings → Sync. On the Outgoing peers sub-tab, below the peer list, is the Trusted CAs section: the CA certificates this server trusts for the HTTPS certificate of the peers it pushes to, in addition to the operating system's trust store.

1. Under Upload CA certificate (.cer, .crt, .pem), choose the receiver's CA file from step 1. .cer, .crt, .pem and .der files are accepted, as PEM text or binary DER.
2. On success a Trusted CA added: subject message appears and the CA is listed in the table.
3. Repeat for every receiver this server pushes to.

The change applies to the very next push or peer Test — no server restart is needed. Each push opens a fresh TLS connection, so removing a CA also takes effect immediately.

What the upload accepts

Every CA in this list becomes a trust anchor for pushes, so the upload is strict. It must be exactly one public CA certificate that has not expired. Anything else is refused with a Certificate refused: reason message:

Files larger than 64 KB are rejected before upload with "The file is too large to be a CA certificate."

The Trusted CAs table

Use the delete button on a row to stop trusting a CA. With the list empty, the panel reads "No trusted CAs. Pushes trust only the operating system's store and this server's own CA." — so a receiver whose certificate was issued by the sender's own CA, or by a CA the operating system already trusts, needs no entry here.

• Who can manage it: anyone with the settings.manage permission — the same as the rest of the Sync settings. It is configuration, so it is available whether or not the server's licence includes Settings Sync.
• Per server: the list belongs to the server you edit it on. Settings Sync does not push it to other servers.
• Audited: uploads and removals are recorded as SettingsSyncTrustedCaAdded and SettingsSyncTrustedCaDeleted, with the CA's subject and SHA-256 fingerprint. A refused upload is written to the server log, not the audit log.

Managing trusted CAs from the REST API

The same list is available to scripts. All three calls need settings.manage.

The POST body carries the certificate as PEM text, or as base64 of the DER bytes:

POST /api/settings/sync/trusted-cas
{ "certificate": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----" }

Alternative · Trust it in the Windows certificate store#

On a Windows server install you can skip Trusted CAs and use the operating system instead. The push accepts any certificate the OS already trusts. Still on the sender, install the receiver's .cer into the Local Machine trust store — not your user store. The Athena server runs as a service and does not read your personal certificate store.

Double-click athena-root-ca.cer, then:

1. Install Certificate…
2. Store Location: Local Machine (not Current User) → Next → accept the prompt
3. Place all certificates in the following store → Browse… → Trusted Root Certification Authorities → OK
4. Next → Finish → confirm the security warning

Or, in PowerShell run as Administrator:

Import-Certificate -FilePath "$env:USERPROFILE\Downloads\athena-root-ca.cer" `
  -CertStoreLocation Cert:\LocalMachine\Root

You will end up with two certificates named Athena Root CA in that store — the sender's own and the receiver's. That is expected; they are different certificates and differ by thumbprint.

3 · Check trust#

If you used Trusted CAs, check from the console: on the sender's Settings → Sync → Outgoing peers, use the peer's Test button. Test uses the same trust as a real push. Success reads "The peer is reachable and accepted the sync token." A certificate problem shows as "Could not reach the peer." with the underlying TLS error as detail. Trusted CAs apply only to Athena's own pushes, so a browser or PowerShell on the same machine will still warn about the receiver's certificate. That is expected.

If you used the Windows store, confirm trust before touching the Sync screens. In PowerShell on the sender:

Invoke-RestMethod "https://RECEIVER-HOSTNAME:8443/health"

A result means the sender trusts the receiver. A certificate error means the import did not take — most often because it went into the Current User store instead of Local Machine, or the URL used a name that is not on the certificate (see Use the hostname, never the IP).

Use the hostname, never the IP address#

The receiver's certificate is issued for its hostnames. An IP address is normally not on the certificate, so https://192.168.1.50:8443 fails even after the CA is trusted — the trust is fine, the name does not match.

Use the same hostname everywhere: in the check above and in the peer's Base URL on the Sync screen. If the sender cannot resolve that name, add it to the sender's hosts file (C:\Windows\System32\drivers\etc\hosts) rather than falling back to the IP. Peers saved with a plain http:// URL are rejected outright — Settings Sync is HTTPS only.

Troubleshooting#

• Push fails with "Could not establish TLS with peer 'name' … its certificate is not trusted by this server". The sender does not trust the receiver's CA. The message gives the exact download URL for that peer's CA. Upload it on the sender under Trusted CAs, then push again. No restart is needed.
• The CA is listed under Trusted CAs, but pushes still fail TLS. Check the SHA-256 column against the receiver's current CA. If the receiver's CA was regenerated, the old entry no longer matches — delete it and upload the new one. Otherwise the peer URL's host name does not match the receiver's certificate (next item).
• Trust is in place but Test still fails on a name mismatch. You are using an IP address or a name that is not on the certificate. Use one of the receiver's real hostnames everywhere — see Use the hostname, never the IP.
• Windows: certificate imported but still not trusted. It most likely went into the Current User store. Re-import into Local Machine → Trusted Root Certification Authorities; the service reads only the machine store.
• Push refused with "loop detected". Two servers share an Instance ID — usually cloned servers. Give each a unique SettingsSync__InstanceId and restart.
• Push refused even though trust and the token are fine. The receiver has Sync disabled — a receiver with Sync off refuses every bundle. Turn Enabled on in the receiver's Settings → Sync.

Related#

• Settings Sync — what sync does, setting groups, sync tokens, push behavior, and topologies.
• Certificates & PKI — the built-in Root CA, downloading it, and certificate lifecycle.
• Server TLS Certificate — how each server's HTTPS certificate is issued and named.
• Network Ports & Firewall — the ports a sender needs open to a receiver.
• Air-Gapped Operation — keeping isolated servers consistent with no outbound calls.