Skip to content

Self-Update

The agent side of over-the-air updates: internal/selfupdate, driven from internal/connector. For the whole system (release registry, channels, presigned URLs, portal) see OTA Agent Updates and Agent Update Progress.

When the agent checks

reconcileAgent runs at startup, every 30 minutes (agentReconcileInterval), and when Nexus pushes an update_agent nudge. The nudge carries nothing: the agent always asks GetDesiredState, so a command cannot choose which binary to run. An update already on probation makes a reconcile a no-op.

It first confirms a pending update (reaching Nexus with the new binary is the evidence it works), then asks for desired state and applies the update it names, if any.

Apply

  1. Download to <binary>.new, next to /usr/local/sbin/edge-agent on the same filesystem. HTTP/1.1 only (the object store resets HTTP/2 bodies past about 10 MiB), up to 4 attempts, resuming from what already arrived; an expired URL (403) or missing object is not retried, and the next reconcile gets a fresh URL. Size cap 128 MiB.
  2. Verify the sha256 and the ed25519 signature against the public key baked into the running binary. A binary built without that key (otaSigningPublicKey empty) refuses to self-update at all.
  3. Sanity check: run the new binary's version and require the expected version.
  4. Back up the current binary to <binary>.bak, write the pending marker, and arm the watchdog.
  5. Swap with an atomic rename over the live path (valid while the old binary runs).
  6. Restart the service, detached from the agent process.

Nothing on disk changes until the download is verified; every failure before the swap leaves the device as it was. Each phase (checking, downloading, verifying, installing, restarting, then confirmed or failed) is reported over the WebSocket for the portal's timeline.

The watchdog

update-watchdog.sh in the data directory, launched detached so it survives the agent restarting or dying. After the probation window (90 s, ProbationWindow):

  • if the new agent wrote the confirmation marker, it cleans up and exits;
  • otherwise it logs (edge-agent-watchdog), stops the new agent and force-kills anything left, restores the backup with a staged copy and atomic mv (a direct copy onto a binary that is running fails with ETXTBSY), removes the pending marker after the restore, and starts the agent again.

Nexus infers the outcome from the version the device reports when it reconnects.

The watchdog covers exactly one failure: a new binary that does not confirm within 90 s. Everything later is the self-heal guard's job.