Config Snapshots & Rollback

Nexus GSLB automatically saves a versioned snapshot of the full cluster configuration after every write mutation. You can browse the change timeline, inspect what changed, and restore any previous snapshot with one click.

Snapshots are stored in the rqlite datastore and so are replicated to all cluster nodes via Raft. The last 100 snapshots are retained; older ones are pruned automatically.

What is captured

Each snapshot contains the full configuration state at that moment:

Health check results (up/down state) are not included — those are dynamic and re-derived from live probes after a restore.

Trigger events

WebUI — Config History page

Navigate to Admin → History to see the full timeline.

• Timeline list — all snapshots newest-first, with event type, timestamp, and actor.
• Expand a row — click the chevron to view the full JSON snapshot content inline.
• Restore — click Restore, then Confirm. A pre-restore backup is saved automatically before the restore runs.
• Create checkpoint — click "Create checkpoint" and optionally add a description to save a named snapshot at any point.
• Delete — remove individual snapshots to reclaim storage.

API

List snapshots

curl https://nexus-api.example.com/api/v1/history?limit=20 \
  -H "Authorization: Bearer $GSLB_API_KEY" | jq .

Response (array, newest-first):

[
  {
    "id": "a1b2c3d4e5f6...",
    "createdAt": 1717862400,
    "createdBy": "user-id-abc",
    "triggerEvent": "member.created",
    "description": ""
  }
]

Get a snapshot (with full content)

curl https://nexus-api.example.com/api/v1/history/<id> \
  -H "Authorization: Bearer $GSLB_API_KEY" | jq .snapshot.pools

Restore a snapshot

curl -X POST https://nexus-api.example.com/api/v1/history/<id>/restore \
  -H "Authorization: Bearer $GSLB_API_KEY"
# 204 No Content on success

The restore is atomic — the entire configuration is replaced in a single SQLite transaction. A pre-restore snapshot is saved first so you can undo the restore if needed.

Create a manual checkpoint

curl -X POST https://nexus-api.example.com/api/v1/history \
  -H "Authorization: Bearer $GSLB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "before Q2 maintenance window"}'

Delete a snapshot

curl -X DELETE https://nexus-api.example.com/api/v1/history/<id> \
  -H "Authorization: Bearer $GSLB_API_KEY"

gslbctl

# List recent snapshots (newest first)
gslbctl history list [--limit 50]

# Show full content of a snapshot
gslbctl history show <id>

# Restore to a snapshot
gslbctl history restore <id>

# Create a named checkpoint
gslbctl history checkpoint --description "pre-deployment"

# Delete a snapshot
gslbctl history delete <id>

Example history list output:

  ID        TIME                    EVENT                     BY              DESCRIPTION
  ─────────────────────────────────────────────────────────────────────────────────────────
  a1b2c3d4  2026-06-08 14:22:05     member added              user@example    
  e5f6a7b8  2026-06-08 14:18:03     pool created              user@example    
  c9d0e1f2  2026-06-08 13:00:00     manual checkpoint         user@example    pre-deployment

Restore behaviour

1. A pre-restore snapshot is saved automatically before the restore begins.
2. All existing pools, members, services, health checks, geo rules, redirect rules, TXT records, TSIG keys, delegated domains, and non-system roles are deleted.
3. All records from the snapshot are inserted.
4. Users from the snapshot are restored (including hashed passwords).
5. The change is broadcast to all cluster nodes via NATS state sync.
6. Health check results are unaffected — probes continue running and results update naturally.

Note: Restoring a snapshot that references a pool ID that no longer exists in the DNS zone will not cause an error — the DNS resolver simply returns no results for that service until you re-create the required records.

Permissions

Default grants:

Related

• Deployment Gates — stage config changes behind a health-soak promote step (builds on config snapshots)
• Progressive Delivery Rollouts — every rollout start/rollback saves a snapshot
• RBAC — permission model and role management