nx9-wg/docs/BACKUP_RESTORE.md

Backup and Disaster Recovery Guide

Architecture

nx9-wg uses SQLite VACUUM INTO for atomic, consistent online snapshots of the database while the service is live.

---

1. Creating a Backup

Via CLI

nx9-wg backup create --description "Routine weekly backup"

Via REST API

curl -X POST http://127.0.0.1:8080/api/v1/backups/create \
  -H "Authorization: Bearer nx9_<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Pre-maintenance backup"}'

---

2. Verifying a Backup

The verification process:

1. Validates minimum file size.
2. Checks the SQLite 3 magic header bytes (b"SQLite format 3\0").
3. Validates the SHA-256 cryptographic checksum against the manifest.

nx9-wg backup verify /var/lib/nx9-wg/backups/nx9-backup-20260816-120000.db

---

3. Restoring from a Backup

The restore workflow is designed with fail-safety:

1. Verifies the backup archive before performing any modifications.
2. Creates an automatic pre-restore safety snapshot (pre-restore-safety-TIMESTAMP.bak).
3. Closes open connection pools and replaces the database file.
4. Cleans stale WAL and SHM journal files.
5. Reopens the database and runs the Reconciliation Engine to bring kernel WireGuard and firewall state in sync with the restored database.

nx9-wg backup restore /var/lib/nx9-wg/backups/nx9-backup-20260816-120000.db