Recovery Manager: Difference between revisions

From OSNEXUS Online Documentation Site
Jump to navigation Jump to search
← Older editNewer edit →
VisualWikitext
m Re-fit screenshot widths to half the captured size (capped at 800px) so 2x captures display at their true on-screen size (wiki-docs rule 5)
m osn-seo-utilities: docs-configuration-bundle-cli-commands-config-bundl @ 3f9985de5db9 (approved in the portal)
Line 1: Line 1:
[[Category:admin_guide]]
[[Category:admin_guide]]


The '''Recovery Manager''' restores the QuantaStor internal configuration database ({{Code|1=osn.db}}) from a backup. Use it when a system has been re-installed and you need the previous configuration back -- Storage Volumes, Network Shares, Users, Hosts, Schedules and the other logical objects.
The '''Recovery Manager''' creates, downloads, uploads and restores '''configuration bundles'''. A configuration bundle is a single {{Code|1=.tgz}} file holding a Storage System's internal configuration database ({{Code|1=osn.db}}) together with the configuration files around it: encryption keys, NFS and SMB settings, Ceph keyrings, network customizations, certificates, time settings and more. Use a bundle to bring a system back after its boot device is replaced or its OS is reinstalled, or to pass the identity and configuration of a retired server to the new server that replaces it.


{{Navigation|Storage Management → Storage Systems → ''select a Storage System'' → Recovery Manager ''(toolbar)''}}
{{Navigation|Storage Management → Storage Systems → ''select a Storage System'' → Recovery Manager ''(toolbar)''}}


It is also on the right-click context menu for a Storage System.
The Recovery Manager is also on the right-click menu of a Storage System. Every operation in it is also available from the command line.


[[File:ss_recovery_manager.png|thumb|right|637px|Recovery Manager, listing the configuration database backups discovered on the started Storage Pools.]]
{| class="wikitable"
! Section !! Purpose
|-
| [[#Configuration Bundles|Configuration Bundles]] || Generate, download, upload and delete bundles
|-
| [[#Restore Options|Restore Options]] || Choose which categories a restore writes, and what each one holds
|-
| [[#What happens during a restore|What happens during a restore]] || The checks, the pre-restore backup, the service restart and rollback
|-
| [[#Command line|Command line]] || The {{Code|1=qs config-bundle-*}} commands and a reinstall walk-through
|-
| [[#Cautions|Cautions]] || Node identity, network changes and maintenance windows
|-
| [[#Pool database backups|Pool database backups]] || The hourly database copies kept on each Storage Pool
|}


'''Scope note:''' the Recovery Manager currently recovers the {{Code|1=osn.db}} configuration database only. A full configuration download and recovery workflow covers considerably more than this, and is planned for a future release. Treat this page as covering the database recovery step, not configuration recovery as a whole.
'''Your data does not depend on a bundle.''' Storage Pools, and the volumes and shares within them, carry their own metadata and come back when the pool is imported. The configuration database holds the logical objects layered on top -- hosts, users, schedules, share and volume settings -- which is why a pool imported into a freshly installed system comes back with its volumes intact but without the objects that referenced them. A bundle restores those, plus the files the database does not hold, such as the encryption keys an encrypted pool needs to unlock.


'''Your data does not depend on this database.''' Storage Pools, and the volumes and shares within them, carry their own metadata and are recovered by importing the pool. The configuration database holds the logical objects layered on top, which is why a pool imported into a freshly installed system comes back with its volumes intact but without the hosts, schedules and users that referenced them.
'''Bundles are stored on the system's boot device''', in {{Code|1=/var/opt/osnexus/quantastor/configbundles}}. A bundle left there is lost with the boot device it is meant to recover from, so download every bundle you intend to keep and store it somewhere else. QuantaStor creates bundles only when you ask for one, so generate a new bundle after significant configuration changes.


'''In a Storage Grid this matters much less''', because the configuration database is replicated across all grid nodes; a node rejoining a grid picks the configuration up from its peers.
== Configuration Bundles ==


== Using the Recovery Manager ==
The '''Configuration Bundles''' tab works on one Storage System at a time. Choose it in the '''Storage System''' list; the list is preselected when you open the dialog from a Storage System's right-click menu. The table below it lists the bundles on that system, newest first:


# Select the '''Storage System''' to recover.
{| class="wikitable"
# Choose a backup from the list. Each row shows its name, file size and creation time.
! Column !! Shows
# Optionally tick '''Include network configuration recovery''' -- see the cautions below.
|-
# Press '''OK'''.
| Bundle || The bundle's file name.
|-
| Type || '''generated''' for a bundle you created, '''prerestore''' for the backup QuantaStor takes before every restore, '''legacy''' for a bundle from an older release that has no manifest, and '''invalid''' for a file that failed validation and cannot be restored.
|-
| Files || The number of configuration files in the bundle.
|-
| Size || The size of the bundle file.
|-
| Created || When the bundle was created.
|}


The list is built from backups found on the '''started''' Storage Pools, so if the backup you expect is missing, import and start the pool holding it first.
The buttons above the table act on the selected Storage System or on the bundle you tick in the table:


Backups are named by rotation slot -- {{Code|1=osn.db.backup.hourly.N}} and {{Code|1=osn.db.backup.daily.N}}. The count of each is set by {{Code|1=max_db_backups}} in {{Code|1=/opt/osnexus/quantastor/conf/quantastor.conf}} (default '''5'''; 0 disables pool backups). A backup failure raises a '''Configuration DB Backup Failure''' alert -- see [[Call-home / Alerting|Alert Manager]].
{| class="wikitable"
! Button !! What it does
|-
| Generate Bundle || Captures every category of the current configuration into a new bundle named {{Code|1=qs_config_bundle_YYYYMMDD-HHMMSS.tgz}}.
|-
| Restore || Restores the ticked bundle, using the categories selected on the '''Restore Options''' tab. A confirmation names the bundle and the system. See [[#What happens during a restore|What happens during a restore]].
|-
| Download || Saves the ticked bundle to your computer through the browser.
|-
| Delete || Deletes the ticked bundle from the system after a confirmation.
|-
| Refresh || Reloads the list.
|-
| Upload Bundle... || Uploads a bundle file from your computer to the selected system so that you can restore it. The bundle keeps its file name, with {{Code|1=-2}}, {{Code|1=-3}} and so on added if a bundle of that name is already there. A file whose name is not a bundle name is stored as {{Code|1=qs_config_bundle_YYYYMMDD-HHMMSS_imported.tgz}}.
|}
 
The dialog's own button is '''Close'''; nothing happens until you press one of the buttons on this tab.
 
Uploads and downloads are limited to '''100 MB''' per bundle. A bundle is validated when it is uploaded and again before it is restored: it must be a readable {{Code|1=.tgz}}, every file must match the checksum recorded in its manifest, and it may only contain files that a restore is allowed to write. Anything else in the file is refused, and a bundle that fails validation shows as '''invalid''' and cannot be restored.
 
'''A bundle holds secrets.''' It contains the configuration database and the encryption keys and salts of encrypted pools. Downloading a bundle therefore needs the same permission as modifying the Storage System, and you should store a downloaded bundle as carefully as the keys themselves.
 
== Restore Options ==
 
The '''Restore Options''' tab chooses which parts of the bundle a restore writes. Every category is ticked when the dialog opens, which restores everything the bundle holds. '''Select All''' and '''Clear All''' tick or clear the whole list; at least one category must be ticked to restore.
 
Restoring a subset is useful when only part of a system needs to go back -- for example the SMB configuration after a bad edit, or the encryption keys of a reinstalled node -- without replacing the rest of its configuration.
 
{| class="wikitable"
! Restore Options label !! CLI name !! What it captures and restores
|-
| Grid database (osn.db) || {{Code|1=database}} || The QuantaStor configuration database: the node's identity and its logical objects.
|-
| Encryption (crypttab, keys, salts) || {{Code|1=encryption}} || {{Code|1=/etc/crypttab}}, and the keys, salts and pool metadata of software- and SED-encrypted pools on ZFS and Ceph. LUKS header backups are left out to keep bundles small.
|-
| NFS exports and NFS-Ganesha || {{Code|1=nfs}} || Custom export rules in {{Code|1=/etc/exports.custom}}, and the NFS-Ganesha configuration used for CephFS and bucket shares.
|-
| SMB / Samba || {{Code|1=smb}} || {{Code|1=/etc/samba/smb.conf}} and {{Code|1=/etc/samba/smb.globals}}.
|-
| Kerberos / directory services || {{Code|1=directory}} || {{Code|1=/etc/krb5.conf}} and {{Code|1=/etc/krb5.default}}.
|-
| Ceph configuration and keyrings || {{Code|1=ceph}} || Everything in {{Code|1=/etc/ceph}}.
|-
| Static routes, port filters, proxy and firewall || {{Code|1=network}} || Per-port static routes, port filtering and lossless networking settings, proxy configuration and firewall rule customizations.
|-
| Multipath and udev rules || {{Code|1=storagedevices}} || {{Code|1=/etc/multipath.conf}} and the NVMe-oF udev rules.
|-
| SSL certificates and system use notice || {{Code|1=certificates}} || The QuantaStor SSL certificates and the system use notification text.
|-
| Load balancer (haproxy, nginx) || {{Code|1=loadbalancer}} || Custom files in {{Code|1=/etc/haproxy/conf.d}} and {{Code|1=/etc/nginx/conf.d}}.
|-
| Conf overrides, touch-files, alert filters, support and OEM files || {{Code|1=system}} || Override files in {{Code|1=/var/opt/osnexus/quantastor/conf}}, [[QuantaStor Touch Files|touch-files]], alert filters, support contact information and OEM branding files.
|-
| Time zone and NTP || {{Code|1=time}} || The time zone and the chrony or ntpd configuration.
|}
 
The full list of captured paths is in {{Code|1=/opt/osnexus/quantastor/conf/qs_config_exporter.conf}} on the appliance. A restore only ever writes paths that this file covers. Performance metrics (Telegraf and InfluxDB data) are not captured; they are far too large for a bundle.
 
If you request a category the bundle has nothing for -- encryption on a system without encrypted pools, for example -- that category is skipped and the restore carries on. A bundle taken on an older release stays restorable: files it holds that the current release no longer covers are skipped and logged rather than written.
 
'''Put lasting SMB global options in {{Code|1=smb.globals}}.''' QuantaStor rewrites {{Code|1=smb.conf}} from its database whenever a share changes, so hand edits to its {{Code|1=[global]}} section do not last. Options in {{Code|1=/etc/samba/smb.globals}} are appended to {{Code|1=[global]}} every time, and the bundle captures that file too.
 
== What happens during a restore ==
 
# '''Checks.''' The bundle is validated. If the database is being restored, it must pass an integrity check and must not belong to another member of the grid the system is in, because two grid nodes with the same ID break the grid. A restore is refused while an earlier one is still being applied.
# '''Pre-restore backup.''' QuantaStor generates a bundle of the complete current configuration, named {{Code|1=..._prerestore.tgz}}, before it changes anything. Restore that bundle to undo the restore.
# '''Files.''' The selected categories are written. Files that already match the bundle are left alone. The time service is restarted if its configuration changed.
# '''Database and service restart.''' The database is staged, and within about a minute the QuantaStor service stops, swaps in the restored database and starts again. The previous database is kept as {{Code|1=osn.db.prerestore}}. Reload the browser once the service is back.
# '''Result.''' A '''System Configuration Restore Completed''' alert confirms success. If the service does not come up on the restored database within ten minutes, or comes up on a different database, QuantaStor puts the previous database back, keeps the rejected one as {{Code|1=osn.db.failedrestore}} and raises '''System Configuration Restore Failed'''. The other configuration files stay restored in that case; restore the pre-restore bundle to undo them. See [[Call-home / Alerting|Alert Manager]] for alert delivery.
 
A reboot of the system is recommended once the restore completes, so that every restored setting takes effect.
 
When the database is restored, QuantaStor re-creates the Samba users from it. If the SMB category was restored too, the restored {{Code|1=smb.conf}} is kept rather than regenerated. If the network category was restored with the database, QuantaStor also reapplies the network configuration stored in the database -- see the cautions below.
 
== Command line ==
 
Six {{Code|1=qs}} commands drive the same operations as the dialog. Each takes an optional {{Code|1=--storage-system}} argument naming the system to act on, so you can manage the bundles of any grid member from one node; without it, the command acts on the system you are connected to.
 
{| class="wikitable"
! Command !! Short form !! Purpose
|-
| {{Code|1=qs config-bundle-generate [--categories=<list>]}} || {{Code|1=cb-generate}} || Create a bundle.
|-
| {{Code|1=qs config-bundle-list}} || {{Code|1=cb-list}} || List the bundles on a system.
|-
| {{Code|1=qs config-bundle-export --config-bundle=<bundle> [--output-file=<path>]}} || {{Code|1=cb-export}} || Download a bundle to a local file.
|-
| {{Code|1=qs config-bundle-import --input-file=<path>}} || {{Code|1=cb-import}} || Upload a local bundle file to a system.
|-
| {{Code|1=qs config-bundle-restore --config-bundle=<bundle> [--categories=<list>]}} || {{Code|1=cb-restore}} || Restore a bundle.
|-
| {{Code|1=qs config-bundle-delete --config-bundle=<bundle>}} || {{Code|1=cb-delete}} || Delete a bundle.
|}
 
{{Code|1=--config-bundle}} takes the bundle's file name or ID, as shown by {{Code|1=config-bundle-list}}. {{Code|1=config-bundle-export}} writes the file readable by your user only; without {{Code|1=--output-file}} it saves it under the bundle's own name in the current directory. {{Code|1=config-bundle-import}} reads the file on the machine where you run the command and uploads it.
 
{{Code|1=--categories}} takes the CLI names from the [[#Restore Options|Restore Options]] table, comma separated. Leave it out, or pass {{Code|1=all}}, for every category. A plain list selects only those categories; a name prefixed with {{Code|1=~}} leaves that category out of the full set:
 
<pre style="font-size: smaller">
qs config-bundle-restore --config-bundle=qs_config_bundle_20261102-091500.tgz --categories=encryption,smb
qs config-bundle-restore --config-bundle=qs_config_bundle_20261102-091500.tgz --categories=~network
</pre>
 
The first restores only the encryption keys and the SMB configuration; the second restores everything except the network files.
 
=== Recovering a reinstalled system ===
 
Generate and download a bundle while the system is healthy:
 
<pre style="font-size: smaller">
qs config-bundle-generate --storage-system=qs-node1
qs config-bundle-list --storage-system=qs-node1
qs config-bundle-export --storage-system=qs-node1 --config-bundle=qs_config_bundle_20261102-091500.tgz --output-file=/root/qs-node1-bundle.tgz
</pre>
 
Copy the file off the system. After the boot device is replaced and QuantaStor reinstalled, copy the file back to the system and restore it:
 
<pre style="font-size: smaller">
qs config-bundle-import --input-file=/root/qs-node1-bundle.tgz
qs config-bundle-list
qs config-bundle-restore --config-bundle=qs-node1-bundle.tgz
</pre>
 
The uploaded file's name is not a bundle name in this example, so {{Code|1=config-bundle-import}} stores it as {{Code|1=qs_config_bundle_YYYYMMDD-HHMMSS_imported.tgz}}; use the name {{Code|1=config-bundle-list}} shows. Watch for the '''System Configuration Restore Completed''' alert, then reboot.


== Cautions ==
== Cautions ==


'''Do not restore a backup taken from a different system.''' The database carries the system's unique ID, so this can leave two systems claiming the same UUID, which causes grid problems.
'''Restore a node's bundle only onto that node or onto the server replacing it.''' The database carries the node's unique ID. QuantaStor refuses a database that belongs to another member of the same grid, but it cannot see a retired server that is still running elsewhere -- power the old server off, or remove it from the grid, before its replacement takes over its identity.
 
'''Network configuration recovery can cut off your own session.''' If the restored network settings differ from the current ones, your connection drops when the address changes. Where ports may become unreachable, run the restore from the console, or untick the network category.
 
'''The restore replaces the running configuration and restarts the QuantaStor service.''' Schedule it as maintenance. If you are unsure which bundle is right, contact OSNEXUS support at support@osnexus.com before restoring rather than working through them by trial.


'''Network configuration recovery can cut off your own session.''' If the restored network settings differ from the current ones, your connection drops when the address changes. Where ports may become unreachable, make the change from the console rather than the web interface.
== Pool database backups ==


'''The restore replaces the running configuration.''' If you are unsure which backup is correct, contact OSNEXUS support at support@osnexus.com before restoring rather than working through them by trial.
[[File:ss_recovery_manager.png|thumb|right|637px|The Recovery Manager as it was in QuantaStor 6.9, when it restored the configuration database from these pool copies. Current releases list configuration bundles instead.]]


== Restoring by hand ==
Separately from configuration bundles, QuantaStor copies its configuration database to every online Storage Pool, keeping rotating hourly and daily copies in a {{Code|1=.qsbackups}} directory in the pool. The number of copies of each is set by {{Code|1=max_db_backups}} in {{Code|1=/opt/osnexus/quantastor/conf/quantastor.conf}} (default '''5''', maximum 100; 0 turns pool backups off). A backup failure raises a '''Configuration DB Backup Failure''' alert.


The database is a SQLite file and can be replaced directly if the dialog is not available -- for example on a system whose web interface will not start:
These copies hold the database only, not the encryption keys or other files a bundle carries, and the Recovery Manager does not list them. They are a last resort for a system that has no bundle. To use one, stop the service, move the live database and its {{Code|1=-wal}} and {{Code|1=-shm}} files aside, copy the backup into place and start the service:


<pre style="font-size: smaller">
<pre style="font-size: smaller">
systemctl stop quantastor
systemctl stop quantastor
cp &lt;backup-file&gt; /var/opt/osnexus/quantastor/osn.db
cd /var/opt/osnexus/quantastor
mv osn.db osn.db.old; mv -f osn.db-wal osn.db-wal.old; mv -f osn.db-shm osn.db-shm.old
cp &lt;backup-file&gt; osn.db
systemctl start quantastor
systemctl start quantastor
</pre>
</pre>
We recommend contacting OSNEXUS support before restoring a database this way.


== Related pages ==
== Related pages ==


* [[Storage System]] -- system-level configuration and the Modify dialog
* [[Storage System]] -- system-level configuration and the Modify dialog
* [[Upgrade Manager]] -- includes a re-install / boot drive swap procedure that uses the Recovery Manager
* [[Upgrade Manager]] -- includes a re-install / boot drive swap procedure
* [[Call-home / Alerting|Alert Manager]] -- the Configuration DB Backup Failure alert
* [[Call-home / Alerting|Alert Manager]] -- restore and backup alerts
* [[Software Encryption]] -- encrypted pools, whose keys a bundle carries
* [[QuantaStor Touch Files]] -- the touch-files captured by the system category


----
----
<small>''Verified against QuantaStor 6.9.0.''</small>
<small>''Verified against QuantaStor 7.0.0.''</small>

Revision as of 18:45, 2 November 2026


The Recovery Manager creates, downloads, uploads and restores configuration bundles. A configuration bundle is a single .tgz file holding a Storage System's internal configuration database (osn.db) together with the configuration files around it: encryption keys, NFS and SMB settings, Ceph keyrings, network customizations, certificates, time settings and more. Use a bundle to bring a system back after its boot device is replaced or its OS is reinstalled, or to pass the identity and configuration of a retired server to the new server that replaces it.

Navigation: Storage Management → Storage Systems → select a Storage System → Recovery Manager (toolbar)

The Recovery Manager is also on the right-click menu of a Storage System. Every operation in it is also available from the command line.

Section Purpose
Configuration Bundles Generate, download, upload and delete bundles
Restore Options Choose which categories a restore writes, and what each one holds
What happens during a restore The checks, the pre-restore backup, the service restart and rollback
Command line The qs config-bundle-* commands and a reinstall walk-through
Cautions Node identity, network changes and maintenance windows
Pool database backups The hourly database copies kept on each Storage Pool

Your data does not depend on a bundle. Storage Pools, and the volumes and shares within them, carry their own metadata and come back when the pool is imported. The configuration database holds the logical objects layered on top -- hosts, users, schedules, share and volume settings -- which is why a pool imported into a freshly installed system comes back with its volumes intact but without the objects that referenced them. A bundle restores those, plus the files the database does not hold, such as the encryption keys an encrypted pool needs to unlock.

Bundles are stored on the system's boot device, in /var/opt/osnexus/quantastor/configbundles. A bundle left there is lost with the boot device it is meant to recover from, so download every bundle you intend to keep and store it somewhere else. QuantaStor creates bundles only when you ask for one, so generate a new bundle after significant configuration changes.

Configuration Bundles

The Configuration Bundles tab works on one Storage System at a time. Choose it in the Storage System list; the list is preselected when you open the dialog from a Storage System's right-click menu. The table below it lists the bundles on that system, newest first:

Column Shows
Bundle The bundle's file name.
Type generated for a bundle you created, prerestore for the backup QuantaStor takes before every restore, legacy for a bundle from an older release that has no manifest, and invalid for a file that failed validation and cannot be restored.
Files The number of configuration files in the bundle.
Size The size of the bundle file.
Created When the bundle was created.

The buttons above the table act on the selected Storage System or on the bundle you tick in the table:

Button What it does
Generate Bundle Captures every category of the current configuration into a new bundle named qs_config_bundle_YYYYMMDD-HHMMSS.tgz.
Restore Restores the ticked bundle, using the categories selected on the Restore Options tab. A confirmation names the bundle and the system. See What happens during a restore.
Download Saves the ticked bundle to your computer through the browser.
Delete Deletes the ticked bundle from the system after a confirmation.
Refresh Reloads the list.
Upload Bundle... Uploads a bundle file from your computer to the selected system so that you can restore it. The bundle keeps its file name, with -2, -3 and so on added if a bundle of that name is already there. A file whose name is not a bundle name is stored as qs_config_bundle_YYYYMMDD-HHMMSS_imported.tgz.

The dialog's own button is Close; nothing happens until you press one of the buttons on this tab.

Uploads and downloads are limited to 100 MB per bundle. A bundle is validated when it is uploaded and again before it is restored: it must be a readable .tgz, every file must match the checksum recorded in its manifest, and it may only contain files that a restore is allowed to write. Anything else in the file is refused, and a bundle that fails validation shows as invalid and cannot be restored.

A bundle holds secrets. It contains the configuration database and the encryption keys and salts of encrypted pools. Downloading a bundle therefore needs the same permission as modifying the Storage System, and you should store a downloaded bundle as carefully as the keys themselves.

Restore Options

The Restore Options tab chooses which parts of the bundle a restore writes. Every category is ticked when the dialog opens, which restores everything the bundle holds. Select All and Clear All tick or clear the whole list; at least one category must be ticked to restore.

Restoring a subset is useful when only part of a system needs to go back -- for example the SMB configuration after a bad edit, or the encryption keys of a reinstalled node -- without replacing the rest of its configuration.

Restore Options label CLI name What it captures and restores
Grid database (osn.db) database The QuantaStor configuration database: the node's identity and its logical objects.
Encryption (crypttab, keys, salts) encryption /etc/crypttab, and the keys, salts and pool metadata of software- and SED-encrypted pools on ZFS and Ceph. LUKS header backups are left out to keep bundles small.
NFS exports and NFS-Ganesha nfs Custom export rules in /etc/exports.custom, and the NFS-Ganesha configuration used for CephFS and bucket shares.
SMB / Samba smb /etc/samba/smb.conf and /etc/samba/smb.globals.
Kerberos / directory services directory /etc/krb5.conf and /etc/krb5.default.
Ceph configuration and keyrings ceph Everything in /etc/ceph.
Static routes, port filters, proxy and firewall network Per-port static routes, port filtering and lossless networking settings, proxy configuration and firewall rule customizations.
Multipath and udev rules storagedevices /etc/multipath.conf and the NVMe-oF udev rules.
SSL certificates and system use notice certificates The QuantaStor SSL certificates and the system use notification text.
Load balancer (haproxy, nginx) loadbalancer Custom files in /etc/haproxy/conf.d and /etc/nginx/conf.d.
Conf overrides, touch-files, alert filters, support and OEM files system Override files in /var/opt/osnexus/quantastor/conf, touch-files, alert filters, support contact information and OEM branding files.
Time zone and NTP time The time zone and the chrony or ntpd configuration.

The full list of captured paths is in /opt/osnexus/quantastor/conf/qs_config_exporter.conf on the appliance. A restore only ever writes paths that this file covers. Performance metrics (Telegraf and InfluxDB data) are not captured; they are far too large for a bundle.

If you request a category the bundle has nothing for -- encryption on a system without encrypted pools, for example -- that category is skipped and the restore carries on. A bundle taken on an older release stays restorable: files it holds that the current release no longer covers are skipped and logged rather than written.

Put lasting SMB global options in smb.globals. QuantaStor rewrites smb.conf from its database whenever a share changes, so hand edits to its [global] section do not last. Options in /etc/samba/smb.globals are appended to [global] every time, and the bundle captures that file too.

What happens during a restore

  1. Checks. The bundle is validated. If the database is being restored, it must pass an integrity check and must not belong to another member of the grid the system is in, because two grid nodes with the same ID break the grid. A restore is refused while an earlier one is still being applied.
  2. Pre-restore backup. QuantaStor generates a bundle of the complete current configuration, named ..._prerestore.tgz, before it changes anything. Restore that bundle to undo the restore.
  3. Files. The selected categories are written. Files that already match the bundle are left alone. The time service is restarted if its configuration changed.
  4. Database and service restart. The database is staged, and within about a minute the QuantaStor service stops, swaps in the restored database and starts again. The previous database is kept as osn.db.prerestore. Reload the browser once the service is back.
  5. Result. A System Configuration Restore Completed alert confirms success. If the service does not come up on the restored database within ten minutes, or comes up on a different database, QuantaStor puts the previous database back, keeps the rejected one as osn.db.failedrestore and raises System Configuration Restore Failed. The other configuration files stay restored in that case; restore the pre-restore bundle to undo them. See Alert Manager for alert delivery.

A reboot of the system is recommended once the restore completes, so that every restored setting takes effect.

When the database is restored, QuantaStor re-creates the Samba users from it. If the SMB category was restored too, the restored smb.conf is kept rather than regenerated. If the network category was restored with the database, QuantaStor also reapplies the network configuration stored in the database -- see the cautions below.

Command line

Six qs commands drive the same operations as the dialog. Each takes an optional --storage-system argument naming the system to act on, so you can manage the bundles of any grid member from one node; without it, the command acts on the system you are connected to.

Command Short form Purpose
qs config-bundle-generate [--categories=<list>] cb-generate Create a bundle.
qs config-bundle-list cb-list List the bundles on a system.
qs config-bundle-export --config-bundle=<bundle> [--output-file=<path>] cb-export Download a bundle to a local file.
qs config-bundle-import --input-file=<path> cb-import Upload a local bundle file to a system.
qs config-bundle-restore --config-bundle=<bundle> [--categories=<list>] cb-restore Restore a bundle.
qs config-bundle-delete --config-bundle=<bundle> cb-delete Delete a bundle.

--config-bundle takes the bundle's file name or ID, as shown by config-bundle-list. config-bundle-export writes the file readable by your user only; without --output-file it saves it under the bundle's own name in the current directory. config-bundle-import reads the file on the machine where you run the command and uploads it.

--categories takes the CLI names from the Restore Options table, comma separated. Leave it out, or pass all, for every category. A plain list selects only those categories; a name prefixed with ~ leaves that category out of the full set: 

qs config-bundle-restore --config-bundle=qs_config_bundle_20261102-091500.tgz --categories=encryption,smb
qs config-bundle-restore --config-bundle=qs_config_bundle_20261102-091500.tgz --categories=~network

The first restores only the encryption keys and the SMB configuration; the second restores everything except the network files.

Recovering a reinstalled system

Generate and download a bundle while the system is healthy: 

qs config-bundle-generate --storage-system=qs-node1
qs config-bundle-list --storage-system=qs-node1
qs config-bundle-export --storage-system=qs-node1 --config-bundle=qs_config_bundle_20261102-091500.tgz --output-file=/root/qs-node1-bundle.tgz

Copy the file off the system. After the boot device is replaced and QuantaStor reinstalled, copy the file back to the system and restore it: 

qs config-bundle-import --input-file=/root/qs-node1-bundle.tgz
qs config-bundle-list
qs config-bundle-restore --config-bundle=qs-node1-bundle.tgz

The uploaded file's name is not a bundle name in this example, so config-bundle-import stores it as qs_config_bundle_YYYYMMDD-HHMMSS_imported.tgz; use the name config-bundle-list shows. Watch for the System Configuration Restore Completed alert, then reboot.

Cautions

Restore a node's bundle only onto that node or onto the server replacing it. The database carries the node's unique ID. QuantaStor refuses a database that belongs to another member of the same grid, but it cannot see a retired server that is still running elsewhere -- power the old server off, or remove it from the grid, before its replacement takes over its identity.

Network configuration recovery can cut off your own session. If the restored network settings differ from the current ones, your connection drops when the address changes. Where ports may become unreachable, run the restore from the console, or untick the network category.

The restore replaces the running configuration and restarts the QuantaStor service. Schedule it as maintenance. If you are unsure which bundle is right, contact OSNEXUS support at support@osnexus.com before restoring rather than working through them by trial.

Pool database backups

The Recovery Manager as it was in QuantaStor 6.9, when it restored the configuration database from these pool copies. Current releases list configuration bundles instead.

Separately from configuration bundles, QuantaStor copies its configuration database to every online Storage Pool, keeping rotating hourly and daily copies in a .qsbackups directory in the pool. The number of copies of each is set by max_db_backups in /opt/osnexus/quantastor/conf/quantastor.conf (default 5, maximum 100; 0 turns pool backups off). A backup failure raises a Configuration DB Backup Failure alert.

These copies hold the database only, not the encryption keys or other files a bundle carries, and the Recovery Manager does not list them. They are a last resort for a system that has no bundle. To use one, stop the service, move the live database and its -wal and -shm files aside, copy the backup into place and start the service: 

systemctl stop quantastor
cd /var/opt/osnexus/quantastor
mv osn.db osn.db.old; mv -f osn.db-wal osn.db-wal.old; mv -f osn.db-shm osn.db-shm.old
cp <backup-file> osn.db
systemctl start quantastor

We recommend contacting OSNEXUS support before restoring a database this way.

Related pages

Verified against QuantaStor 7.0.0.

Retrieved from "https://wiki.osnexus.com/index.php?title=Recovery_Manager&oldid=28349"