Documentation > Professional+ > Multi-Site Federation
⭐ PRO+ ENTERPRISE

Multi-Site Federation

A coordinating SysManage server aggregates host inventory, compliance posture, vulnerability exposure, and dispatched commands across many subordinate site servers running independently at each data center, branch office, or cloud region.

Overview

Large enterprises operate data centers, branch offices, and cloud regions across multiple geographic locations. Managing thousands of hosts from a single SysManage server creates scalability bottlenecks, network latency issues, and single-point-of-failure risk.

The federation Pro+ Enterprise SKU introduces a hierarchical architecture: many subordinate site servers operate autonomously at each site, while a Federation Controller aggregates data and dispatches commands across the entire enterprise. The controller never talks to agents directly — everything flows through site servers, preserving local-autonomy semantics if a network partition isolates a site.

Engine Modules

Federation ships as two Pro+ engines in one Enterprise license — a server runs exactly one role at a time, picked by role: in sysmanage.yaml.

Federation Controller Engine

Loaded on the coordinating server. Owns the site registry, accepts upstream rollup pushes from sites, exposes cross-site host search, drives policy push and command dispatch, and writes the federation audit log.

  • Site server registry: enroll, suspend, resume, remove
  • Secure enrollment workflow with mutual-TLS certificate pinning
  • Host-directory tier (~1 KB × 1M-host target ≈ 1 GB)
  • Aggregate rollups: host counts, compliance scores, CVE exposure
  • Polymorphic policy push (update profiles, firewall roles, compliance baselines) with stale-version detection
  • Command dispatch with a strict FSM (queued → in-progress → terminal)

Federation Site Engine

Loaded on every subordinate site server. Handles the inbound side of the federation protocol (enroll, accept policy pushes, accept dispatched commands) and drains an outbound sync queue back upstream.

  • Coordinator enrollment + handshake
  • Upstream data sync (host deltas, compliance + vulnerability snapshots)
  • Downstream policy + command inboxes
  • Offline queue with deduplication-on-replay
  • Local autonomy mode — agents continue reporting and commands run locally when the coordinator is unreachable

Data Architecture

Federation data is split into three tiers, deliberately partitioned so the coordinator scales linearly with sites rather than with hosts:

  1. Aggregate tier (coordinator) — one row per site per metric. Host count, healthy/unhealthy ratio, compliance %, top CVEs by severity, alert counts, last-sync timestamp.
  2. Host-directory tier (coordinator) — one row per host fleet-wide, holding only the columns operators filter on (hostname, IP, OS, status, geo, tags). Sized for ~1 KB × 1M hosts.
  3. Detail tier (sites) — full software inventory, certificate chains, audit log bodies, OS-specific facts. Never replicated upstream; drill-down queries are proxied to the originating site.

Coordinator UI

When the federation controller engine is loaded, several new pages become available in the SysManage web UI:

  • Sites (/sites) — card grid of enrolled sites with status traffic light, last-sync, host count. "Enroll Site" button generates a one-time enrollment token for delivery to the new site server.
  • Site detail (/sites/:siteId) — per-site metadata, connection card, and lifecycle actions (Suspend / Resume / Remove). "See hosts" deep-links into the Hosts page filtered by this site; "View audit log" deep-links the audit log viewer pre-filtered.
  • Sites map (/sites/map) — geographic Leaflet map of every site at its operator-supplied (lat, lng). Click markers for popup details + deep-link into site detail.
  • Policies (/federation/policies) — CRUD on coordinator-defined policies (update profiles, firewall roles, compliance baselines). Assign to multiple sites, push immediately, deactivate.
  • Federation audit log (/audit/federation) — every cross-site operation (enrollment, suspend/resume/remove, policy push, command dispatch) with URL-shareable filters by site, operation, and actor.

Enrolling a Site

  1. On the coordinator's Sites page, click Enroll Site and fill in name, URL, and an optional location label. The default token TTL is 24 hours.
  2. Copy the displayed enrollment token once — it is not retrievable afterwards.
  3. On the new site server, run the federation enroll command with the coordinator URL + the token. The site engine presents the token over mutual TLS to complete the handshake.
  4. After successful handshake, the site flips to enrolled status on the coordinator, the token hash is scrubbed, and the enrolled_at timestamp is stamped.

If the token leaks or expires before the site completes enrollment, use Regenerate token on the site detail page to invalidate the old one and issue a fresh value.

Licensing

Federation is part of the SysManage Enterprise tier. The Enterprise license entitles a deployment to load either the federation controller engine or the federation site engine on any server — the role is configured in sysmanage.yaml. On Community / Professional installs, the federation API endpoints return 403 pro_plus_required and the UI renders an Enterprise upsell on every federation page.