Installing and Configuring the Cluster Package

The following procedures will allow you to install the lnh_cluster secure package on the Luna Network HSM 7, and configure the appliance for a cluster, using REST API calls or LunaSH. This procedure must be completed whether you are creating a new cluster on this appliance (see Creating a Cluster), or joining it to an existing cluster (see Joining a New Member to an Existing Cluster).

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.

REST API

Prerequisites

>The Luna Network HSM 7 must be configured and accessible over the network. All members of a cluster must be able to communicate bi-directionally with all other members. Refer to Configuring IP and Network Parameters.

>If you are setting up a cluster on a multifactor quorum-authenticated HSM, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.

>If you plan to use REST API to work with clusters, set up the webserver service so that the appliance can accept calls from your web application.

Refer to Webserver Setup.

After configuring the webserver service, you must synchronize the HSM time with the time on the appliance.

lunash:> hsm time sync

>The Luna Network HSM 7 must be initialized.

PUT /api/lunasa/hsms/{hsmid}

>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.

Refer to:

•Updating the Luna Appliance Software

•Updating the Luna HSM Firmware

>The Luna Network HSM 7 and any clients must have NTP configured, or have their system clocks synchronized manually. Clocks must be synchronized before starting the cluster service:

•Using NTP (actionid: synchronize): POST /api/lunasa/ntp/actions/{actionid}

•Manually: PUT /api/lunasa/time

CAUTION! If the system clock is adjusted after the cluster certificate is created, the certificates might not be valid due to date/time. For example, if the certificate is generated while the system clock is ahead by a few minutes, and the clock is then corrected, the certificate will not be valid until the clock catches up to the time it was set to when the cert was created. If the current system time does not fall within the certificate's range of validity, the cluster service fails to start.

To configure the appliance for clustering

1.Open a session to the Luna REST API on the Luna Network HSM 7.

POST /auth/session

2.Create a new application partition to serve as the cluster partition (see The Cluster Partition).

a.Create a new application partition, specifying a V1 partition.

CAUTION!

>Using a V0 partition can cause undesired behavior and require you to factory reset the cluster service and recreate the partition.

>Do not select a partition that contains important key material as the cluster partition. Objects are not preserved after migration, and any existing NTLS connections to this partition are broken. Thales recommends creating a new partition for this purpose.

> If you intend to use single-identity mode (refer to Keyring Roles and Identity Modes; using lnh_cluster-1.0.4 or older, only single-identity mode is available), only one V1 partition can exist on the HSM; do not create more than one V1 partition. Dual-identity mode is recommended; it is required for migrating keys from standard Luna partitions to keyrings.

POST /api/lunasa/hsms/{hsmid}/partitions

b.Initialize the partition and the Partition Security Officer (PO) role.

NOTE The cluster partition on each member must use the same cloning domain. If you are configuring this appliance to join an existing cluster, ensure that you use the same domain string or PED key that was used to initialize the cluster partition on the primary member.

PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}

c.Log in with the new Partition SO credential, and set partition policy 40: Require Per-Key Authorization Data to 0. Confirm the policy change task (actionid: start).

i.POST /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/login

ii.PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/{policyid}

iii.POST /tasks/{taskid}/actions/{actionid}

CAUTION! Changing partition policies after you have created and are using clusters can cause unwanted behavior. Ensure that you have configured all your desired policy settings before you continue. This includes policies for Activation on Multifactor Quorum-Authenticated Partitions.

d.Initialize the Crypto Officer (CO) role (roleid: co). If necessary, change the initial CO credential.

i.PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid}

NOTE If HSM policy 21: Force user PIN change after set/reset is enabled (this is the default setting), the CO must change the password/PED key from its initial value before any other actions are permitted.

ii.PATCH /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid}

3.Install the lnh_cluster secure package on the Luna Network HSM 7.

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.Log in as HSM SO.

POST /api/lunasa/hsms/{hsmid}/login

c.[Optional] Verify that the secure package file is present on the Luna Network HSM 7.

GET /users/{userid}/files

d. [Optional] Verify the package file, specifying the authorization code you received from Thales.

POST /api/lunasa/packageFiles?VerifyOnly=true

GET /tasks/{taskid}/response

e.Install the lnh_cluster secure package.

POST /api/lunasa/packageFiles?VerifyOnly=false

4.Set the initial cluster configuration, including the following important settings:

•Authentication mode (specify single or dual, applies to lnh_cluster-1.0.5 or newer): Single or dual-identity mode (refer to Keyring Roles and Identity Modes for important information about these two choices; using lnh_cluster-1.0.4 or older, only single-identity mode is available). This setting must be consistent across all members of a cluster; a member configured in one mode is blocked from joining an existing cluster using the other.

•Client assignment mode (specify auto or manual): Automatic or manual client assignment mode (refer to Client Assignment Modes for important information about these two choices; using lnh_cluster-1.0.4 or older, only automatic mode is available). This setting must be consistent across all members of a cluster; a member configured in one mode is blocked from joining an existing cluster using the other.

•IP address to use for the core cluster traffic on this member. This must be the same IP address as one of the appliance's network interfaces.

NOTE The authentication mode and core IP address cannot be changed later, except after factory reset of the cluster service. Client assignment mode can be changed; refer to Changing Client Assignment Mode on the Cluster.

PUT /api/cluster/config

{
  "service": "core",
  "IpAddress": "127.0.0.1",
  "identity": "dual",
  "clientAssignment": "manual"
}

5.[Optional] Enable the cluster service on the appliance (serviceid: cluster). Enabling the service means that it will automatically restart in the case of an appliance reboot.

PATCH /api/lunasa/services/{serviceid}

{
  "onBoot": true
}

6.Start the cluster service on the appliance (serviceid: cluster, actionid: start).

POST /api/lunasa/services/{serviceid}/actions/{actionid}

NOTE The cluster service cannot be started if a user partition has not yet been created (refer to step 1).

7.Check the status of the cluster service ("onBoot": true and running). It may take several minutes for the cluster service to start, and the next step will fail if it is still starting up. This resource reports "status": "stopped" until the cluster service startup has finished.

GET /api/lunasa/services/{serviceid}

8.If you selected dual-identity authentication mode, select a V1 partition to serve as the cluster partition.

a.Get a list of eligible partitions on the HSM.

GET /api/cluster/member/partitions

Partitions that meet the requirements are returned with "clusterReady": true.

b.Select the cluster partition by specifying its UUID.

PUT /api/cluster/member/partitions/{partitionID}

NOTE Once you have selected a cluster partition, do not delete or otherwise manipulate the partition for any reason, without first selecting a different partition.

9.[Optional] You can also bind the administrative traffic to the cluster to a specified network device, including assigning a port number from a limited range (50075-50079).

PUT /api/cluster/config

{
  "service": "admin",
  "interface": "eth0",
  "port": 50075
}

10.[Optional] Check that the network configuration was set correctly.

GET /api/cluster/config

You can now create a new cluster on the appliance (see Creating a Cluster) or join a cluster on a different appliance (see Joining a New Member to an Existing Cluster).

LunaSH

Prerequisites

>If you are setting up a cluster on a multifactor quorum-authenticated HSM, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.

>The Luna Network HSM 7 must be initialized (see Initializing the HSM).

Refer to:

•Updating the Luna Appliance Software

•Updating the Luna HSM Firmware

•Updating the Luna HSM Client Software

>The Luna Network HSM 7 and any clients must have NTP configured, or have their system clocks synchronized manually. Clocks must be synchronized before starting the cluster service. Refer to Network Time Protocol on Luna Network HSM 7 or Setting the System Date and Time.

To configure the appliance for clustering

1.Create a new application partition to serve as the cluster partition (see The Cluster Partition).

a.Create a new application partition in LunaSH, specifying a V1 partition.

CAUTION!

>Using a V0 partition can cause undesired behavior and require you to factory reset the cluster service and recreate the partition.

Refer to Creating or Deleting an Application Partition.

b.Initialize the partition and the Partition Security Officer (PO) role in LunaSH, specifying the policy template filename.

Refer to Initializing an Application Partition.

c.Set partition policy 40: Require Per-Key Authorization Data to 0 (OFF).

Refer to Setting Partition Policies Manually.

d.Initialize the Crypto Officer (CO) role in LunaSH. If necessary, change the initial CO credential.

Refer to Initializing the Crypto Officer Role and Changing a Partition Role Credential.

2.Install the lnh_cluster secure package on the Luna Network HSM 7.

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>

The new cluster and keyring commands become available when you open a new LunaSH session.

3.Set the initial cluster configuration, including the following important settings:

•Identity mode (specify single or dual): Single or dual-identity mode (refer to Keyring Roles and Identity Modes for important information about these two choices; using lnh_cluster-1.0.4 or older, only single-identity mode is available). This setting must be consistent across all members of a cluster; a member configured in one mode is blocked from joining an existing cluster using the other.

•IP address to use for the core cluster traffic on this member. This must be the same IP address as one of the appliance's network interfaces.

NOTE The identity mode and core IP address cannot be changed later, except after factory reset of the cluster service. Client assignment mode can be changed; refer to Changing Client Assignment Mode on the Cluster.

Using lnh_cluster-1.0.5 or newer:

lunash:> cluster config set -service core -ipaddress <appliance_IP> -identity <mode> -clientAssignment <mode>

Using lnh_cluster-1.0.4 or older:

lunash:> cluster config -service core -ipaddress <appliance_IP>

4.If you want the service to restart automatically on appliance reboot, enable the cluster service on the appliance. Enabling the service will automatically start it. Otherwise, start the cluster service.

To enable the cluster service:

lunash:> cluster enable

To start the cluster service without enabling it:

lunash:> service start cluster

5.Check the status of the cluster service (enabled and/or running).

lunash:> cluster status

NOTE It can take up to 1-2 minutes for the cluster service to start. Until startup is complete, the status is reported as starting.

6.If you selected dual-identity authentication mode, select a V1 partition to serve as the cluster partition.

a.Display a list of eligible partitions on the HSM.

lunash:> cluster member partition list

Partitions that meet the requirements are displayed in the list with an R flag.

b.Select the cluster partition by specifying its UUID.

lunash:> cluster member partition select -partitionid <partition_UUID>

NOTE Once you have selected a cluster partition, do not delete or otherwise manipulate the partition for any reason, without first selecting a different partition.

7.[Optional] You can also bind the administrative traffic to the cluster to a specified network device, including assigning a port number from a limited range (50075-50079).

lunash:> cluster config -service admin [-interface <netdevice>] [-port <port>]

8.[Optional] Check that the network configuration was set correctly.

lunash:> cluster config show

You can now create a new cluster on the appliance (see Creating a Cluster) or join a cluster on a different appliance (see Joining a New Member to an Existing Cluster).



	SUPPORT	LEGAL
Luna Network HSM 7 Documentation © Copyright 2001-2025, Thales Group Last Updated: 2025-09-08 10:09:58 GMT-05:00	Customer Release Notes Customer Support Portal Support Contacts	End User License Agreement Third Party Software Licenses Document Information