Relay sites

A relay site is a remote FluxDeploy server that caches images and drivers locally and serves as a self-contained deployment server for its location. Agents at each location connect to their local relay rather than the central Core server, reducing WAN bandwidth and improving deployment speed.

Every relay site belongs to one relay group, and the group decides which recipes (and with them images and drivers) the relay site receives, plus any additional drivers. A new relay site joins the default relay group, which carries every recipe and every Windows driver unless you take them out - so a relay receives content as soon as it is approved. See Relay groups for how content reaches a relay.

Relay sites and relay groups share one home in the Core UI: Relay sites (/sites) and Relay groups (/sites/groups), two pills on the same page.

Registering a relay site#

On Relay sites, click Register relay site:

• Name - A descriptive name (e.g., "Chicago Office", "Branch 42")
• Relay IP Address - The relay server's IP address (IPv4 or IPv6, max 45 chars) and HTTPS port
• Relay group - The group whose recipes and drivers this relay site receives. The default relay group is preselected (see Relay groups)

On registration, the system generates a 256-bit API key for secure relay-to-Core communication. A downloadable relay.json file is produced containing all connection details.

Network requirements#

A relay needs one wired network. A relay on Wi-Fi and Ethernet at the same time keeps changing its address, which rebuilds its boot image and breaks Core's calls to it; Core flags it as an error on the site's Overview and its row. See Relay network requirements.

Configuring the Relay#

Place the generated relay.json in the relay server's application directory. It contains:

• Core Server URL
• API Key
• Site ID
• Core TLS certificate thumbprint (for certificate pinning)

Alternatively, configure via the relay's web UI at Settings > Relay Configuration.

Certificate pinning and first contact#

CoreCertThumbprint is what makes a stolen API key insufficient to impersonate Core, so the relay requires it. Every request the relay makes carries its API key; without a pinned thumbprint there is nothing to stop an on-path attacker answering the first connection, taking the key, and becoming the identity the relay pins permanently.

Both supported provisioning paths supply it for you:

• The relay.json downloaded from Relay sites > Register relay site already contains Core's thumbprint.
• Auto-registration (installer + registration key) writes it from Core's registration response.

A relay started with no thumbprint refuses to connect and logs what to do. Paste Core's SHA-256 thumbprint (Settings > Security > Certificates on Core) into Relay.CoreCertThumbprint and restart the relay service.

If you genuinely cannot pre-seed a thumbprint, set Relay.AllowTrustOnFirstUse to true. The relay then trusts the first certificate it is offered and pins it, logging a warning that names the adopted thumbprint - compare that against Core before relying on it.

Auto-registration is the one exception: it has no earlier channel to inherit trust from, so it proceeds without a pre-seeded thumbprint rather than refusing. When it does, Core records a CERT_PIN_TRUSTED_ON_FIRST_USE entry in the Audit Log naming the site, the relay logs a warning, and relay.json is marked with CoreCertThumbprintTrustedOnFirstUse so the unverified pin stays distinguishable from one you supplied. Verify the thumbprint and remove that marker.

Once a thumbprint is pinned, a change to it is never accepted silently: a rotation Core pre-publishes over the already-pinned channel is adopted seamlessly, but a certificate that simply turns up different stops sync and waits for an admin (see AllowAutoCoreCertRepin).

Approval of self-registered relays#

A relay that registers itself with the registration key joins the default relay group and stays unapproved until an Admin approves it on Relay sites. Until then Core sends it no passwords, keys or tokens and none of its group's images, recipes or drivers, and admin-credentials answers 403 with the reason. Relay sites registered from Core, and all relay sites that existed before approval was introduced, are approved already. See Relay sites page.

Site Lifecycle#

Heartbeat#

Relays send a heartbeat to Core every 2 minutes (configurable). The heartbeat includes:

• Machine and recipe counts
• Synced image and driver IDs
• Deployment events (forwarded from agents)
• PXE status and TLS certificate thumbprint
• Boot WIM SHA-256 hash
• Which PXE boot files the relay is missing, if any

The last two are separate answers to separate questions. The hash says the relay holds the right boot.wim; the missing-files list says whether it can actually serve a boot. A relay's boot image stays at Syncing - it is not marked Synced - until that list is empty, because boot.wim is only one of the files a PXE client fetches. A site stuck on Syncing shows the reason on Boot Images > (image) > relay table, and the full per-file inventory is on Sites > (site) > PXE & Health.

Core responds with:

• Manifest change notifications
• PXE and logging configuration
• Boot image availability
• Certificate thumbprint for relay-to-Core pinning

Content Sync#

Content syncs on a schedule (default every 30 minutes) and when Core signals a manifest change. The sync process:

1. Relay requests the manifest: its relay group's active recipes, their images and drivers, the group's additional drivers, and the settings
2. Compares manifest hash against the local copy
3. Downloads new/updated content with resumable transfers (HTTP Range + ETag)
4. Reports sync completion

If the relay's image cache removed an image to make room, the next sync downloads it again. A machine that asks the relay for that image in the meantime is told the relay is re-downloading it (HTTP 503 with a retry time) rather than that the image does not exist, and the request starts a sync straight away.

Managing relay sites#

The Relay sites page provides:

• Summary cards - Relay sites, Online, Unreachable, Pending Sync counts
• Search and filter - By name, IP, relay group, or status
• Per-site actions - Edit, Force Sync, Delete Boot Image, Delete Site
• Relay group column - links to the group, and warns when the relay site receives no recipes
• Site dashboard - Click a relay site row to open /sites/{id}: what it receives and its relay group (changeable there), sync status, boot image info, PXE status, and per-item sync details

See Relay sites page for the detail.

Force Sync#

Click Force Sync on a site to trigger an immediate sync on the next heartbeat. This sets ForceSyncRequested on the site entity, and the heartbeat response tells the relay to sync immediately.