Guides:Backing Up and Restoring QuantaStor Node Configuration with Configuration Bundles

From OSNEXUS Online Documentation Site
Jump to navigation Jump to search

By Steve Umbehocker, CTO, OSNexus · Updated November 2, 2026

A configuration bundle is a compressed archive of everything that makes a QuantaStor node that node: its internal configuration database, encryption keys, NFS and SMB settings, directory services, Ceph keyrings, network routes, certificates and system overrides. The Recovery Manager generates bundles on any node in the grid, downloads them to your workstation, uploads them to a reinstalled or replacement node, and restores them selectively by category. Every restore first takes a safety bundle of the current configuration, so a restore can itself be undone. This guide covers the routine "generate and download" habit, keeping bundles off the appliance, partial restores, and a worked reinstall-and-restore example using both the web interface and the CLI.

Why it matters

Your data does not live in the configuration database. Storage pools carry their own metadata and come back when you import the pool. What does not come back on its own is the layer on top: hosts and host groups, users, schedules, NFS and SMB settings, static routes, certificates and the encryption keys an encrypted pool needs before it can be imported.

QuantaStor already writes hourly and daily copies of the configuration database to every started storage pool, and the Recovery Manager page describes how those rotate. That protects you as long as a pool survives. It does not help when the boot device and the pools are both gone, or when the pool that would hold the backup is encrypted and its keys were on the failed boot drive. A bundle you downloaded last week and stored elsewhere covers exactly that case.

In a Storage Grid the database is replicated across nodes, so a node rejoining the grid picks most of its configuration up from its peers. The files outside the database (keys, SMB and NFS configuration, certificates, time and NTP settings) are still per-node, and a bundle is how you get them back.

Bundles complement site-level disaster recovery rather than replace it. Remote replication copies volumes and shares asynchronously to a second site so you can fail over when the primary site is lost. A configuration bundle protects the appliance itself, so a rebuilt node at either site comes back with its keys, shares, routes and certificates. A complete DR plan uses both.

How it works

A bundle is a .tgz with a manifest that records every file it holds with its checksum, owner and permissions. Each file belongs to one of twelve categories:

Category What it covers
database The QuantaStor grid configuration database
encryption Encryption configuration, keys, salts and pool metadata (software and SED)
nfs NFS exports and NFS-Ganesha configuration
smb Samba / SMB configuration
directory Kerberos and directory services configuration
ceph Ceph configuration and keyrings
network Static routes, network port, proxy and firewall configuration
storagedevices Multipath and udev rules
certificates SSL certificates and the system use notice
loadbalancer haproxy and nginx configuration
system Configuration overrides, touch files, alert filters, support and OEM files
time Time zone and NTP (chrony / ntpd) configuration

On restore, the bundle is validated before anything is written; a damaged or tampered archive is refused. QuantaStor then generates a _prerestore bundle of the node's current state, which appears in the list like any other bundle. It writes the selected categories back and restarts the QuantaStor service to apply them. A reboot afterwards is recommended. The node raises a System Configuration Restore Completed alert when it is done. If the service will not run on the restored database, the previous database is put back and a System Configuration Restore Failed alert is raised instead.

Two safety checks apply to the database category. A database whose identity belongs to another member of the same grid is refused, because two nodes claiming the same system ID cause grid problems. Restoring that bundle with the database category left out is allowed.

Design and sizing

  • Generate on a schedule you will actually keep. After any significant change (new shares, AD join, certificate replacement, network change) and before every upgrade is a good minimum.
  • Keep bundles off the node. A bundle stored only on the appliance is lost with its boot drive. Download each one and store it with your other infrastructure secrets.
  • Treat bundles as sensitive. A bundle with the encryption category contains the keys for encrypted pools. Store it with the same controls you use for key escrow. Bundles are never included in support log reports.
  • One bundle per node. Bundles are per storage system; in a grid, generate one for each node from the grid master by naming the node.
  • Storage cost is negligible. The configuration database is typically under 10 MB, and the other categories are plain configuration files.

Setting it up

From the web interface

Open Storage Management → Storage Systems, select the node and press Recovery Manager on the toolbar (it is also on the storage system's right-click menu). Pick the node in the Storage System list; the grid below shows that node's bundles with their name, type, file count, size and creation time.

The Configuration Bundles tab of the Recovery Manager: the Storage System picker selects the node, and the Generate Bundle, Restore, Download, Delete and Upload Bundle buttons sit above the bundle grid
  1. Press Generate Bundle to capture the current configuration. A new row appears.
  2. Select the row and press Download to save the .tgz to your workstation.
  3. On a reinstalled or replacement node, press Upload and choose the saved file. It appears with an _imported suffix.
  4. Select the bundle and press Restore. On the Restore Options tab all twelve categories are ticked by default; untick any you do not want restored. The confirmation names both the system and the bundle.
The Restore Options tab with all twelve categories ticked, from the grid database through time zone and NTP, plus Select All and Clear All for building a partial restore

From the CLI

The same operations are available as qs commands. Each also has a short form (cb-generate, cb-list, cb-export, cb-import, cb-restore, cb-delete), and --storage-system lets you work on another grid node from the master. Generate a bundle on node1, list it, download it to a local file for copying off-box, and delete old bundles you no longer need: 

qs config-bundle-generate --storage-system=node1
qs config-bundle-list --storage-system=node1
qs config-bundle-export --storage-system=node1 --config-bundle=<bundle-name> --output-file=/root/node1-config.tgz
qs config-bundle-delete --storage-system=node1 --config-bundle=<bundle-name>

--categories takes a comma-separated list. A plain list (database,smb) restores only those categories; a name prefixed with ~ leaves it out, so --categories=~smb means everything except SMB.

Operating and testing

Worked example: reinstall and restore

Suppose node1 (192.0.2.21) lost its boot mirror. Its pool, pool1, is encrypted and on intact data drives, and you downloaded a bundle last week.

  1. Reinstall QuantaStor on node1 following the boot-drive procedure in Upgrade Manager, and give it a management address from the console.
  2. Copy the saved bundle to the node and upload it:
   scp node1-config.tgz root@192.0.2.21:/root/
   qs config-bundle-import --input-file=/root/node1-config.tgz
   qs config-bundle-list
  1. Restore it. If the node's management address is unchanged, restore everything:
   qs config-bundle-restore --config-bundle=<imported-bundle-name>

If you have deliberately changed the network, leave that category out with --categories=~network, as described in the cautions below.

  1. Wait for the service restart and the System Configuration Restore Completed alert, then reboot.
  2. With the encryption keys back in place, import and start pool1. Its volumes and shares return with their pool, and the hosts, users and schedules that reference them come back from the restored database.

Partial restores

A restore does not have to be all or nothing. If SMB settings were changed deliberately since the bundle was taken, restore with --categories=~smb (or untick smb in the dialog). To put back only the time zone and NFS exports, use --categories=time,nfs; files in other categories are left untouched, although the service still restarts.

Cautions

  • Network restores can drop your session. If the restored network settings differ from the current ones, your connection drops when the address changes. Run network restores from the console. The same caution applies to the database-only recovery described on the Recovery Manager page.
  • Do not restore one node's database onto another node. A bundle is for the node it was taken from or that node's replacement.
  • Watch the alerts. Failed pool database backups raise a Configuration DB Backup Failure alert; route alerts to your team through Call-home / Alerting.

Testing

Test a restore on a lab node before you need one in production. Generate a bundle, change a share setting and the time zone, then restore with --categories=time and confirm only the time zone reverted. The _prerestore bundle created by that test is your rollback; restore it to return to where you started.

FAQ

What is the difference between a configuration bundle and the automatic database backups on pools?

The automatic backups cover only the configuration database and live on the storage pools themselves, so they are reachable only when a pool can be imported and started. A bundle also captures encryption keys, NFS, SMB, Ceph, network, certificate and time settings, and you can download it and keep it anywhere. Use both: the pool backups for quick rollbacks, bundles for losing the whole node.

Can I restore everything except one category?

Yes. In the dialog, untick that category on the Restore Options tab. On the CLI, prefix it with ~, for example --categories=~smb. If no category is left selected, the restore is refused.

What happens if a restore goes wrong?

Before writing anything, QuantaStor saves a _prerestore bundle of the current configuration, so you can restore that bundle to undo the change. If the service cannot start on the restored database, the previous database is put back automatically and a System Configuration Restore Failed alert is raised.

Do I need a bundle if the node is part of a grid?

The grid replicates the configuration database, so a rejoining node gets that part from its peers. Keys, SMB and NFS configuration, certificates and other per-node files are not replicated. A bundle per node is the reliable way to recover them.

Can I restore a bundle onto a newer QuantaStor release?

Yes for the database: the core service upgrades older database schemas to the current version automatically. Restore the bundle and let the service apply the schema upgrade on restart.

Part of the QuantaStor Guides series. For reference documentation, see the QuantaStor documentation.

Retrieved from "https://wiki.osnexus.com/index.php?title=Guides:Backing_Up_and_Restoring_QuantaStor_Node_Configuration_with_Configuration_Bundles&oldid=28354"