Updating the Cluster
Use these instructions to perform software/firmware/package updates on all members of a cluster.
>Checking the Installed Version
>Updating a Multi-Member Cluster
>Updating a Single-Member Cluster
With the latest release, Thales is pleased to announce that Clusters are fully supported for new production deployments, designed to reduce operation cost and maximize the return on investment of a fleet of HSMs. This release does not provide a migration path from standard Luna partitions or Luna Cloud HSM services to keyrings. 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.
NOTE Unlike the PSO and CO roles on standard Luna partitions, the KRSO and KRCO roles on each keyring are intended to be held by the same individual, and use the same password. When the password for one role is changed, the change is applied to the other role as well. Consider this distinction when planning your cluster deployment and setting your KRSO passwords.
CAUTION! DO NOT INSTALL THE CLUSTER PACKAGE ON A LUNA NETWORK HSM WITH PARTITIONS ALREADY IN PRODUCTION
When the lnh_cluster package is installed, access to any existing partitions on the HSM is disabled, and this can only be reversed by re-imaging the Luna Network HSM 7 appliance (see Re-Imaging the Appliance to Baseline Software/Firmware Versions). Re-imaging is a destructive action; all roles, partitions, and keys are destroyed. The Luna Network HSM 7 must be completely reconfigured; all partitions must be recreated and their contents restored from backup. In particular, do not attempt to configure clustering on a Luna Network HSM 7 that already has V1 partitions created; either delete these partitions or re-image the appliance before configuring a cluster.
Checking the Installed Version
There are three methods of checking which version of the lnh_cluster package is installed on the Luna Network HSM 7.
Get Cluster Member Information
The installed lnh_cluster version is included in the output of the following LunaSH and REST API commands. These commands can be run on any member in the cluster, but you must specify the UUID for the member you want information for:
>GET /api/clusters/{clusterID}/members/{memberID}
>lunash:> cluster member show
Check List of Installed Packages on the Luna Network HSM 7
The installed lnh_cluster version can be found in the list of installed packages in the format cluster_service-#.#.#-#####.x86_64:
>lunash:> package list
Search supportInfo.txt File
The installed lnh_cluster version can be found in the supportInfo.txt file generated by the following LunaSH and REST API commands:
>POST /api/lunasa/hsms/{hsmid}/supportInfo
>lunash:> hsm supportInfo
Transfer the file to a client computer using pscp/scp or another secure method, and search for the string cluster_service:
grep cluster_service supportInfo.txt
Updating a Multi-Member Cluster
The following procedure will allow you to update the appliance software, firmware, and lnh_cluster package on all members of a cluster, using REST API or LunaSH. The cluster can remain active during this procedure; client applications can keep running, except for during client update.
REST API
Prerequisites
>All cluster members must be functioning and visible to the primary member ("memberActive": true, "visibleToServicingNode": true, "restartService": false).
GET /api/clusters/{clusterID}/members
To update all members of an active cluster using REST API
1.Identify the primary cluster member ("primaryNode": true).
GET /api/clusters/{clusterID}/members
2.Choose one of the non-primary members to update.
a.Stop the cluster service on that member (serviceid: cluster, actionid: stop).
POST /api/lunasa/services/{serviceid}/actions/{actionid}
b.Disable the cluster service to prevent automatic restart during the update procedure (serviceid: cluster, actionid: disable).
POST /api/lunasa/services/{serviceid}/actions/{actionid}
c.Update the Luna Network HSM 7 appliance software. You must be updating from Luna Appliance Software 7.8.3 or newer to use REST API for this action.
If you are updating from an older appliance software version, refer to the LunaSH procedure (Updating the Luna Appliance Software).
d.If desired, update the Luna HSM firmware (actionid: upgrade).
POST /api/lunasa/hsms/{hsmid}/firmware/actions/{actionid}
e.Update the cluster package and restart the cluster service. You require Luna Appliance Software 7.8.3 or newer to use REST API for this action (version you updated to in step b above).
The member becomes active again.
f.You can now re-enable the cluster service (serviceid: cluster, actionid: enable).
POST /api/lunasa/services/{serviceid}/actions/{actionid}
Repeat step 2 for each non-primary member, one at a time.
3.Promote one of the updated members to primary.
Refer to Promoting a Member to Primary.
4.Repeat step 2 for the final (formerly primary) member.
5.[Optional] If you wish, promote the original primary member back to primary.
Refer to Promoting a Member to Primary.
6.Update the Luna HSM Client software.
Refer to Updating the Luna HSM Client Software.
After updating the client, you may restart applications from that client. Repeat for each additional client.
LunaSH
Prerequisites
>All cluster members must be functioning and visible to the primary member (not displayed in the list with an x or R).
lunash:> cluster member list
To update all members of an active cluster using LunaSH
1.Identify the primary cluster member.
lunash:> cluster member list
The primary member is displayed in the list with a P.
2.Choose one of the non-primary members to update. Log in to LunaSH on the appliance as admin.
a.Stop the cluster service.
lunash:> service stop cluster
b.Disable the cluster service to prevent automatic restart during the update procedure.
lunash:> cluster disable
c.Update the Luna Network HSM 7 appliance software.
Refer to Updating the Luna Appliance Software.
d.If desired, update the Luna HSM firmware.
Refer to Updating the Luna HSM Firmware.
e.Update the lnh_cluster package and restart the cluster service.
i.Transfer the secure package update file to the Luna Network HSM 7 using pscp or scp.
pscp <path>/lnh_cluster-1.0.#-###.spkg admin@<appliance_host/IP>:
ii.[Optional] Verify that the secure package file is present on the Luna Network HSM 7.
lunash:> package listfile
iii. [Optional] Verify the package file, specifying the authorization code you received from Thales.
lunash:> package verify <filename>.spkg -authcode <code_string>
iv.Install the lnh_cluster secure package.
lunash:> package update lnh_cluster-1.0.#-###.spkg -authcode <authcode_string>
v.Re-enable or start the cluster service. Enabling the service starts it automatically.
To enable the cluster service:
lunash:> cluster enable
To start the cluster service without enabling it:
lunash:> service start cluster
Repeat step e for each non-primary member, one at a time.
3.Promote one of the updated members to primary.
Refer to Promoting a Member to Primary.
4.Repeat step 2 for the final (formerly primary) member.
5.[Optional] If you wish, promote the original primary member back to primary.
Refer to Promoting a Member to Primary.
6.Stop your client applications and update the Luna HSM Client software.
Refer to Updating the Luna HSM Client Software.
After updating the client, you may restart applications from that client. Repeat for each additional client.
Updating a Single-Member Cluster
The following procedure will allow you to update the appliance software, firmware, and cluster package on a single-member cluster, using REST API or LunaSH. Since the cluster contains only one member, this will be a service-disrupting operation.
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.
REST API
Prerequisites
>Stop all client applications during the update process.
To update the single-member cluster using REST API
1.Stop the cluster service (serviceid: cluster, actionid: stop).
POST /api/lunasa/services/{serviceid}/actions/{actionid}
2.Disable the cluster service to prevent automatic restart during the update procedure (serviceid: cluster, actionid: disable).
POST /api/lunasa/services/{serviceid}/actions/{actionid}
3.Update the Luna Appliance Software. You must be updating from Luna Appliance Software 7.8.3 or newer to use REST API for this action.
If you are updating from an older appliance software version, refer to the LunaSH procedure (Updating the Luna Appliance Software).
4.If desired, update the Luna HSM firmware (actionid: upgrade).
POST /api/lunasa/hsms/{hsmid}/firmware/actions/{actionid}
5.Update the lnh_cluster package and restart the cluster service. You require Luna Appliance Software 7.8.3 or newer to use REST API for this action (version you updated to in step 3 above).
6.Manually authorize the member by specifying the cluster partition, and CO password (or "password": "" and present the CO PED key).
PUT /api/clusters/{clusterID}/members/{memberID}
{
"action": "authorize",
"authentication": [
{
"type": "CO",
"password": "IamtheCO",
"partitionLabel": "clusterpar"
}
]
}
7.You can now re-enable the cluster service (serviceid: cluster, actionid: enable).
POST /api/lunasa/services/{serviceid}/actions/{actionid}
8.Update the Luna HSM Client software.
Refer to Updating the Luna HSM Client Software.
After updating the client, you may restart applications from that client. Repeat for each additional client.
LunaSH
Prerequisites
>Stop all client applications during the update process.
To update the single-member cluster using REST API
1.Stop the cluster service.
lunash:> service stop cluster
2.Disable the cluster service to prevent automatic restart during the update procedure.
lunash:> cluster disable
3.Update the Luna Network HSM 7 appliance software.
Refer to Updating the Luna Appliance Software.
4.If desired, update the Luna HSM firmware.
Refer to Updating the Luna HSM Firmware.
5.Update the lnh_cluster package and restart the cluster service.
a.Transfer the secure package update file to the Luna Network HSM 7 using pscp or scp.
pscp <path>/lnh_cluster-1.0.#-###.spkg admin@<appliance_host/IP>:
b.Using a serial or SSH connection, log in to the appliance as admin (see Logging In to LunaSH).
c.Log in as HSM SO (see Logging In as HSM Security Officer).
lunash:> hsm login
d.[Optional] Verify that the secure package file is present on the Luna Network HSM 7.
lunash:> package listfile
e. [Optional] Verify the package file, specifying the authorization code you received from Thales.
lunash:> package verify <filename>.spkg -authcode <code_string>
f.Install the secure package for the cluster service.
lunash:> package update lnh_cluster-1.0.#-###.spkg -authcode <authcode_string>
g.Re-enable or start the cluster service. Enabling the service starts it automatically.
To enable the cluster service:
lunash:> cluster enable
To start the cluster service without enabling it:
lunash:> service start cluster
6.Manually authorize the member by specifying the application partition, CO password/PED key, and Member ID.
lunash:> cluster member authorize -partition <label> -memberid <string> [-copassword <password>]
7.Update the Luna HSM Client software.
Refer to Updating the Luna HSM Client Software.
After updating the client, you may restart applications from that client. Repeat for each additional client.
Troubleshooting
If you encounter any issues, refer to Reading System Logs to check recent activity on the appliance. To report an issue that is not described below, export the appliance syslog to a client workstation and provide it to your Thales representative (refer to Exporting System Logs).
