Skip to main content

Directory replicas

Applies to: directory 1.3.7 and later, agent 1.0.4 and later · Verified: 29.10.2026

An installation has one directory. Every further directory instance — in any platform's metaspace — is a replica of the same directory, like a second domain controller of one domain, not a second store. All instances hold the same accounts, groups, units, installation objects and attribute schema; each takes its own clients' and administrators' writes, and the changes reach the others by replication.

What replicates, and how​

  • Rows. Accounts (with their password hashes and second-factor secrets — a replica has to let people in), groups and membership, the tree of units and placements, the installation's objects (servers, services, sites, policies, address lists) and the schema's definitions, platform extensions included. The calendar does not replicate: it lives on the instance with the calendar profile.

  • Conflicts — as in Active Directory. Every attribute carries the version, time and instance of its last change; the higher version wins, at equal versions the later time. Multi-valued attributes (a group's members, an object's links) are compared value by value.

  • Deletion. A deleted row stays a tombstone for 14 days, in which every instance learns of it; a replica away longer loads again from scratch.

  • Transport. Instances read each other over SCIM (?since= on the /scim/v2/* collections), each with its own cursor, every minute, from both sides. One side's failure does not stop the other — the card keeps the error and the time of the last good pass.

  • Signing keys and tokens. Every instance signs platform tokens with its own keys, but under one issuer name — the primary's public URL, which the coordinator hands to the services and to every directory alike. On every pass an instance reads its peer's /oauth/jwks and publishes the keys of every instance of the installation at its own /oauth/jwks. A token a replica issued is therefore accepted by every service and every directory, whichever instance the coordinator points them at. Private keys never travel. The instance card shows, per peer, how many of its keys this instance knows.

The primary instance​

One instance is primary: the attribute schema changes there (the others redirect such requests to it), and it runs the outbound jobs — pushes to SCIM targets and the SIEM, the HRMS and upstream LDAP synchronisation, SAML metadata refresh. Everything the directory serves — LDAP for devices, sign-in, OIDC/SAML, the SCIM doors — every instance answers.

The oldest instance is primary by default. To move the role: Settings → Platforms → Directory → Make primary; every instance learns of the move with its next desired state. The clients are told the primary's name.

Adding a replica​

  1. Servers & deploys → Add a host → directory. While the installation has a live directory, the new instance joins as a replica automatically (the console says so in the invitation); pick the metaspace — the platform this instance will serve under its public name.
  2. The host comes up, receives the other instances' addresses and its own standing from the coordinator, and starts the initial load: the same replication pass from zero. On 50,000 accounts that is minutes. Until it is done the instance's /healthz answers replication: initial.
  3. The other instances receive the new peer with their next desired state — reading goes both ways.

No replication tokens travel: every instance of the installation holds the one service key, and they read each other with the directory's service token.

The synchronisation state in the console​

Settings → Platforms → Directory lists every instance: its platform, its standing (primary or replica), the replication state — current (read to the feed's head), loading (the initial load), alone (no peers) — and per peer: the time of the last good pass, the cursors per collection, the number of failures in a row and the last error. The instance's GET /healthz answers the same under replication, as does GET /control/replication of its control API.

A peer that stays in error is almost always the network between the instances' public names or a certificate: a replica reaches its peer by its public name, as a client does.