Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Other › Upgrade Support Boundary

Upgrade Support Boundary

Status: PARTIAL. Forward migrate from an admitted tree exists; mixed-version, rollback, and downgrade are not certified.Audience: operators, documentation reviewers

This document is required because the completeness report cannot claim a complete Enterprise operator journey while upgrade remains PARTIAL.

Classifications (binding)

Scroll sideways to see the full table. Use the arrow keys when focused.

TopicClassificationNotes
MIXED_VERSION_SUPPORTNOT_VERIFIEDRunning Agents on a different Manager schema/API generation is not a certified topology
ROLLBACK_SUPPORTNOT_VERIFIED as a product rollbackRecovery = restore a dump taken before migrate, then run matching binaries. Not a one-command rollback
DOWNGRADE_SUPPORTNot supportedManager -migrate is forward-only
DATABASE_BACKWARD_COMPATIBILITYNot supportedNewer schema is not documented as readable by older Manager binaries
AGENT_MANAGER_COMPATIBILITYNOT_VERIFIEDHeartbeat and rule sync exist; no published compatibility matrix
In-product updater (zwallctl update / /api/v1/update-campaigns)NOT_SUPPORTED for productionImplemented; owner/truth: not a production upgrade path
Hosting profile transition APIsNOT_VERIFIED per version pairPreflight flags exist; use only when the admitted release documents the pair
Community source rebuild + -migrateSUPPORTED as the Community pathBackup first
Enterprise verified-release + --manager-database-onlySUPPORTED as the commercial directionPath prefixes remain inconsistent; not a production-readiness claim

What can safely be documented now

Community

  1. Backup with backup_db.sh (and verify helper).
  2. Rebuild Manager, Agent, zwallctl, eBPF objects, and web UI from the new source tag you intend to run.
  3. ./bin/manager -config <path> -preflight-migrate (validate pending plan, no apply).
  4. ./bin/manager -config <path> -migrate (forward-only apply, then exit).
  5. ./bin/manager -config <path> -check-schema.
  6. Restart Manager, then Agents.
  7. Verify /health/live, /health/ready, console login, Agent list (3-Agent cap still applies).

Community has no license cobra tree and no update-campaign commands.

Enterprise

  1. Backup database and license identity files and systemd credentials.
  2. Stage the new verified release (customer verifier zwall-release).
  3. Run database admission against the new bundle (scripts/setup.sh --manager-database-only or scripts/install-manager-database.sh) so -preflight-migrate, -migrate, and -check-schema run from the admitted Manager binary.
  4. Replace Manager/Agent/Hosting artifacts and units from that same admitted release. Do not mix binaries from two bundles.
  5. Restart units (Hosting: loader then Agent).
  6. Verify health, login, Agent list, Hosting observation or Virtualization attachment as applicable.

--allow-test-release is disposable non-production only.

Hosting in-place profile transition

Agent flags:

zwall-agent --hosting-upgrade-preflight --config PATH \
  --expected-agent-id N \
  --compatibility-manifest-sha256 DIGEST \
  --agent-artifact-sha256 DIGEST

prints UPGRADE_COMPATIBLE or a failure category.

Manager APIs POST/GET /api/v1/agents/:id/hosting-profile-transition and rollback exist. Treat the specific version pair as NOT_VERIFIED unless the admitted release documents it.

What is not a production upgrade path

  • zwallctl update apply, zwallctl upgrade, zwallctl update rollback
  • POST /api/v1/update-campaigns
  • Signing-key CLI used to feed that updater
  • Mixing Community source Manager with Enterprise Hosting Agent
  • Skipping database admission on Enterprise

Those commands may exist in the Enterprise cobra tree. They are inventoried so operators are not surprised; they are not the certified path.

Rollback boundary (truthful)

Scroll sideways to see the full table. Use the arrow keys when focused.

ActionSupported?
Restore a pre-migrate dump into an isolated DB and inspectSCRIPT_EXISTENCE_ONLY (see Backup; certified restore is unresolved)
Point a matching old Manager binary at a restored old schemaNOT_VERIFIED as a certified procedure; engineering has not published a rollback matrix
Run new Manager against old schema without migrateNOT_VERIFIED / likely fail -check-schema or runtime validate
Run old Manager against new schemaNOT_SUPPORTED (no backward compatibility claim)
Product “downgrade channel”Not supported
zwallctl update rollbackNOT_SUPPORTED for production (updater)

If admission fails before -migrate applies, keep the previous binaries. If -migrate has applied, the previous Manager binary is not documented as compatible with the new schema. Recovery is restore-from-backup plus binaries that match that dump, which is not a certified rollback product.

Compatibility notes that remain open

  • OS/kernel matrix
  • filesystem prefix (/etc/zcs vs /etc/zwall-manager vs /opt/zcs …)
  • certified upgrade compatibility matrix
  • Enterprise uninstall residue
  • PostgreSQL 15+ (Community README) vs PostgreSQL 16 observed on Enterprise gates — do not invent a single public PG major

Verification after upgrade (minimum)

  • GET /health/live → alive
  • GET /health/ready → ready with database ok
  • Admin login
  • GET /api/v1/agents (or zwallctl list-agents)
  • Virtualization: eBPF health if Enterprise dashboard endpoint is present
  • Hosting: loader + Agent active; hosting status; drops remain zero
  • Enterprise: zwallctl license status if licensed