Backup & Restore

Your Nefia operator state includes configuration, cryptographic keys, audit logs, and schedule definitions. Losing any of these can disrupt your fleet management or break your audit trail. Regular backups ensure you can recover quickly.

What Gets Backed Up

A Nefia backup archive contains:

nefia-backup-2026-02-24.tar.gz
├── manifest.json              # Integrity manifest with SHA-256 checksums
├── nefia.yaml                 # Configuration file
└── state/
    ├── audit/
    │   ├── 2026-02-22.jsonl   # Append-only audit logs (date-partitioned)
    │   ├── 2026-02-23.jsonl
    │   └── 2026-02-24.jsonl
    ├── sessions.json          # Session and connection state
    ├── schedules/
    │   ├── daily-sync.json    # Scheduled task definitions (.json / .yaml)
    │   └── weekly-report.yaml
    └── recordings/
        └── rec-2026-02-24.json  # Session recording metadata (JSON only)

Creating a Backup

Run nefia backup to create a compressed archive of your operator state:

nefia backup

Each backup archive includes a manifest.json as its first entry, containing the Nefia version, creation timestamp, and a SHA-256 checksum for every file. This enables integrity verification after transfer or storage.

Custom Output Path

Specify a destination path with --output:

nefia backup --output /mnt/backups/nefia-$(date +%Y%m%d).tar.gz

Verifying Backup Integrity

Use nefia backup verify to validate that all files in an archive match their recorded SHA-256 checksums:

nefia backup verify nefia-backup-2026-02-24.tar.gz

The command exits with code 0 when all files pass, or code 1 if any file fails or is missing from the archive. This makes it safe to use in scripts and CI pipelines.

Restoring from a Backup

Restore your operator state from a backup archive:

nefia restore ~/nefia-backup-2026-02-24.tar.gz

Dry Run

Preview what a restore would do without writing any files:

nefia restore --dry-run ~/nefia-backup-2026-02-24.tar.gz

Each file is marked as either new (does not exist on disk) or overwrite (will replace an existing file), along with its size. The --dry-run flag skips the confirmation prompt and writes nothing to disk.

Force Overwrite

By default, nefia restore prompts for confirmation before overwriting existing files. Use --force to skip the prompt and overwrite without asking:

nefia restore --force ~/nefia-backup-2026-02-24.tar.gz

This is useful in scripts or automated recovery workflows where interactive prompts are not possible.

Restore Behavior

Best Practices

Automate Backups with Scheduled Execution

Use Nefia's built-in scheduler to create daily backups automatically:

nefia schedule create \
  --name "config-backup" \
  --cron "0 3 * * *" \
  --playbook backup-operator.yaml \
  --target localhost

Verify After Transfer

Always verify backup integrity after copying to remote storage:

# Copy to remote storage
scp nefia-backup-2026-02-24.tar.gz backup-server:/backups/
 
# Verify on the remote host
ssh backup-server nefia backup verify /backups/nefia-backup-2026-02-24.tar.gz

Store Backups Off-Device

A backup stored on the same machine it protects is not a backup. Copy archives to cloud storage or an external drive.

Test Restores Periodically

Test by running a dry-run restore first, then a full restore on a non-production machine:

# Preview what would be restored
nefia restore --dry-run ~/nefia-backup-2026-02-24.tar.gz
 
# Perform the actual restore
nefia restore ~/nefia-backup-2026-02-24.tar.gz

Retention Strategy

MCP Tools

Backup and restore operations are available via MCP:

Related