SynVirt Updates v2 — ISO-based Appliance Updates

Synced read-only from /home/synnet/mirrors/synvirt-product/docs/superpowers/specs/updates-v2-iso-based.md. Edit at the source, not here.

SynVirt Updates v2 — ISO-based Appliance Updates

Goals

ISO-based, signed, transactional, rollbackable, offline-first. The same official installer ISO is used for install, update, repair, and recovery. No internet, no apt repos, no package channels.

Scope

Single edition. Features gated by license at runtime. The web installer chooses the install mode (standalone host / cluster node / update existing host / rescue) at first boot. The same ISO covers install, cluster install, update, repair, and recovery.

ISO Layout

/synvirt/manifest.json /synvirt/signature.sig /synvirt/packages/ /synvirt/rootfs/ /synvirt/migrations/ /synvirt/hooks/preflight.d/ /synvirt/hooks/postupdate.d/ /synvirt/release-notes.md /synvirt/compatibility.json

Manifest Schema

SynvirtIsoManifest { product: String, // “SynVirt” product_line: ProductLine, // SynVirt (single variant; reserved for future appliances) version: String, // “1.5.0” build: String, // “2026.06.10” min_supported_version: String, // “1.3.0” requires_reboot: bool, kernel: String, qemu: String, zfs: String, libvirt: String, synvirt_daemon: String, ui: String, update_mode: UpdateMode, // Transactional | SystemRebase | Repair }

Signature

ed25519 over manifest.json bytes. Public key embedded in synvirt-iso crate at keys/synvirt-release.pub. Private key lives in signing infrastructure, never in the repo.

ISO Library

Path: /var/lib/synvirt/isos/updates/ Owner: root:synvirt, mode 0750. Filename convention: synvirt--.iso

Update Flow

1. Upload or Mount ISO
2. Scan ISO (manifest + signature + compatibility)
3. Preflight Check (host health, ZFS, free space, VMs, backups)
4. Update Plan (component diff, release notes)
5. Checkpoint (ZFS boot environment clone)
6. Apply → Reboot → Post-verify

Update Modes

• standard: patch/minor (1.4.x → 1.5.x)
• system_rebase: major (1.x → 2.x), forces new BE
• repair: reinstall current version from ISO

Boot Environment Strategy

Pool: synvirt-root, dataset prefix synvirt-root/ROOT/. Pre-update snapshot: synvirt--preupdate-. Apply target: clone into synvirt-root/ROOT/synvirt-. Set bootfs to new BE before reboot. Default retention: 14 days, configurable.

API Surface (versioned /api/v1/)

POST /api/v1/isos/upload GET /api/v1/isos DELETE /api/v1/isos/:filename POST /api/v1/isos/:filename/scan POST /api/v1/isos/:filename/verify

POST /api/v1/system/update/select-iso POST /api/v1/system/update/preflight GET /api/v1/system/update/plan POST /api/v1/system/update/checkpoint POST /api/v1/system/update/apply POST /api/v1/system/update/reboot POST /api/v1/system/update/rollback GET /api/v1/system/update/status GET /api/v1/system/update/history GET /api/v1/system/update/logs (SSE)

CLI Surface

synvirt iso list | scan | verify | import | delete synvirt update select | preflight | plan | checkpoint | apply [–allow-downgrade] | status | rollback | history | logs –follow

Security

Signature verification mandatory. No UI override. Downgrade blocked unless CLI flag –allow-downgrade –recovery. All events written to /var/log/synvirt/update-audit.jsonl (JSONL, append-only).

Rollback

System-only by default. Never touches VM disks, datasets, backups, or user ISOs. Reboots into previous BE. Audit entry written.

State Machine

Idle → IsoSelected → Scanning → ScanOk → Preflight → PreflightOk → CheckpointReady → Applying → AwaitingReboot → Rebooting → PostVerify → Completed Failed branches at Scanning, Preflight, Applying, PostVerify. RollbackAvailable from Failed (post-Apply) and Completed.

License/Trial

ISO scan reads /etc/synvirt/license.toml. Trial expired blocks apply but allows repair mode.

Crate Layout

crates/synvirt-iso/ — manifest, signature, scanner, compatibility, library crates/synvirt-update/ — preflight, boot_env, transaction, migration, rollback, audit, post_verify crates/daemon/src/update_v2/ — orchestrator + state machine crates/daemon/src/api/isos.rs — /api/v1/isos crates/daemon/src/api/update_v2.rs — /api/v1/system/update crates/web-ux-v2/src/views/Updates/ — System Update view crates/web-ux-v2/src/views/Isos/ — already exists as IsoLibraryView; extend or refactor for update-ISO scope

Sidebar

“ISOs” already present (IsoLibraryView). “Updates” entry added under PLATFORM, between current ISOs entry and Backups (or at the end of PLATFORM if Backups not present yet).