Skip to content

Replicated certificates

Most certificates live in exactly one place: one Scout holds the file, one Scout serves it, one Scout's renewal keeps it current. Sometimes the same certificate and the same private key need to sit on more than one machine — a load balancer with two identical backends, or two servers that have always shared one hand-copied certificate because that is how the service was built. Cyphers calls the extra copies replicas.

A wildcard whose covered hosts sit on different Scouts is the one shape Cyphers does not deliver to automatically yet — see When a replica has to be updated by hand.

Owner and replicas

Every certificate still has exactly one owner — the Scout whose renewal produces it, chosen exactly the way it always has been. Every other active Scout the Hub has real evidence is holding that certificate and actually serving one of its names is a replica.

Replica status is discovered, never declared. There is no setting that marks a certificate as "shared." The moment a second Scout is seen holding the file at a live path and serving one of the names it covers, that Scout appears as a replica on the certificate's Manage row. Remove the copy, or let that Scout go dark, and it disappears from the list the same way — nothing to switch off.

Why the private key never moves

Key locality holds here exactly as everywhere else: private keys are generated on the endpoint and never leave it. A replica never receives a key from the Hub — only the certificate and its chain. Before installing anything, the Scout checks that the delivered certificate actually pairs with the private key already sitting on its own disk; if it doesn't, nothing is installed and the mismatch is reported plainly rather than papered over.

That check is also why key reuse matters more once a replica exists. The owner's renewal normally generates a fresh key every time — harmless when there is one copy, since the certificate and the key rotate together. With a replica in the picture, a fresh key on the owner would no longer match the copy sitting on the replica at all. So the moment the Hub can see a certificate has a replica, it requires the renewal profile to reuse the existing key instead, and refuses the renewal outright rather than let a rotation silently strand a replica holding a certificate its own key no longer opens.

How delivery happens

Once a renewal is verified, the Hub does two things for the owner as it always has — queues the deployment notification, then re-checks any sibling names on the same certificate — and, in between those two steps, ships the exact same certificate and chain it just installed on the owner to every replica. This is not a second renewal: a replica delivery creates no order, no separate certificate, and no renewal record of its own. It cannot make the owner's renewal succeed or fail, and a replica that fails to accept the copy never touches the outcome the owner already reached.

When a certificate covers more than one live-serving box and every one of them turns out to be a genuine replica of the others — the same shape a load balancer or a hand-copied SAN split produces — the Hub also places the renewal itself as one order rather than one per box: there is only ever one certificate to issue, and copying it out is what the fan-out above is for. A hostname whose backends hold genuinely different certificates keeps being renewed independently, exactly as before.

What the list and drawer show

On the Manage list, a certificate that lives on more than one Scout says so in the Scout column: every row it covers lists all its serving Scouts (api-io · vault-io), the SAN/Wildcard chip carries the same names, and a group header shows the union across its endpoints. The State column stays about the certificate's own health — replicas are a location fact, not a state, and the list renders no per-replica line.

Each replica's state lives in the endpoint drawer's Known certificates block, listed against the certificate it's about, with its file path and how long it's been in that state:

State What it means
Current This Scout's newest copy already is the certificate you're looking at.
Delivering A copy was just dispatched and hasn't been acknowledged yet (within about an hour of dispatch).
Behind No successful copy has landed — either nothing has been dispatched yet, or the last attempt is older than about an hour with no acknowledgment.
Key differs The last delivery attempt reached this Scout, but the certificate didn't pair with the key already on its disk.

If any replica is Behind or Key differs, the certificate's own state on Manage becomes Action needed, naming the Scout and the plain-English reason, until it's resolved — a lagging replica is not hidden behind an otherwise-healthy owner.

Automatic convergence

Copies converge on their own. Every five minutes the Hub checks each recently renewed certificate against every Scout that serves one of its names, and any Scout still holding the previous certificate is sent the new one automatically — without a button, and without waiting for the renewal to verify on the wire: an install the owner's own validation accepted is a good bundle, and whether each box serves it is that box's own story (its deploy hook, its reload). A delivery already in flight is never doubled up; a renewal that failed or rolled back converges nothing.

A Key differs replica is the one state convergence cannot fix by sending bytes — its on-disk key no longer pairs with the certificate, and no delivery can change that. Re-copy the key to that Scout by hand (or remove its copy); the next sweep then brings it current automatically.

(There used to be a per-replica Deliver again button here. It is gone — the sweep replaced it.)

When a replica has to be updated by hand

There is one shape Cyphers lists but does not deliver to: a Scout that only serves a host a wildcard covers, rather than a name the certificate itself presents. A certificate issued for *.example.com alone, with b.example.com served from a second Scout, is exactly this case.

The reason is that Cyphers has to name one directory on the replica for both halves of the operation — the key it adopts and the certificate it installs — and here there is no honest name: the covered host is not a name the certificate carries, and the wildcard is not a name that box answers for. So Cyphers refuses rather than write into a directory the certificate never mentions.

The replica still appears on the certificate, still reads Behind, and its note says plainly that the file has to be placed by hand; the convergence sweep skips it for the same reason, and a renewal on the owner will not reach it. Copying the new fullchain.pem across after each renewal is the workaround today.

A wildcard whose covered hosts all sit on the same Scout as the owner is not affected — that is one Scout, not a replica. And a certificate that names both the wildcard and the second host explicitly (*.example.com and b.example.com) is delivered automatically, because the second Scout then serves a name the certificate presents.

When a renewal is refused because of a replica

Four refusals exist specifically to stop a renewal from breaking a replica rather than let it happen silently, and none of them can be overridden:

  • The renewal's key policy would generate a fresh key while a replica exists.
  • A replica already holds a key that doesn't match — repairing that comes first.
  • The renewal profile uses the HTTP-01 validation method, which never hands the issued certificate back to the Hub at all — there is nothing to copy to a replica on that lane today.
  • The Hub could not work out whether this certificate has replicas at all (a database problem). It refuses rather than guess, because guessing wrong strands a replica.

Replicated certificates are DNS-01-only, by policy (operator ruling 2026-08-31), not just at renewal time. Adopting an endpoint, or repointing an already-managed one, onto an HTTP-01 profile is refused the moment you pick it if the certificate already has a replica — the same fact as the renewal-time refusal above, caught earlier so you don't discover it only after a renewal is due.

The exact messages, and what fixes each one, are in Recover from refusals.

What replication does not change

Everything else about the certificate works exactly as documented elsewhere: the owner's renewal, autopilot, adoption, scoring, the Cyphers Score badge. Replication is additive information layered on top of a certificate that otherwise behaves exactly like any other — it never changes who owns it, what renews it, or how its posture is judged.

Not yet supported, and one that's policy, not a gap

Rotating a replicated certificate's key today still means a manual re-copy — there is no Hub-brokered way to hand a new key from one Scout to another yet, which is exactly why the Hub refuses a rotation instead of stranding a replica silently. A replica that serves only a host a wildcard covers is, similarly, listed but never delivered to, as described above — both are open gaps, waiting on their own Hub-side or wire changes.

The HTTP-01 lane is different: a certificate on that lane cannot have replicas at all, and that is deferred by operator ruling (2026-08-31), not a gap Cyphers plans to close — the lane never gives the Hub the certificate it issues, so there is nothing a future change could hand to a replica without rearchitecting how HTTP-01 validates. Pick a DNS-01 profile for any certificate that needs replicas.

All three limitations are stated or refused loudly, before anything breaks — see the how-to below for the walkthrough of what a working setup looks like today.

Where to next