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
Thales is pleased to announce that Clusters, designed to reduce operation cost and maximize the return on investment of a fleet of HSMs, are fully supported for new production deployments and migration from Luna application partitions. 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.
NOTE Using Luna Appliance Software 7.9.0 or newer with lnh_cluster-1.0.5 or newer, you can configure the cluster in one of the following identity modes:
>Single-Identity Mode (default): In this mode, 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.
>Dual-Identity Mode: In this mode, the KRSO and KRCO roles on each keyring use separate passwords, and this separation is enforced using the same rules as standard Luna application partitions. This mode is required if you are migrating keys from standard Luna partitions to keyrings.
Consider this distinction before configuring your cluster; you may not switch from one mode to another without resetting the cluster to factory conditions. If you are using Luna Appliance Software 7.8.5 with lnh_cluster-1.0.4 or older, only single-identity mode is available.
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
TIP SCP is deprecated and SFTP is enabled by default for file transfer operations with Luna HSMs and clients. While you can continue using scp with Luna products, for the time being, eventually openSSL might discontinue scp support, and we recommend that you "future-proof" your operations by updating scripts and procedures to call sftp by preference.
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.
NOTE Each Luna Appliance Software package includes an optional firmware version that is ready to apply after installation. If you wish to install an older firmware version instead, you must first install the Luna Appliance Software package that includes your desired firmware version.
For example, if you have Luna Appliance Software 7.8.3 and Luna HSM Firmware 7.8.2 installed, and you want to use the latest FIPS-validated firmware version:
1.Install the secure package for
2.Update to Luna HSM Firmware 7.8.4.
3.Install the secure package for Luna Appliance Software 7.9.0, and do not update the firmware again.
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/ismigration, actionid: disable).
POST /api/lunasa/services/{serviceid}/actions/{actionid}
c.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 Luna 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 lnh_cluster and lnh_is_migration 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
TIP SCP is deprecated and SFTP is enabled by default for file transfer operations with Luna HSMs and clients. While you can continue using scp with Luna products, for the time being, eventually openSSL might discontinue scp support, and we recommend that you "future-proof" your operations by updating scripts and procedures to call sftp by preference.
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 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
NOTE Any new LunaSH commands included in the update become available when you open a new LunaSH session.
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, 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.
NOTE Each Luna Appliance Software package includes an optional firmware version that is ready to apply after installation. If you wish to install an older firmware version instead, you must first install the Luna Appliance Software package that includes your desired firmware version.
For example, if you have Luna Appliance Software 7.8.3 and Luna HSM Firmware 7.8.2 installed, and you want to use the latest FIPS-validated firmware version:
1.Install the secure package for
2.Update to Luna HSM Firmware 7.8.4.
3.Install the secure package for Luna Appliance Software 7.9.0, and do not update the firmware again.
REST API
Prerequisites
>Stop all client applications during the update process.
To update a 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 Luna 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 label and its 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.
TIP SCP is deprecated and SFTP is enabled by default for file transfer operations with Luna HSMs and clients. While you can continue using scp with Luna products, for the time being, eventually openSSL might discontinue scp support, and we recommend that you "future-proof" your operations by updating scripts and procedures to call sftp by preference.
To update a 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 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
NOTE Any new LunaSH commands included in the update become available when you open a new LunaSH session.
6.Manually authorize the member by specifying the cluster partition label, its CO password/PED key, and the 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).
