Skip to content

Updating the agent (OTA)

Updating a device's edge agent is: publish a release by tagging edge/gateway (tags are named vX.Y.Z-beta; every tag publishes to the beta channel in both dev and prod), promote it to stable per environment with the manual promote:stable:<env>:<arch> jobs once a canary has taken it, then press Update agent on the device page. Publishing and channels are described in Agent Releases.

The Agent version card

On a device page the Agent version card shows:

  • Running: the version the agent reports.
  • Channel: stable or beta. Changeable from the card; a device on beta is marked as a test channel.
  • Pinned to: shown when the device is pinned to a specific version.
  • Latest available and Update available: version when the channel offers something newer, otherwise The agent is up to date.

Changing the channel, and updating, need write access to the device (ORG_OWNER, ORG_MEMBER, DEVICE_OWNER, support roles, platform admin). Only assigned devices receive updates.

Running an update

Update agent asks for confirmation (Update the agent from X to Y?) and records the desired version. Nexus then nudges the device; if it is offline the update is recorded and happens when it next connects (The device is offline and will update when it next connects).

PortalGatewayService.UpdateGatewayAgent with an empty target_version tracks the latest release on the device's channel and clears any pin; a non-empty target_version pins the device to that version. The portal button uses the latest.

The card then shows the phases: Scheduled, Checking for update, Downloading, Verifying signature, Installing, Restarting, Confirmed (or Update failed, with Retry update). See agent-update progress.

What the device does

  1. Downloads the binary from a presigned URL into its environment's bucket.
  2. Verifies the sha256 and the ed25519 signature against the public key baked into the running agent at build time.
  3. Swaps the binary under an out-of-process watchdog.

If the new agent does not confirm within the probation window (90 seconds), the watchdog restores the previous binary.

Devices that cannot self-update

Only an agent built by the tag pipeline carries the OTA public key. An agent built any other way (a local build, make build-openbsd) cannot verify releases; it logs self-update disabled (no release signing key in this build) at startup and refuses OTA updates.

An install image therefore has to embed a release binary. The image builders in provisioning/openbsd-autoinstall enforce it: they take AGENT_VERSION (fetched and verified) or AGENT_BIN, and stop on an agent without the release signing key unless ALLOW_UNSIGNED_AGENT=1 marks a bench image. See The agent must be a release build, Provisioning and Write the image to a USB stick.

A device already running a non-release agent needs a release agent installed once, by reflashing or by hand; every update after that is the Update agent button.