Air-Gap End-to-End Workflow

The complete operator workflow for moving packages across an air gap with SysManage — from choosing server roles to air-gapped hosts installing updates from the local mirror. The Deployment guide covers the architecture and the Runbook covers day-to-day operations; this page is the linear "do this, then this" path that ties them together and points at the exact UI controls involved.

Overview

An air-gap deployment is a pair of SysManage servers. The Collector sits on the internet-connected side, mirrors upstream packages, and burns a cryptographically-signed ISO. You physically carry that ISO across the gap. The Repository sits on the isolated side, verifies and ingests the ISO, serves the packages over HTTP, and automatically repoints every managed agent at that local mirror so the agents never reach the internet.

Set roles — one server to Air-Gap Collector, one to Air-Gap Repository (Settings → Server Role).
Establish trust — copy the collector's public key and import it on the repository.
Collect & burn — run a collection on the collector to produce a signed ISO; write it to optical/USB media.
Import — carry the media to the repository, select the drive, and import.
Serve & repoint — the repository serves the mirror and agents are repointed automatically.

Step 1 — Assign server roles

On each server, go to Settings → Server Role and pick the role. The role is stored in the database and takes full effect after the next server restart (the role-specific Pro+ engine loads at startup).

On the internet-connected box, choose Air-Gap Collector. Selecting this role automatically generates the ed25519 manifest-signing keypair at /var/lib/sysmanage/airgap/collector-ed25519.pem (private, mode 0600) plus its .pub sibling — no manual keygen.
On the isolated box, choose Air-Gap Repository.

Step 2 — Establish trust (copy & import the public key)

The repository will only ingest media signed by a collector it trusts. Trust is established by copying the collector's public key to the repository — the private signing key never leaves the collector.

On the collector, in Settings → Server Role, the Collector Public Key card shows the public key and its fingerprint. Click Copy Public Key to put the PEM on your clipboard (and note the fingerprint — it matches the signer_fingerprint stamped into every manifest).
Move the key text to the repository over any channel you trust (it's a public key — sneakernet, signed email, or an existing trusted ingest all work).
On the repository, in Settings → Server Role, use the Trusted Collector Keys card: give the collector a name, paste the PEM, and click Import Key. The imported key is written to /var/lib/sysmanage/airgap/trusted-collectors/<name>.pub and the card lists it with its fingerprint. The keyring holds multiple keys, so you can trust several collectors and rotate keys without downtime.

Step 3 — Collect and burn on the collector

On the collector, the Air-Gap Collections page drives a collection run that mirrors the selected repositories, builds the signed ISO, and (optionally) burns it to a disc.

Start a new collection run with an ISO label and the distros/repos to include. The run walks QUEUED → MIRRORING → STAGING_COMPLETE → BUILDING_ISO → ISO_BUILT → COMPLETE; the page polls and shows the live status.
Leave the burn device blank to build a single downloadable ISO of any size (for attaching to a VM or writing to USB yourself); set a device to add a burn stage. The size column reflects the real built ISO size.
When the run reaches ISO_BUILT/COMPLETE, use the download icon. Downloads stream directly to disk via a short-lived token, so multi-gigabyte ISOs download without buffering in the browser.

Step 4 — Transport and import on the repository

Carry the optical disc or USB media to the repository. The repository imports directly from the drive — no copying the ISO onto the server's disk first.

On the repository, in Settings → Server Role, the Import Drive card lists eligible block devices (the OS disk is never offered). Pick the optical/USB drive — the lowest-numbered optical drive is the default. Use Rescan after inserting media.
Insert the media into that drive.
Go to the Air-Gap Repositories page. The Import from Media panel shows the drive's live status; the Import ISO button enables when the drive holds readable ISO media. Press it. (Use Rescan if you just inserted or fixed the disc.)
Import mounts the media read-only, verifies the embedded signed /manifest.json against your trusted-collector keyring, and rsyncs the verified payload into /var/lib/sysmanage/airgap-repo. Watch the run status: VERIFYING_SIG (signature check), COPYING (rsync in flight), COMPLETE. A disc from an untrusted collector simply fails at verification.

Step 5 — Serve the mirror

On COMPLETE, the repository registers a per-distro local repository (visible on the Air-Gap Repositories page with package count, last-ingest time, freshness, and the signer fingerprint) and serves it over HTTP from the SysManage web port at /airgap-repo/. The registered repository URL points at the actual apt/dnf tree inside the media, so no manual web-server or symlink setup is needed.

Step 6 — Agents repoint automatically

Any agent managed by a server whose role is Air-Gap Repository is automatically repointed at the local mirror: its package manager is configured to use the repository's mirror and its online sources are disabled. This happens on the agent's normal communication cycle, so it also catches agents that were already connected when you changed the role — they update on their next check-in. The directive is self-throttling: it re-dispatches only when the mirror configuration actually changes (a role flip or a fresh ingest), so there's no repeated apt-get update churn.

On an air-gapped host you can confirm with apt-cache policy <pkg> (the candidate should come from the repository's /airgap-repo/ URL) and apt list --upgradable (sourced entirely from the mirror).

Ongoing updates

Repeat Steps 3–4 on a cadence (manually or via a scheduled collection). Each ingest refreshes the mirror in place and updates the freshness shown on the Air-Gap Repositories dashboard; agents pick up the new package set on their next update. The Runbook's freshness and key-rotation sections cover how often to do this and how to age out trusted keys.