pixop-appliance-update

Unified operator CLI for qualified Prime appliance releases: signed manifests that pin immutable LIVE and Prime transport (pixop/prime-transport) digests, optional host tool bundles bound to signed manifests, and coordinated staging/apply across both stacks via pixop-image-update.

Availability: Confirm on your appliance with command -v pixop-appliance-update and pixop-appliance-update --help. Operators do not type sudo; the CLI self-elevates when access to root-owned updater state requires it. The immutable Stage0 entrypoint is /opt/pixop/bootstrap/bin/pixop-appliance-update; qualified AMIs expose the command through the normal operator PATH.

What this tool updates (and what it does not)

Prefer pixop-appliance-update when Pixop publishes a coordinated qualified release (manifest + catalog). Use pixop-image-update only for advanced, per-component digest work when you understand Pulse allowlists and restart policy.

Signed releases (operator view)

Pixop publishes Ed25519-signed release manifests and a signed catalog index. Appliances verify signatures fail-closed before staging or apply: no valid trust key and envelope means no work.

When a remote catalog URL is configured, check, plan, and apply use the signed index for discovery and verify each manifest envelope (Ed25519 + SHA-256 hash from the index). Unsigned remote metadata is never trusted. When no URL is configured, discovery uses the local catalog directory only.

Manifests use schema pixop-appliance-release/v1. Each manifest includes min_appliance_version (AMI semver from bake metadata); plan and apply fail closed when the local appliance is older.

ECR digests in a manifest are checked against Pulse POST /v1/appliance/registry-credentials allowlists before apply and --download-only download paths (plan shows intended digests only; it does not call Pulse or ECR).

Offline or USB delivery: pixop-appliance-update plan <release> --manifest /path/to/signed.json.

Revocation registry (commissioned appliances)

Appliances with channel commissioning (catalog URL + channel marker) also require a signed revocation registry at <catalog>/revocations/index.json. For those systems, plan, apply, and --download-only (including offline --manifest) fail closed when the registry is missing, invalid, replayed, or lists the target release as revoked. check and status show registry metadata; rollback and internal boot-recover do not consult revocation (already-applied releases keep running until you roll back or replace the platform).

Run pixop-appliance-update doctor (read-only) to diagnose catalog URL wiring, trust key presence, remote signed index reachability, and revocation registry health on commissioned DEV/PROD channels.

Software update vs updater self-update

Two related but separate mechanisms share one CLI entrypoint:

updater-apply downloads a signed ZIP/metadata pair and invokes bootstrap updater-install (not a generic package manager). Use updater-apply … --download-only to verify and stage bytes without installing.

Stage0-only bootstrap commands (updater-recover, updater-install, updater-status) exist for recovery engineering; operators normally use the high-level updater-* commands above.

Commands

pixop-appliance-update check
pixop-appliance-update status
pixop-appliance-update history [--limit N] [--transaction ID] [--layer LAYER] [--json]
pixop-appliance-update doctor
pixop-appliance-update plan <release> [--download-only] [--manifest <path>]
pixop-appliance-update apply <release> [--download-only] [--manifest <path>]
pixop-appliance-update rollback
pixop-appliance-update updater-check
pixop-appliance-update updater-plan <package_id|latest>
pixop-appliance-update updater-apply <package_id|latest> [--download-only]

Apply order: stage host bundle (when present) and both images, then switch host pointer, then apply tsduck then live (host-first so restarts load new runners). download-only stages verified archives only (no current / env digest switch). Interrupted operations leave a durable journal under /var/lib/pixop-live/appliance-update/ (and related trees); resolve or roll back before retrying.

pixopctl pull and tsduckctl pull remain refused. Per-component rollback is still available with pixop-image-update rollback live|tsduck.

history (read-only)

Structured update timeline from append-only JSONL under:

Options:

Durable *.json journals in the same directories remain authoritative for recovery; JSONL is for operators and bounded export in support packs.

Host bundles

Manifests may include structured host_bundle metadata (id, archive_path, artifact_sha256, artifact_bytes, min_host_applier_version) pointing at an immutable ZIP on the same HTTPS catalog origin. Trust is manifest-bound: staged bundle.zip bytes and attestation must match the signed fields; apply re-verifies and does not fetch remotely (use download-only or the apply staging phase first). Merge uses the baked AMI baseline plus bundle overlay (host-only files from a prior bundle are dropped when omitted from the new ZIP; AMI files cannot be removed). Materializes releases/host-<id>, switches current, then applies transport/LIVE. rollback restores previous_host_release from the applied stamp when recorded.

Host bundle apply requires a host applier and versioned /opt/pixop layout on a qualified AMI recipe—confirm with pixop-appliance-update plan / -h on your instance, not from documentation alone.

Internal entrypoint (not customer workflow)

boot-recover performs early-boot offline composite journal recovery when systemd recovery units run. It is not a substitute for operator rollback or support-directed recovery during maintenance. Do not run it unless Pixop support directs you.

Platform refresh lifecycle

Plan periodic qualified platform refresh (new Marketplace AMI or delivered QCOW2) on a cadence that matches your change policy—many teams target roughly six months as a planning horizon, but Pixop does not guarantee a fixed cadence or that every hardware/OS combination stays qualified indefinitely. Between platform refreshes, use signed pixop-appliance-update (preferred) or digest-pinned pixop-image-update for software contained in qualified releases. Do not run unmanaged dnf upgrade on production guests; kernel, driver, and OS compatibility are validated only on published appliance images.

Related

• pixop-image-update — per-component digest operations
• Configuration change control — change classes and rollback
• Monitoring and health signals — update event JSONL in support context
• pixop-pack-logs / pixop-support-bundle — bounded update-ops export