Update the appliance
Install a signed release from the online channel or from an offline bundle, know what happens while it runs, and roll back if it does not come up healthy.
- Version: 0.4
- Role: admin_user
- Type: task
Every CID222 release is signed, verified before anything on the appliance changes, and rolled back automatically if the new version does not come up healthy. You apply one from the release channel if the appliance has internet, or from a bundle you carry in if it does not.
What do I need?
- Licence
- Any
- Role
admin_user
Prerequisites
- The appliance has completed the first-boot setup wizard.
- You can sign in to the dashboard with a tenant that has the admin_user role.
- Disk headroom: roughly three times the bundle size free for an uploaded bundle, or 15 GB free for an online install. The updater refuses to start without it.
- For the online path: the appliance can reach the release channel over HTTPS, and the channel host is allowed for online installs.
- For the offline path: the signed .cidupd bundle for the target version, on a machine whose browser can reach the appliance.
- A maintenance window. The dashboard is one of the containers that is replaced, and writes can block while database migrations run.
The appliance never checks for updates by itself. A check happens only when you ask for one, and the work is done by a privileged updater on the appliance host — the dashboard queues the request and streams back what the updater reports.
Check which version you are on
Open the update page
Select Settings → System Updates.
The Installed version tile names the running release and, where one exists, the previous
release and whether a rollback is available. The Channel tile names the release channel, or
states that none is configured. A version of 0.0.0 means the appliance cannot read its own
version stamp rather than that it is unreleased.
/assets/screenshots/system-updates@0.4.pngInstall a release
Select the online source
On Settings → System Updates, open the Online tab.
The Update channel is pre-filled from the appliance's configuration. Use use a custom URL and Custom manifest URL only when this appliance must pull from a different host than the one it was configured with.
Start the install
Select Check & install.
The appliance fetches the channel manifest, verifies its signature, and — if the release is newer than the installed one — begins the install. Progress streams on the page. Where an update is already known to be available, the page instead offers Install for that version directly.
What happens while it runs
The updater works in a fixed order and stops at the first step that fails:
- It verifies the signature on the manifest or bundle. An unsigned or altered release is refused.
- It stages the release images, pinned by digest.
- It takes two backups of the database — a logical dump and a physical snapshot of the data
directory — under
/var/lib/cid/backups. The last 14 dumps are kept. - It applies the database migrations to a throwaway clone first, as a dry run.
- It applies the migrations for real, swaps in the new containers, and health-gates them.
- If the new version does not come up healthy, it rolls back to the previous release and restores the database from the snapshot it took in step 3.
The page shows a duration estimate for the run, derived from the size of the database and the number of migrations actually pending. Migrations run before the new images start, so the still-serving old version runs into their locks: when the estimate says writes may block, they will. The dashboard itself is replaced during the swap, so the page disconnects and reconnects on its own. The appliance's address does not change.
Warning
A release refuses to install over a version older than the minimum it names, and the updater refuses a downgrade. To go back to an earlier release, use the rollback below rather than installing the older bundle.
Roll back
Rollback is supported, and it is the same operation the updater performs automatically on a failed health gate. It returns the appliance to the previous release and restores the database snapshot taken before that release was applied.
Confirm a rollback is available
On Settings → System Updates, read the Installed version tile.
It names the previous version and states that a rollback is available. If it does not, this appliance has no previous release to return to and the rollback control is disabled.
Roll back
Select Roll back to the version named, and confirm.
The updater snapshots the current database first, then reverts the images and restores the earlier database. Data written since the update was applied is not carried back.
Danger
A rollback restores the database as it was before the update. Anything recorded since — sessions, detections, event log entries, configuration changes — is lost. Roll back to recover from a broken update, not to undo a configuration mistake.
Verify
- Settings → System Updates shows the new release under Installed version, and Last update reports the run as successful with the old and new versions.
- Sign in and open a product page. It loads, rather than reporting that the appliance is unavailable.
- Settings → License still shows your tier and expiry. An update never changes the licensed package.
- Where the Host repair tile is shown, every migration it lists reads as applied rather than pending or failed.
If it fails
The System Updates page shows 0.0.0, or the update buttons return 500
You might see: System Updates shows version 0.0.0 · current version 0.0.0 · update check returns 500 · install update → 500
Before you start
Checks
- 1
Read the product version the appliance reports
diagnostics · appliance.version = "0.0.0"
- 2
Verify an update channel is configured
diagnostics · appliance.channel
- 3
Verify the release channel answered on the last attempt
diagnostics · appliance.update.channelReachable = true
- 4
Check whether an update or host-repair intent is stuck waiting for the host updater
diagnostics · appliance.update.pendingIntent
- 5
Read the host-repair status, which is what the page renders alongside the version
GET /admin/system-update/host-repair
Causes and fixes
| Reached when | Cause | Explanation, fix and verification |
|---|---|---|
| check 1 fails | version-file-missing (warning) | The appliance reads its installed version from a file the image build writes. When that file is absent or unreadable the version falls back to 0.0.0, and every comparison against the channel manifest then looks like a downgrade — which is why the page can show 0.0.0 and simultaneously refuse to offer an update. Fix: Run the host repair from Settings → System Updates, which rewrites the appliance version file, then reload the page. If host repair is unavailable, the version can be restored by re-running the installer's finalisation step; see Update the appliance. Verify: diagnostics · appliance.version = "0.0.0" If that does not apply: Attach the support bundle. A 0.0.0 that survives host repair means the image was built without its version stamp. |
| check 2 fails | manifest-url-unset (warning) | No release channel is configured, so the update check has no manifest to fetch. The API rejects the call with a 400 naming the missing manifest URL, which the page surfaces as a failed button rather than as a configuration prompt. Fix: Set the update channel under Settings → System Updates. On an air-gapped appliance, choose the offline channel and upload the update bundle instead of pointing at a URL. Verify: diagnostics · appliance.channel |
| check 3 fails | channel-unreachable (warning) | The channel is configured but the manifest fetch failed — no DNS, no egress, or an outbound proxy that is required and not configured. The fetch failure surfaces as a 500 from the update endpoint. Fix: Fix outbound access to the channel host, or switch the appliance to offline updates. Read the DNS and egress probes in the diagnostics snapshot separately: resolution succeeding does not mean the HTTPS fetch succeeds, and a proxy-only network needs the proxy configured explicitly. Verify: diagnostics · appliance.update.channelReachable = true |
| check 4 fails | updater-daemon-not-running (critical) | An intent is queued but nothing is executing it. The gateway only records the intent; the privileged updater daemon on the host performs the work. When that daemon is not running, intents accumulate and every subsequent action appears to hang or fail. Fix: Start the updater daemon on the appliance host and confirm the queued intent moves out of the queued state. Do not queue further intents until it does; a backlog makes the failure harder to read. Verify: diagnostics · appliance.update.pendingIntent If that does not apply: Attach the support bundle plus the updater daemon's own log from the host. |
| check 5 fails | host-agent-absent (warning) | The host-repair endpoint cannot answer because the host agent has never written its inventory. The page then has no host-side data to render beside the version, and the combination reads as a broken page. Fix: Run the host agent's inventory job on the appliance and reload the page. This is expected on a non-appliance deployment, where there is no host agent at all and the update page is not the supported upgrade path. Verify: GET /admin/system-update/host-repair |
- The install ran and reported a failure → the previous version is already running again. Note the message the page showed and contact your CID222 contact with it.
- The bundle is rejected → only genuine, vendor-signed releases install. Re-obtain the bundle rather than retrying the same file.
Next steps
- Backup and restore — what the updater's own backups do and do not cover.
- Licensing and activation — capabilities follow the licence, not the release.
- Hardening checklist — re-check the operator settings after a major upgrade.
Last updated on