Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Operations › Backup

Backup

SharedStatus: SUPPORTED as “logical PostgreSQL dump scripts exist”. Not a certified recovery contract. No public RPO/RTO/SLA.Audience: Enterprise and Community administrators

Purpose

Create a restorable custom-format PostgreSQL dump of the Manager database, with checksum and metadata, plus (Enterprise) a separately protected copy of license identity files.

Prerequisites

  • pg_dump and psql on PATH (PostgreSQL client tools matching the server major version you run)
  • Network reachability to PostgreSQL
  • The five required DB_* environment variables
  • Disk space in BACKUP_DIR
  • For encryption: openssl

Required permissions: a PostgreSQL role that can dump DB_NAME. Root is not required for the dump itself. Reading systemd credentials or license private keys for the Enterprise file set requires privileged access.

Dependencies

Manager may keep running during a logical dump. The dump is not crash-consistent with in-flight Agent heartbeats. Do not treat it as a filesystem snapshot of /var/lib/zwall-manager.

Configuration

Dump configuration is environment, not Manager YAML. maintenance.backup_dir in Manager YAML is used by the unimplemented API backup handler path builder; it is not the backup_db.sh destination.

Match PGSSLMODE to database.ssl_mode (require in the Manager example; the script defaults PGSSLMODE to disable — set it explicitly).

Procedure — database dump

Do not put DB_PASSWORD on the command line.

export DB_HOST=127.0.0.1
export DB_PORT=5432
export DB_USER=zwall_user
export DB_NAME=zwall_centralized_security
export PGSSLMODE=require
export BACKUP_DIR=/var/backups/zwall
export BACKUP_LABEL=manual
# DB_PASSWORD from a prompt, systemd credential, or a root-only file — not argv

umask 0077
mkdir -p "$BACKUP_DIR"
chmod 700 "$BACKUP_DIR"

# from the admitted release or Community tree
./scripts/backup_db.sh

Optional encryption:

export BACKUP_ENCRYPTION_PASSPHRASE
./scripts/backup_db.sh

The script then writes .dump.enc and deletes the plaintext .dump.

Optional retention prune (deletes matching artifacts older than N days in BACKUP_DIR):

export BACKUP_RETENTION_DAYS=14

Procedure — verify the dump without touching production 

export VERIFY_DB_NAME="${DB_NAME}_restore_verify"
export VERIFY_KEEP_DB=0
./scripts/full_backup_and_verify.sh

This helper:

  1. Calls backup_db.sh
  2. Restores into VERIFY_DB_NAME with RESTORE_DROP_RECREATE=1
  3. Compares COUNT(*) for agents, admins, and rules

Keep VERIFY_DB_NAME distinct from the live Manager database.

Procedure — Enterprise identity files

Copy these as a set, with the same protection you use for private keys. Paths follow the known prefix inconsistency (more than one prefix appears in units and examples); copy what the host actually uses.

  • Deployment ID file
  • License certificate
  • Manager license identity key pair
  • Clock/lease auxiliary files if present
  • systemd credential files used by zwall-manager.service (not YAML passwords)

Expected result

backup_db.sh prints:

backup_file=<path>.dump
checksum_file=<path>.dump.sha256
metadata_file=<path>.meta

or .dump.enc when a passphrase was set.

Metadata includes created_at_utc, host/port/name/user, label, filenames, checksum_algorithm=sha256, encrypted=true|false, schema_version.

Verification

  1. Confirm the dump file exists and is non-empty.
  2. Confirm the .sha256 file matches (sha256sum -c or the restore script’s checksum step).
  3. Run full_backup_and_verify.sh against a verify database.
  4. Confirm Enterprise identity files were copied and are not world-readable.

Failure modes

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

SymptomMeaningAction
missing required environment variable: DB_*env not exportedexport all five
missing required command: pg_dumpclient tools absentinstall PostgreSQL client
pg_dump SSL/auth errorPGSSLMODE or role mismatchmatch Manager database.ssl_mode and role
empty or tiny dumpwrong DB_NAME or failed dump with set -e (should have exited)do not keep the artifact
passphrase set but no opensslscript exitsinstall OpenSSL or omit passphrase

Do not

  • Do not use zwallctl backup or POST /api/v1/maintenance/backup as the dump. That handler returns HTTP 200 "Database backup initiated" without calling pg_dump (TODO: Implement actual database backup logic in MaintenanceHandler.BackupDatabase).
  • Do not publish internal 15-minute RPO / 30-minute RTO figures as customer SLAs.
  • Do not treat streaming replication as a restore artifact.
  • Do not store dump files or passphrases in tickets, chat, or world-readable directories.

Security considerations

  • PGPASSWORD is exported by the script for the dump process lifetime.
  • Encrypted dumps still need the passphrase stored separately from the file.
  • Dumps contain administrator rows, Agent metadata, rules, and security-log history. Treat them as confidential.

Limitations

  • Logical dump only; no WAL/PITR contract.
  • Schema version in .meta is best-effort.
  • Not a certified whole-product recovery.
  • Community and Enterprise share the scripts; license files apply to Enterprise.
  • Certified restore/DR is unresolved. Do not treat this dump as an SLA.
  • Restore procedure details are provided separately to Enterprise customers.
  • Database maintenance
  • License identity files must be copied with the dump on licensed Managers. License operations are provided separately to Enterprise customers.