Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Upgrades › Community

Community

Community upgrades

CommunityStatus: SUPPORTED as source rebuild + forward migrate. Official Community binary publication remains deferred per Community install docs.Audience: Community operators

Purpose

Move a Community Manager/Agent install to a newer source revision without using Enterprise release admission or the in-product updater (Community has no update-campaign cobra commands).

Prerequisites

  • Working Community install (source install)
  • Go / Node / eBPF toolchain versions required by the new tree (README: Go 1.25+, Node 18+, PostgreSQL 15+ — note the version difference if you compare to Enterprise 16)
  • A dump from backup_db.sh
  • Maintenance window (migrate is not zero-downtime)

Required permissions: the account that builds binaries; PostgreSQL role for migrate; root to restart enforcement Agents.

Procedure

  1. Backup the database and keep the old bin/ and ebpf/ objects until verification succeeds.
export DB_HOST DB_PORT DB_USER DB_PASSWORD DB_NAME PGSSLMODE
./scripts/backup_db.sh
  1. Fetch and build the new Community source (same commands as install):
go build -o bin/manager ./cmd/manager
go build -o bin/agent ./cmd/agent
go build -o bin/zwallctl ./cmd/zwallctl
cd ebpf && make && cd ..
cd web && npm install && npm run build && cd ..
  1. Preflight (no apply):
./bin/manager -config /etc/zcs/manager.yml -preflight-migrate
  1. Migrate (forward-only, then exit):
./bin/manager -config /etc/zcs/manager.yml -migrate

-init-db is a deprecated alias; do not use it in new procedures.

  1. Check schema:
./bin/manager -config /etc/zcs/manager.yml -check-schema

  1. Restart Manager, then Agents (systemd if setup.sh installed units; otherwise your process supervisor). Enforcement Agents still require root.

  2. Replace eBPF objects on Agent hosts from the new ebpf/ build. Integrity flags (ebpf.verify_artifact_integrity) should stay true.

Verification

  • GET /health/live and /health/ready
  • Console /login
  • At most three Agents (COMMUNITY_AGENT_LIMIT_REACHED on a fourth)
  • zwallctl list-rules / list-agents against the real Manager URL (not the 8080 default if you listen on 8443)

Expected result

New binaries running, schema checksum accepted, previous admin and Agent rows present.

Failure modes

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

SymptomMeaningAction
preflight failspending plan rejecteddo not migrate; stay on old binaries
migrate applied, start failstreat as forward-onlyrestore dump; see Rollback
Agent offlinebinary/eBPF mismatch or URLAgent disconnected
Fourth Agentcapexpected

Do not

  • Do not run Enterprise setup.sh --manager-database-only against Community.
  • Do not document zwallctl update (absent on Community).
  • Do not skip backup.

Security considerations

  • Build as a non-root user; run Manager as the dedicated user if you have one.
  • Keep JWT/database passwords out of YAML in production even on Community (Community still requires JWT_SECRET / yaml secret in some setups — follow the Community example you actually deploy).

Rollback / recovery notes

There is no schema downgrade. If migrate applied and the new Manager is unusable, restore the pre-migrate dump and run the old binaries. That procedure is SCRIPT_EXISTENCE_ONLY for the dump and NOT_VERIFIED as a certified rollback product.