Skip to content

Backup and Migration

gitsync edited this page Nov 17, 2026 · 1 revision

Save the whole configuration of a ZNAS server in one encrypted file, and restore it on the same machine, on new hardware, or on the USB Appliance. It works in both directions: from an installed server to the appliance and back.

Backup & Migration card

The card is in Settings → General → Backup & Migration (admins only).

What the backup contains

Included Not included
All portal settings, schedules, alerts and notification channels Your data — it stays on the pools
Portal users, their roles, 2FA and API keys Login sessions (everyone signs in again)
The Linux accounts behind them, with the same uid/gid, and their SMB passwords Caches and local daemon logs
SMB shares, NFS exports, iSCSI targets, MergerFS, UPS settings The audit log (optional)
Encryption keys of your encrypted datasets
The pool list, Incus datastores, networks and profiles, and the VM / container list
Performance and capacity charts history (optional)
HTTPS certificates (optional) and the server name

Keeping the same uid/gid means file ownership and permissions on the pools stay correct after the move.

Export

Export dialog

  1. Click Export…
  2. Choose a password of at least 12 characters and confirm it.
  3. Choose the options: charts history (on by default), HTTPS certificates (on), audit log (off).
  4. Click Export. A file named znas-backup-<server>-<date>.znasbak downloads.

The file is encrypted with AES-256-GCM, using a key derived from your password (PBKDF2-SHA256, 600 000 rounds). Without the password the file cannot be opened, and nobody can recover it. It holds password hashes and the keys of your encrypted datasets, so store it like a password.

Import on a new server (or the appliance)

This is the usual migration path:

  1. On the old server, export the configuration.

  2. Shut the old server down and move the pool disks to the new machine. You don't need to export the pools first.

  3. Start the new server (or boot the USB appliance). On its first-start page, don't create an account: click Restore from a ZNAS backup instead.

    Restore from a ZNAS backup

  4. Choose the .znasbak file and enter its password. Nothing is changed yet: ZNAS shows the import plan.

    Import plan

    • ZFS pools: will import (disks found), present (already imported) or not found (disks not connected). Connect missing disks and click Check the disks again, or carry on: missing pools are skipped, and their shares and VMs come back once you import the pool later from Pools → Import ZFS Pool.
    • Account conflicts: a Linux account that already exists here with a different uid is skipped, never changed.
    • Missing features: optional features used on the old server that aren't installed here. Their settings are restored and start working once you install them.
    • VM & container networks: networks the old server used. Managed networks are recreated. For a bridge that doesn't exist here (for example br0 on the old host), choose the bridge to connect to (vmbr0 on the appliance).
    • Options: Import pools last used by the old server (zpool import -f; needed when the disks were moved without exporting the pools) and Rename this server to the old name, so shares and bookmarks keep working. After a rename your router may give the server a different IP address.
  5. Click Import and follow the progress. ZNAS restores the settings and accounts, then the SMB passwords. Next it imports the pools by their GUID, so pools with the same name can't be confused. Then it applies the shares and recovers the VMs and containers, which stay stopped so you can check them first.

  6. The portal restarts. Sign in with your migrated account: same user name, same password.

Import on a server that is already set up

Settings → General → Backup & Migration → Import… runs the same wizard. It replaces the settings and users of this server. Everyone is signed out when the import finishes.

Rolling back

Before an import, ZNAS saves a copy of the current settings. The Backup & Migration card then shows Roll back, which puts the portal settings and users back as they were and restarts the portal. Pools that were imported stay imported, and Linux accounts and VMs created by the import are kept. Only the portal configuration goes back.

Tips

  • Moving from an installed server to the appliance: install on the appliance the optional features you used (iSCSI, UPS…) from Optional Features, or let the plan tell you what's missing.
  • The Firewall configuration comes back but isn't switched on. Enable the Firewall from Requisites → Optional Features and choose Start from the restored configuration; the wizard asks which port replaces each one that isn't on this server. See Firewall.
  • VMs and containers need Virtualization on the new server. On the appliance it's always available. On an installed server, enable it first, then import (or import again).
  • Keep a recent export somewhere safe even if you don't plan to move: it's the quickest way to rebuild after losing the boot disk.

Clone this wiki locally