FluxDeployDocs
Topics: Relay sites page

Relay sites page

The Relay sites page (/sites) is the primary surface for managing registered relay sites from Core. Each row represents a remote relay server; clicking a row opens that relay site's dashboard (/sites/{id}) with live detail.

The page has two pills: Relay sites (this list) and Relay groups (/sites/groups). Every relay site belongs to one relay group, and the group decides which recipes (and with them images and drivers) it receives, plus any additional drivers - see Relay groups for how content reaches a relay.

For the broader concept of relays, registration, and the heartbeat protocol, see Relay sites.

Summary Cards

  • Relay sites - All registered relay sites
  • Online - Sites with recent heartbeats
  • Unreachable - Sites that have missed 3+ heartbeats
  • Pending Sync - Sites that still need to pull updated content

Registering a relay site

Register relay site in the page header opens a dialog with two ways in:

  • Fill in name, relay address and relay group (the default relay group is preselected) to register the relay site from Core, then download the generated relay.json.
  • Or hand the relay the auto-registration key shown in the same dialog (read-only, with copy) and let it register itself on first contact. A relay that registers itself joins the default relay group.

Approving a relay that registered itself

A relay that registers itself with the key is not trusted yet. Its row shows Awaiting approval and Core withholds everything sensitive from it: the domain-join, local Administrator and agent passwords, the agent bearer token, product keys, Autopilot credentials, the admin password hash, and the images, recipes and drivers you assign to it. The relay can heartbeat and show up here, nothing more.

An Admin approves it with Approve on the row (or Approve relay in the row actions). From then on the relay receives its manifest in full on its next sync. Operators and Read Only users cannot approve (the API answers 403). Sites you register from Core with the dialog's name and address fields are approved straight away, and every site that existed before this feature was introduced stays approved.

While a relay waits, each attempt to fetch withheld content is recorded in the Audit Log as RELAY_UNAPPROVED_ACCESS_REFUSED, and the approval itself as RELAY_SITE_APPROVED. If a relay appears that you did not install, delete it instead of approving it.

The key is generated, regenerated and revoked in one place only: Settings > Relays > Registration, linked from the dialog as Manage key. It is no longer displayed permanently above the site table.

Site Table

Columns: Site (name + address, linked to the site dashboard), Status, Health, Last Seen, Relay group, and Connected Cache (shown when the feature is licensed).

  • Relay group - The relay site's group, linked to the group's page. Receives no recipes under it means the group has no active recipe, so this relay site receives no recipes, images or drivers; assign recipes to the group or move the relay site. The same warning is on the relay site's page and, counted, as one line on the Dashboard.

  • Status - Online / Unreachable / Pending / Disabled / Maintenance, replaced by an Upgrade Pending / Upgrading badge while an upgrade runs.

  • Health - One rollup rather than four separate verdicts. The dot shows the worst state across content sync, boot image (Synced / Syncing / Building / Pending / Failed), relay version (outdated when behind Core) and the relay's own reported health score, which is the number shown. Only the parts that are not healthy get a line under the score; hover the cell for the full breakdown including PXE state, and open the site dashboard for the detail behind each part.

  • Connected Cache - Deployment progress bar plus live HTTP / HTTPS serve badges and the issuing CA read off the node's own socket. One cell carries both what Core provisioned and what the node actually serves.

Row Actions

  • Edit - Open the site edit dialog: name, address and port only (see Per-Site Overrides below; the relay group is changed on the site's Overview)
  • Approve relay - Release a self-registered relay's secrets and content (Admin only; shown only while the site awaits approval)
  • Force Sync - Request an immediate sync cycle
  • Delete Boot Image - Remove the boot image from the relay (PXE stops until a new image syncs)
  • Upgrade to v - Queue a relay upgrade to Core's version (shown for online, outdated sites; see below)
  • Download relay.json - Retrieve the site's configuration file
  • Maintenance Mode / Exit Maintenance - Pause a site for planned work; exiting auto-queues an upgrade (if outdated) or a sync + boot-image rebuild
  • Delete Site

Upgrading Relays

Relays upgrade in place from Core - no manual reinstall:

  • Per site - The Upgrade to v row action queues an upgrade job for that relay.
  • Upgrade All (N) - When outdated relays are online, an Upgrade All button appears in the header and queues upgrades for all of them at once.
  • Automatic - If a maintenance window is configured (Settings > Relays > Registration & Upgrades), outdated online relays are upgraded automatically inside the window, once per day.

The relay learns about a pending upgrade on its next heartbeat, downloads the update package from Core (SHA-256 verified), installs it, and restarts its service. If the new version fails to start, the relay restores the previous binaries automatically and the job is marked RolledBack.

Upgrades only go up. "Outdated" means older than Core. A relay running a NEWER version than Core is never pushed down - not per site, not by Upgrade All (which lists it as skipped, with the reason), and not by the maintenance window - and the relay itself refuses an older package. If you really need to downgrade one relay, an Admin can call POST /api/sites/{id}/upgrade?allowDowngrade=true; it is recorded in the audit log as RELAY_DOWNGRADE_TRIGGERED, and only that job lets the relay install the older version. The site row shows Upgrade Pending / Upgrading while the job runs; full per-job status (Downloading / Installing / Restarting / Completed / Failed / RolledBack) lives on the Jobs page under Relay Upgrades.

Site Dashboard

Clicking a site opens /sites/{id} - a full page organized into URL-addressable subtabs so you land on a focused Overview and drill in, rather than scrolling one long page. Each subtab is deep-linkable (/sites/{id}/{tab}) and works with browser back/forward.

  • Header - Site name, status badge, reported version, last heartbeat.
  • Actions bar (shown above the subtabs, on every tab) - actions and alerts only: Edit (the same name/address/port dialog as the sites table; the page shows the change as soon as you save; hidden for Read Only users), Download relay.json, Restart PXE services (soft, ~2 s) or Restart relay service (hard, ~15 s), and a stuck commands alert with a Clear action if a queued command has gone un-acknowledged for over 2 minutes.

Subtabs:

  • Overview (/sites/{id}) - The landing tab and the single home for this relay's live facts. When the relay is on two networks (Wi-Fi and Ethernet, or two default gateways), on Wi-Fi only, or its address keeps changing, a panel at the top says so, lists every network adapter with its addresses, and says what to do (see Relay network requirements). Stat cards (Total Devices, Deploying, Completed, Failed), Recent Deployments (latest machines with status), a What this relay site receives card ("Relay group: Branch offices - 3 recipes, 2 images, 14 drivers", with a warning when the group has no active recipe and a Change relay group picker to move the relay site to another group), a Sync Status card (boot image state and the active boot image name, synced images/drivers, last sync), and a Health card that leads with the verdicts - reported status, health score, PXE state, and a one-line Connected Cache rollup linking to the Cache tab - then, below a rule, the identity facts that rarely change: database provider, reported operating system (e.g. Windows Server 2022, Ubuntu 24.04, Rocky 9) and the relay URL. The cache rollup reads "Running, certificate expired" when the node is up but its certificate has lapsed, because a lapsed certificate makes clients bypass the cache silently.
  • General (/sites/{id}/general) - The single home for this site's settings: TFTP transfer speed, PXE mode, PXE Boot on/off override, PXE logging, and the PXE Client IP the relay bakes into its boot.wim, plus the assigned recipes with sync badges. Each shows the override you picked alongside Running: - the value the relay actually reports. It does not repeat the read-only boot image, PXE, health and database cards; those live on Overview, one click away, and the tab links there. Fleet-wide defaults are in Settings > PXE & Network Boot > Relay Defaults.
  • Images / Drivers (/sites/{id}/images, /sites/{id}/drivers) - Per-item sync status, size, hash, and transfer progress. Use these to verify that newly activated content has reached the site.
  • PXE Health (/sites/{id}/pxe-health) and Logs (/sites/{id}/logs) - Relay-side diagnostics.
  • Connected Cache (/sites/{id}/cache) - The whole per-site cache story: provisioning and container status, the certificate this node was issued (imported, issuer, expiry, last renewal) beside a live read of what it actually serves on ports 80 and 443, and the Enable / Redeploy / Disable actions. Shown only when Connected Cache is licensed (see Connected Cache). The Connected Cache cell in the sites table links straight here.

Force Sync

The Force Sync action sets ForceSyncRequested on the site; the relay picks this up on its next heartbeat (accelerated to 15s when a manifest change is pending) and performs an immediate sync cycle.

Per-Site Overrides

Open the site and use its General tab to override defaults without touching global settings. The Edit dialog (on the sites table and in the site page's actions bar) is identity only (name, address and port). The relay group is changed on the site's Overview, or on the group's page under Relay groups.

  • PXE Boot - Force ON / Force OFF for just this site, or defer to the global default
  • PXE Logging - Force detailed PXE logging on or off for this site
  • PXE Mode - ProxyDHCP or DHCP server options
  • PXE Client IP - which relay interface PXE clients use; changing it re-queues this site's boot.wim
  • TFTP Transfer Speed - Override the global High/Medium/Low TFTP mode (see PXE Boot); the site also shows which mode the relay is actually running

Overrides are pushed to the relay in the heartbeat response and take effect without a restart, typically within ~15 seconds.