Search the docs

System Backup and Restore

Backup and recovery protect against the loss of the Anvil nodes. The backup command takes a point in time backup of metadata and system configuration. The Restore command restores the metadata and configuration from a backup.

If recovering from a disaster, re-install the Anvil nodes with the same version used to take the backup and then use the restore command.

It is only supported to run Restore from freshly installed Anvil nodes.

If restoring a system with Global File System shares, additional steps must be taken for recovery of those shares. Contact Hammerspace Support for assistance.

Restoring a system from backup is not supported when the system has an object-storage volume flagged as shared — a configuration used in Global File System deployments that replicate to another site. Recovery halts with the error recovery cannot be performed on systems with OSVs flagged 'shared'; exiting recovery process. Do not attempt backup-based recovery on a system that has a shared object-storage volume; contact Hammerspace Support to discuss options.
System Backup and Restore does NOT backup actual user data.

System Backup

To do a backup or restore operation, login to the command line as an admin user. The system-backup-config command enables a backup to be scheduled or taken immediately.

A backup from an Anvil cluster is stored in a unique sub-directory under the specified path using the directory naming of anvil-<UUID>.

Several versions of the backups are automatically stored in the destination directory. The backup directory name is date-time to ensure they are unique.

Each backup is a full backup and is independent of the other backups. A total of five backups are stored in one location. When the number of backups exceeds five, the system will periodically remove the oldest backup.

The following example provides the IP address of the storage node and the NFSv3 export path to back up to. The --now option takes the backup immediately.

Admin CLI

Command:

system-backup-config --ip 192.0.2.52 --path /backup --now

Expected output:

success

Creating a System Backup Schedule

The example below runs at 10 minutes past each hour.

Admin CLI
schedule-create --minute 10 --name backup-schedule

Creating a Scheduled Backup

Admin CLI

Command:

system-backup-config --ip 192.0.2.52 --path /backup --schedule-name backup-schedule

Expected output:

Export path:             /backup
IP:                      192.0.2.52/32
Schedule name:           backup-schedule
Schedule expression:     10 * * * *
Schedule description:    At 10 minutes past the hour. Timezone: UTC
ID:                      08267237-438d-4148-917d-7110b844edda

Checking the Backup Schedule

Admin CLI

Command:

system-backup-config --view

Expected output:

Export path:             /backup
IP:                      192.0.2.52/32
Schedule name:           backup-schedule
Schedule expression:     10 * * * *
Schedule description:    At 10 minutes past the hour. Timezone: UTC
ID:                      42c8fe6b-c276-43d9-a5f7-c6b63cab9ded

Changing or Removing a Schedule and/or Changing the Backup Location

This example changes the schedule from hourly to daily.

Admin CLI

Command:

system-backup-config --ip 192.0.2.52 --path /backup --schedule-name backup-schedule-daily

Expected output:

Export path:             /backup
IP:                      192.0.2.52/32
Schedule name:           backup-schedule-daily
Schedule expression:     59 23 * * *
Schedule description:    At 11:59 PM. Timezone: UTC
ID:                      84662115-c1fb-492c-8259-4d159f92f096

Listing System Backups

The system-backup-list command can be used to list available backups.

Admin CLI

Command:

system-backup-list --ip 192.0.2.52 --path /backup

Expected output:

total 1
Cluster UUID:            aeeadb7f-7258-41e3-aad9-bc57ec176769
Available Backups:
                         Name:                    20260922.133646Z
                         Time:                    Tue Sep 22 13:36:48 UTC 2026
                         Cluster name:            AEL640TQCSS160
                         Management IP:           192.0.2.10
                         Site name:               AEL640TQCSS160
                         Version:                 5.3.2-234
                         Size:                    3.6MB
If the path for the system-backup-list command does not contain any backups of the current system, then all backups that are in that location will be shown.

Restoring System from Backup

The backup-restore command restores the system configuration and metadata. It does not restore or modify any user data.

A metadata backup must be restored to the same Anvil configuration as where the backup was taken. For example, a backup of an HA Anvil configuration must be restored to a HA installation.

The duration of a restore operation depends on the size of the backup. Most configurations are restored within 30 minutes.

The following example provides the IP address of the storage node and the export path of the backup directory to restore from.

Admin CLI

Command:

system-backup-restore --ip 192.0.2.52 --path /backup

Expected output:

backup restore started
It is only supported to run a restore operation from a freshly installed system that has not yet been used.