Cluster Backup and Restore
These procedures allow you to back up the contents of a cluster to an encrypted file on the appliance, using REST API or LunaSH:
>Restoring a Cluster from Backup
NOTE Thales requires minimum Luna Appliance Software 7.8.5 with the lnh_cluster-1.0.4 package, Luna HSM Firmware 7.8.4, and Luna HSM Client 10.7.2 to use clusters in production environments, or minimum Luna Appliance Software 7.9.0 with the lnh_cluster-1.0.5 package, Luna HSM Firmware 7.8.4, and Luna HSM Client 10.8.0 to migrate keys from Luna application partitions.
Backing Up the Cluster SMK
The cluster uses Scalable Key Storage (SKS) to secure keyrings and objects. The cluster partition is a V1 application partition (see V0 and V1 Partitions) on the Luna Network HSM 7 that stores the cluster's SKS Master Key (SMK). The cluster SMK encrypts all keyrings and their objects in the cluster. In the highly unlikely event that the cluster SMK is lost from all members, the entire cluster is unrecoverable. Therefore, Thales recommends backing up the cluster SMK to a Luna Backup HSM as part of your general recovery plan. This procedure requires an initialized Luna Backup HSM connected to the member appliance (using LunaSH) or a Luna HSM Client computer (using LunaCM).
LunaSH
Use the following procedure to back up the cluster SMK to a Luna Backup HSM connected to a member appliance.
Prerequisites
>The Luna Backup HSM must be connected to a USB port on the Luna Network HSM 7 appliance.
>If you are backing up the cluster SMK on a multifactor quorum-authenticated HSM, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.
To back up the cluster SMK using LunaSH
1.Log in to LunaSH as admin, or a custom user with admin privileges.
2.[Optional] View the Luna Backup HSMs currently connected to the appliance and find the correct serial number.
lunash:> token backup list
3.If you have not already done so, initialize the backup HSM, specifying its serial number and a label.
lunash:> token backup init -label <backup_hsm_label> -serial <backup_hsm_SN>
You are prompted to set the backup HSM SO password and a cloning domain string.
4.Initiate the backup operation, specifying the cluster partition label, a label for the backup (either a new label or the label for an existing backup you wish to overwrite), and the Backup HSM serial number.
If you omit the -tokenpar option when creating a new backup, the backup is assigned a default name (<source_partition_name>_<YYYYMMDD>).
lunash:> partition backup -partition <cluster_partition_label> -serial <Backup_HSM_SN> [-tokenpar <target_label>]
You are prompted for the following credentials:
a.Crypto Officer password/PED key for the cluster partition
b.HSM SO password/PED key for the backup HSM (Luna Backup HSM 7 only)
c.New password/PED key for the backup partition
d.Domain string or PED key for the backup partition (must match the cluster partition domain)
The backup operation begins once you have completed the authentication process.
LunaCM
Use the following procedure to back up the cluster SMK to a Luna Backup HSM connected to a Luna HSM Client computer.
Prerequisites
>The cluster partition must be assigned to the Luna HSM Client (see Client-Partition Connections and Assigning or Revoking NTLS Client Access to a Partition).
NOTE The client initiating SMK backup/restore cannot be the same client used to send requests to the cluster. A separate Luna HSM Client must establish an NTLS or STC connection to the partition for this purpose.
>The Luna Backup HSM must be connected to a USB port on the Luna HSM Client computer, or connected to a remote backup server (see Configuring a Remote Backup Server) and appearing as a slot in LunaCM (lunacm:> slot list).
>If you are backing up the cluster SMK on a multifactor quorum-authenticated HSM, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.
To back up the cluster SMK using LunaCM
1.Launch LunaCM on the Luna HSM Client.
2.If you have not already done so, select the slot assigned to the backup HSM Admin partition and initialize the backup HSM, specifying a label and the method of authentication (password or multifactor quorum).
lunacm:> hsm init -label <label> [-initwithped | -initwithpwd]
You are prompted for the new HSM SO password and the HSM domain string (existing or new).
3. Select the slot assigned to the cluster partition and log in as Crypto Officer.
lunacm:> slot set -slot <slot_id>
lunacm:> role login -name co
4.Initiate the backup operation, specifying the slot number for the backup HSM, and the -smkonly option.
lunacm:> partition archive backup -slot <backup_hsm_slot> -smkonly
If you are using password authentication, you are prompted for the following credentials (unless you specified them in the partition archive backup options):
i.The HSM SO password for the backup HSM. This is required to create or access the backup partition in the Admin slot.
ii.The Crypto Officer password to set for the target partition on the backup HSM.
iii.The domain string for the backup partition. The domain must match the domain configured on the source
If you are using multifactor quorum authentication, you are prompted for the following PED keys:
i.The blue HSM SO PED key(s) for the backup HSM.
ii.You are prompted to initialize the backup Partition SO role by creating a new blue PED key or reusing an existing key. After you initialize the role, you are prompted to insert the key again to log in as Partition SO.
iii.The red Domain PED key(s). This must be the same PED key(s) used for the Luna Network HSM 7 partition, otherwise the backup will fail.
iv.The blue Partition SO PED key(s) for the backup partition, to log in again.
v.You are prompted to initialize the Crypto Officer role for the backup by creating a new black PED key or reusing an existing key. After you initialize the role, you are prompted to insert the key again to log in as Crypto Officer.
The backup begins once you have completed the authentication process.
Backing Up a Cluster
Use this procedure to back up the contents of a cluster to an encrypted file on the appliance using REST API or LunaSH. You can perform backups on demand or schedule periodic backups. This procedure does not restore the cluster SMK. Refer to Backing Up the Cluster SMK.
NOTE Ensure that the member you are using to back up the cluster is authorized at the time of backup; otherwise the backup will fail.
REST API
Prerequisites
>Backup and restore operations can only be done on the primary member of the cluster.
>The cluster service must be running on the appliance and the member must be authorized.
To back up a cluster manually
Back up the cluster by specifying its UUID, a filename for the backup file, and a password that will be required to restore from this backup.
NOTE Using the same filename as an existing backup will overwrite the existing file.
PUT /api/clusters/{clusterID}/backup
{
"action": "run",
"password": "backuppassword",
"filename": "myClusterBackup"
}
To schedule periodic backups
1.If you already have backups scheduled, and you wish to make changes, first disable the backup service.
PUT /api/clusters/{clusterID}/backup
{
"action": "disable"
}
2.Set the backup schedule by specifying a filename prefix that will be used to name all backup files ("filename"), the number of backups you would like to store before old backups are deleted ("total", valid range 1-15), and the time you want backup to occur ("time") in the format d:hh:mm (where d is a number representing the day of the week as follows: 0 == Sunday, 1 == Monday, 2 == Tuesday, etc).
The filename you specify may have a maximum length of 64 characters. The following characters are allowed:-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz
PUT /api/clusters/{clusterID}/backup
{
"action": "config",
"total": 5,
"time": "7:09:30",
"filename": "myClusterBackup"
}
3.Enable the backup service, specifying a password that will be required to restore from any of the scheduled backups.
PUT /api/clusters/{clusterID}/backup
{
"action": "enable",
"password": "backuppassword"
}
4.[Optional] Display the scheduled backup configuration.
PUT /api/clusters/{clusterID}/backup
{
"action": "show"
}
All backups are available on the appliance in the admin user's files. The scheduled backup configuration is not affected by rebooting the appliance or restarting the cluster service. However, you must restart the cluster service after changing the appliance time zone or after a daylight savings time change, or the new time will not be reflected in the backup schedule.
NOTE If you promote a new cluster member to primary, you must disable and re-enable scheduled backups. You do not need to re-configure the schedule.
LunaSH
Prerequisites
>Backup and restore operations can only be done on the primary member of the cluster.
>The cluster service must be running on the appliance and the member must be authorized.
>You must be logged in to LunaSH as admin to do backup/restore operations.
To back up a cluster manually
Back up the cluster by specifying its UUID, a filename for the backup file, and a password that will be required to restore from this backup.
NOTE Using the same filename as an existing backup will overwrite the existing file.
The filename you specify may have a maximum length of 64 characters. The following characters are allowed:
-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz
lunash:> cluster backup run -clusterid <string> -filename <filename> -backuppassword <password>
To schedule periodic backups
1.If you already have backups scheduled, and you wish to make changes, first disable the backup service.
lunash:> cluster backup disable
2.Set the backup schedule by specifying the cluster UUID (-clusterid), a filename prefix that will be used to name all backup files (-filename), the number of backups you would like to store before old backups are deleted (-number <1-15>), and the time you want backup to occur (-time) in the format d:hh:mm (where d is a number representing the day of the week as follows: 0 == Sunday, 1 == Monday, 2 == Tuesday, etc).
The filename you specify may have a maximum length of 64 characters. The following characters are allowed:-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz
lunash:> cluster backup config -clusterid <string> -filename <filename> -number <number> -time <string>
3.Enable the backup service, specifying a password that will be required to restore from any of the scheduled backups.
lunash:> cluster backup enable -backuppassword <password>
4.[Optional] Display the scheduled backup configuration.
lunash:> cluster backup show
All backups are available on the appliance in the admin user's files. To view them, use lunash:> my file list. The scheduled backup configuration is not affected by rebooting the appliance or restarting the cluster service. However, you must restart the cluster service after changing the appliance time zone or after a daylight savings time change, or the new time will not be reflected in the backup schedule.
NOTE If you promote a new cluster member to primary, you must disable and re-enable scheduled backups. You do not need to re-configure the schedule.
lunash:> cluster backup disable
lunash:> cluster backup enable -backuppassword <password>
Restoring the Cluster SMK
The cluster uses Scalable Key Storage (SKS) to secure keyrings and objects. The cluster partition is a V1 application partition (see V0 and V1 Partitions) on the Luna Network HSM 7 that stores the cluster's SKS Master Key (SMK). The cluster SMK encrypts all keyrings and their objects in the cluster. You must restore the cluster SMK before creating a new cluster, as a prerequisite for recreating the cluster from backup. It is not necessary to restore the cluster SMK on each member; the cluster SMK is replicated to each new member when it joins the cluster on the primary member. This procedure requires an initialized Luna Backup HSM connected to the member appliance (using LunaSH) or a Luna HSM Client computer (using LunaCM).
CAUTION! Do not restore an SMK to the cluster partition for an active cluster.
LunaSH
Use the following procedure to restore the cluster SMK from a Luna Backup HSM connected to a member appliance.
Prerequisites
>The Luna Backup HSM must be connected to a USB port on the Luna Network HSM 7 appliance.
>The partition must be ready to host a cluster (V1 partition type, initialized, partition policy 40: Require Per-Key Authorization Data set to 0; see Installing and Configuring the Cluster Package).
To restore the cluster SMK from backup
1.Log in to LunaSH as admin, or a custom user with admin privileges.
2.[Optional] View the Luna Backup HSMs currently connected to the appliance and find the correct serial number.
lunash:> token backup list
3.[Optional] View the backups currently available on the Backup HSM.
lunash:> token backup partition list -serial <Backup_HSM_serialnum>
4.Initiate the restore operation, specifying the cluster partition label, the backup label, the Backup HSM serial number, and the -add option.
lunash:> partition restore -partition <target_label> -tokenpar <backup_label> -serial <Backup_HSM_SN> -add
You are prompted for the following credentials:
a.Crypto Officer password/PED key for the backup
b.Crypto Officer password/PED key for the cluster partition
The restore operation begins once you have completed the authentication process. When it is complete, you can create a new cluster on the appliance (see Creating a Cluster).
LunaCM
Use the following procedure to restore the cluster SMK from a Luna Backup HSM connected to a Luna HSM Client computer.
Prerequisites
>The cluster partition must be assigned to the Luna HSM Client (see Client-Partition Connections and Assigning or Revoking NTLS Client Access to a Partition).
NOTE The client initiating SMK backup/restore cannot be the same client used to send requests to the cluster. A separate Luna HSM Client must establish an NTLS or STC connection to the partition for this purpose.
>The Luna Backup HSM must be connected to a USB port on the Luna HSM Client computer, or connected to a remote backup server (see Configuring a Remote Backup Server) and appearing as a slot in LunaCM (lunacm:> slot list).
>The partition must be ready to host a cluster (V1 partition type, initialized, partition policy 40: Require Per-Key Authorization Data set to 0; see Installing and Configuring the Cluster Package).
To restore the cluster SMK using LunaCM
1.Launch LunaCM on the Luna HSM Client.
2. Select the slot assigned to the target partition and log in as Crypto Officer.
lunacm:> slot set -slot <slot_id>
lunacm:> role login -name co
3.List the available backups on the backup HSM by specifying the backup HSM's slot number. You will require the backup partition label to perform the restore operation.
lunacm:> partition archive list -slot <backup_HSM_slot>
4.Initiate the restore operation, specifying the backup HSM slot number, the label of the backup partition containing the SMK, and the -smkonly option. Respond to the prompts to provide the required credentials, as detailed in the summary above.
lunacm:> partition archive restore -slot <backup_HSM_slot> -partition <backup_partition_label> -smkonly
You are prompted for the Crypto Officer credentials for the backup and target partitions. The restore operation begins once you have completed the authentication process.
Restoring a Cluster from Backup
Use this procedure to restore the primary cluster member from backup using REST API or LunaSH.
CAUTION! Restoring the cluster from backup is a service-disrupting operation; do not perform client operations on the cluster until the restore process is complete.
NOTE
>Keyrings can be restored to a different cluster than the one where they were created, as long as the new cluster uses the same cluster SMK. If the cluster SMK is destroyed and cannot be restored from backup, keyrings are unrecoverable.
>Using lnh_cluster-1.0.5 and newer, backups can be restored only to a cluster configured in the same identity mode as the backup (see Keyring Roles and Identity Modes). Attempts to restore a backup taken from a single-identity cluster to a dual-identity cluster, or vice-versa, will fail. If you have configured the cluster in dual-identity mode, it is therefore impossible to restore a backup made from an earlier lnh_cluster version.
>Using lnh_cluster-1.0.5 and newer, you may restore keyrings to a cluster configured in a different client assignment mode than the backup (see Client Assignment Modes). Client assignment information is not included in the backup file, so if you restore to a new or factory-reset cluster in manual assignment mode, you must assign keyrings to clients again. If you are restoring to a cluster that already has keyrings assigned to clients, those assignments are preserved when the keyrings are restored.
>
REST API
Prerequisites
>Backup and restore operations can only be done on the primary member of the cluster.
>The cluster service must be running on the appliance and the member must be authorized.
>Stop the cluster service on all non-primary members of the cluster before you begin the restore operation (serviceid: cluster, actionid: stop):
POST /api/lunasa/services/{serviceid}/actions/{actionid}
To restore a cluster from backup
1.Restore the cluster from backup by specifying the backup filename, the backup password, and the keyring type of restore operation.
{
"filename": "myBackupFile",
"password": "backuppassword",
"type": "keyring"
}
NOTE This operation takes longer for larger clusters.
2.[Optional] Check the status of the restore operation.
3.When the restore operation is complete, you may start the cluster service on each non-primary member, one at a time (serviceid: cluster, actionid: start). Wait until each member is authorized before starting the next member. The amount of time it takes for each member to be authorized may vary, depending on the size of the data restored.
POST /api/lunasa/services/{serviceid}/actions/{actionid}
Confirm that the member is authorized ("memberActive": true) before starting the next member:
GET /api/clusters/{clusterID}/members
4.If you are using Luna Appliance Software 7.8.5 with lnh_cluster-1.0.4 or older, restart the cluster service on the primary member (serviceid: cluster, actionid: restart). This step is no longer required using Luna Appliance Software 7.9.0 with lnh_cluster-1.0.5; refer to known issue LUNA-31648.
POST /api/lunasa/services/{serviceid}/actions/{actionid}
LunaSH
Prerequisites
>Backup and restore operations can only be done on the primary member of the cluster.
>The cluster service must be running on the appliance and the member must be authorized.
>You must be logged in to LunaSH as admin to do backup/restore operations.
>Stop the cluster service on all non-primary members of the cluster before you begin the restore operation:
lunash:> service stop cluster
To restore a cluster from backup
1.Restore the cluster from backup by specifying the backup filename, the backup password, and the keyring type of restore operation.
lunash:> cluster restore run -filename <filename> -type keyring -restorepassword <password>
NOTE This operation takes longer for larger clusters.
2.[Optional] Check the status of the restore operation.
lunash:> cluster restore show
3.When the restore operation is complete, you may start the cluster service on each non-primary member, one at a time. Wait until each member is authorized before starting the next member. The amount of time it takes for each member to be authorized may vary, depending on the size of the data restored.
lunash:> service start cluster
Confirm that the member is authorized (Authorized: True) before starting the next member:
lunash:> cluster member show
4.If you are using Luna Appliance Software 7.8.5 with lnh_cluster-1.0.4 or older, restart the cluster service on the primary member. This step is no longer required using Luna Appliance Software 7.9.0 with lnh_cluster-1.0.5; refer to known issue LUNA-31648.
lunash:> service restart cluster
