Luna Cluster REST API Reference

GET /

Get a certificate from the cluster

This resource allows you to export one of three certificates: **>** The root CA certificate for the cluster **>** The certificate for the local cluster member **>** The gRPC certificate used to authenticate client communication with the cluster

GET /hsmserial

Get the HSM serial number

This resource allows you to retrieve the HSM serial number.

GET /api/ping

Ping the API

This resource allows you to check the client's connection to a member appliance.

PATCH /api/cluster/client/{clientID}

Assign or unassign keyrings to/from a registered client

This resource allows you to assign or unassign keyrings to/from a registered cluster client. > **NOTE:** Ensure that none of this client's applications are running operations on the keyring(s) you unassign. Client requests will be interrupted. lunash:> [cluster client assign](../../lunash/commands/cluster/cluster_client_assign.htm) lunash:> [cluster client unassign](../../lunash/commands/cluster/cluster_client_unassign.htm)

GET /api/cluster/config

Get the Luna Network HSM 7's cluster configuration

This resource allows you to retrieve information about the appliance's cluster configuration. lunash:> [cluster config show](../../lunash/commands/cluster/cluster_config_show.htm)

PUT /api/cluster/config

Configure the cluster on the Luna Network HSM 7

This resource allows you to set an IP address for the cluster **core** services, configure the identity or client assignment mode for the cluster, or route a specified type of network traffic (**admin** or **crypto**) through a specified network device. > **TIP:** Use [GET /api/lunasa/services/cluster](../../REST_API/latest/services_service_id_page_name.html) to ensure that the cluster service is in either the `not running` or `running` state before setting or changing the cluster configuration. Using this resource while the cluster service is `starting` or `stopping` can interrupt the operation and result in a `failed` state, requiring [POST /api/lunasa/services/cluster/actions/restart]( ../../REST_API/latest/services_service_id_actions_action_id_change_page_name.html). lunash:> [cluster config set](../../lunash/commands/cluster/cluster_config_set.htm)

GET /api/cluster/member/partitions

Get a list of partitions on the local HSM

This resource allows you to display a list of partitions created on the HSM, their UUIDs, and their status in relation to the cluster on the local Luna Network HSM 7 appliance. lunash:> [cluster member partition list](../../lunash/commands/cluster/cluster_member_partition_list.htm)

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

Select a V1 partition to store the cluster's SMK

Specify this partition to bind to the cluster on the Luna Network HSM 7 (see [The Cluster Partition](../../admin_cluster/clusters_keyrings.htm#clusterpar)). If you create a new cluster on this appliance, this partition's SMK will become the cluster SMK. If you join this appliance to an existing cluster, the cluster's encrypting SMK will be copied to this partition. To bind this partition to the cluster, it must be returned with `"clusterReady": true` in the output from [GET /api/cluster/member/partitions](#/Cluster/api_cluster_member_partition_list_local). lunash:> [cluster member partition select](../../lunash/commands/cluster/cluster_member_partition_select.htm)

GET /api/cluster/member/partitions/{partitionID}/objects

Get a list of objects on a Luna partition

Return a list of objects on a Luna partition by specifying its Crypto Officer credential. lunash:> [cluster member partition object list]( ../../lunash/commands/cluster/cluster_member_partition_object_list.htm)

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

Migrate objects from a Luna partition to a keyring

This resource allows you to select objects to migrate from an eligible Luna application partition to a Luna keyring. lunash:> [cluster member partition object assign]( ../../lunash/commands/cluster/cluster_member_partition_object_assign.htm)

GET /api/cluster/migration

Get the migration status

Return the status of the current Luna IS 6 cluster migration, including details about migrated partitions and objects. This resource is available only if the **ismigration** secure package is installed on the Luna Network HSM. lunash:> [cluster migration status](../../lunash/commands/cluster/cluster_migration_status.htm)

PUT /api/cluster/migration

Migrate partitions from Luna IS

This resource allows you to migrate keys from Luna IS partitions to Luna Network HSM. This resource is available only if the **ismigration** secure package is installed on the Luna Network HSM. lunash:> [cluster migration join](../../lunash/commands/cluster/cluster_migration_join.htm) lunash:> [cluster migration finish](../../lunash/commands/cluster/cluster_migration_finish.htm) lunash:> [cluster migration restore](../../lunash/commands/cluster/cluster_migration_restore.htm)

PATCH /api/cluster/migration

Import the Luna IS cloning domain

This resource allows you to import a Luna IS 6 domain PED key secret to the Luna Network HSM cluster partition (see [The Cluster Partition](../../admin_cluster/clusters_keyrings.htm#clusterpar)) for migration purposes. You require a local or remote Luna PED to import the PED key secret. Refer to [Multifactor Quorum Authentication](../../admin_hsm/PED_Auth/PED_Auth.htm). lunash:> [cluster migration importDomain](../../lunash/commands/cluster/cluster_migration_importdomain.htm)

GET /api/cluster/restore

Get the cluster restore status

This resource allows you to display the status of current and past restore operations. lunash:> [cluster restore show](../../lunash/commands/cluster/cluster_restore_show.htm)

PUT /api/cluster/restore

Restore a cluster from backup

This resource allows you to restore a cluster from backup. This resource does not restore the SMK used to encrypt the contents of the cluster. Refer to [Backing Up/Restoring the Partition SMK](../../admin_cluster/cluster_backup_restore.htm#backupSMK) for this procedure. 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. > **NOTES:** > > **>** Keyrings on the target cluster have their configuration (roles, passwords, lock status) restored to their backup state. Objects stored on keyrings are overwritten by their backup versions. Keyrings and objects that do not have a backup version are left unchanged by the restore operation. > > **>** Backups can be restored only to a cluster configured in the same identity mode as the backup (see [Keyring Roles and Identity Modes](../../admin_cluster/clusters_keyrings.htm#IdentityModes)). 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. > > **>** You may restore keyrings to a cluster configured in a different client assignment mode than the backup (see [Client Assignment Modes](../../admin_cluster/clusters_keyrings.htm#Assign)). 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. lunash:> [cluster restore run](../../lunash/commands/cluster/cluster_restore_run.htm)

POST /api/clusters

Create a cluster

This resource allows you to create a cluster on the Luna Network HSM appliance. Do not create more than one cluster. lunash:> [cluster create](../../lunash/commands/cluster/cluster_create.htm)

GET /api/clusters

Get the cluster label and UUID

This resource allows you to retrieve the label and UUID of a cluster on a Luna Network HSM. lunash:> [cluster list](../../lunash/commands/cluster/cluster_list.htm)

GET /api/clusters/{clusterID}

Get information about a cluster

This resource allows you to get information about a specified cluster. lunash:> [cluster show](../../lunash/commands/cluster/cluster_show.htm)

PUT /api/clusters/{clusterID}

Join a cluster

Join an existing cluster from a new member. Both appliances must be configured with the same identity mode (**single** or **dual**; see [Keyring Roles and Identity Modes](../../admin_cluster/clusters_keyrings.htm#IdentityModes)) and client assignment mode (**auto** or **manual**; see [Client Assignment Modes](../../admin_cluster/clusters_keyrings.htm#Assign)). > **NOTE:** This operation may take a few minutes, even though a success message is received right away. > **CAUTION:** If the join process is interrupted due to a network disruption, an incomplete join state can result. If this happens, contact [Thales Customer Support](https://supportportal.thalesgroup.com/csm) for recovery procedures. lunash:> [cluster join](../../lunash/commands/cluster/cluster_join.htm)

DELETE /api/clusters/{clusterID}

Delete the cluster

This resource allows you to delete a cluster on a Luna Network HSM. lunash:> [cluster delete](../../lunash/commands/cluster/cluster_delete.htm)

POST /api/clusters/{clusterID}/sign

Sign a Certificate Signing Request

This resource allows you to sign a Certificate Signing Request (CSR) using the cluster's Certificate Authority (CA).

GET /api/clusters/{clusterID}/backup

Get the cluster backup status

This resource allows you to monitor cluster backups on the appliance. lunash:> [cluster backup show](../../lunash/commands/cluster/cluster_backup_show.htm)

PUT /api/clusters/{clusterID}/backup

Back up the cluster or configure scheduled backups

This resource allows you to configure scheduled cluster backups on the appliance, or start a backup operation on demand. This resource does not back up the SMK used to encrypt the contents of the cluster. Refer to [Backing Up/Restoring the Partition SMK](../../admin_cluster/cluster_backup_restore.htm#backupSMK) for this procedure. 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. lunash:> [cluster backup run](../../lunash/commands/cluster/cluster_backup_run.htm) lunash:> [cluster backup config](../../lunash/commands/cluster/cluster_backup_config.htm) lunash:> [cluster backup enable](../../lunash/commands/cluster/cluster_backup_enable.htm) lunash:> [cluster backup disable](../../lunash/commands/cluster/cluster_backup_disable.htm) lunash:> [cluster backup show](../../lunash/commands/cluster/cluster_backup_show.htm)

GET /api/clusters/{clusterID}/clients

Get a list of registered clients

This resource allows you to get a list of clients registered to the cluster. lunash:> [cluster client list](../../lunash/commands/cluster/cluster_client_list.htm)

POST /api/clusters/{clusterID}/clients

Register a client

This resource allows you to register a client Certificate Signing Request (CSR) to the cluster. You can now specify a LunaSH username with **monitor** privileges to associate with a client. This can be the default **monitor** role, or a custom user with the **monitor** role assigned. The user account must already exist on the appliance. lunash:> [cluster client register](../../lunash/commands/cluster/cluster_client_register.htm)

GET /api/clusters/{clusterID}/clients/{clientID}

Get information about a client

This resource allows you to get information about a registered cluster client, including its name, certificate info, the number of keyrings assigned to it, and the keyring UUIDs. lunash:> [cluster client show](../../lunash/commands/cluster/cluster_client_show.htm)

DELETE /api/clusters/{clusterID}/clients/{clientID}

Deregister a client

This resource allows you to deregister a client from the specified cluster. lunash:> [cluster client deregister](../../lunash/commands/cluster/cluster_client_deregister.htm)

PATCH /api/clusters/{clusterID}/clients/{clientID}

Enable or disable certificate authentication for a client

This resource allows you to enable or disable certificate authentication for a client. If certificate authentication is disabled, this client must authenticate using a LunaSH password. Only the role associated with this client (*monitor* or a custom user with a *monitor* role) can enable or disable it; the BasicAuth authorization string provided must reflect the correct username and password. lunash:> [cluster client enable](../../lunash/commands/cluster/cluster_client_enable.htm) lunash:> [cluster client disable](../../lunash/commands/cluster/cluster_client_disable.htm)

GET /api/clusters/{clusterID}/groups

Get a list of affinity groups on the cluster

This resource allows you to get a list of affinity groups that have been created on the cluster. lunash:> [cluster group list](../../lunash/commands/cluster/cluster_group_list.htm)

PUT /api/clusters/{clusterID}/member/partitions/{partitionID}/migration

Begin or end migration of partition objects to keyrings

This command allows you to begin or end the process of migrating keys from Luna application partitions to Luna keyrings. lunash:> [cluster member partition migration begin]( ../../lunash/commands/cluster/cluster_member_partition_migration_begin.htm) lunash:> [cluster member partition migration end]( ../../lunash/commands/cluster/cluster_member_partition_migration_end.htm)

GET /api/clusters/{clusterID}/members

Get a list of members

This resource allows you to get a list of available members on the specified cluster, including important information about each member. lunash:> [cluster member list](../../lunash/commands/cluster/cluster_member_list.htm)

GET /api/clusters/{clusterID}/members/{memberID}

Get information about a member

This resource allows you to get information about the specified member. lunash:> [cluster member show](../../lunash/commands/cluster/cluster_member_show.htm)

PUT /api/clusters/{clusterID}/members/{memberID}

Authorize, promote, or move a member

This resource allows you to authorize a specified cluster member to create objects on the cluster's keyrings, promote it to be the primary member of the cluster, or move it to a different affinity group. lunash:> [cluster member authorize](../../lunash/commands/cluster/cluster_member_authorize.htm) lunash:> [cluster member config](../../lunash/commands/cluster/cluster_member_config.htm)

PATCH /api/clusters/{clusterID}/members/{memberID}

Remove the member from the cluster

Remove this member from its current cluster. This action must be performed on the local member and it is not possible to remove a non-local member from the cluster. If the member you want to remove is unreachable, see [Delete an unrecoverable member from the cluster](#tag/Clusters/operation/api_cluster_member_delete). lunash:> [cluster leave](../../lunash/commands/cluster/cluster_leave.htm)

DELETE /api/clusters/{clusterID}/members/{memberID}

Delete an unrecoverable member from the cluster

This operation must be run on one of the functioning members of the cluster. It removes references to the unrecoverable member from the other members. If the primary member is unrecoverable, removing it from the cluster allows one of the other members to be promoted to primary, and the cluster can regain Read-Write status. After running this command, you must factory reset the **cluster** service on the deleted member before attempting to rejoin the cluster: [POST /api/lunasa/services/cluster/actions/factoryReset]( ../latest/services_service_id_actions_action_id_change_page_name.html). lunash:> [cluster member delete](../../lunash/commands/cluster/cluster_member_delete.htm)

GET /api/clusters/{clusterID}/members/{memberID}/partitions

Get a list of partitions on the specified member HSM

This resource allows you to display a list of partitions created on the HSM, their UUIDs, and their status in relation to the cluster on the specified member. lunash:> [cluster member partition list](../../lunash/commands/cluster/cluster_member_partition_list.htm)

GET /api/keyrings

Get a list of all keyrings

This resource allows you to retrieve a list of the available keyrings in the specified cluster. lunash:> [keyring list](../../lunash/commands/keyring/keyring_list.htm)

POST /api/keyrings

Create keyrings

This resource allows you to create keyrings in a cluster. You can create up to 100 keyrings at a time. > **NOTE:** While the Keyring Security Officer (KRSO) and Keyring Crypto Officer (KRCO) roles are separate, they are intended to be held by the same individual and they must therefore use the same password. Consider this when setting your KRSO password. The KRCO password is what your applications will specify to access the keyring and create and use objects. Thales recommends that you always use the most secure password possible. **>** If the KRCO password is 16 characters or shorter, the keyring is locked after 10 failed login attempts and must be unlocked before it can be used again: [PATCH /api/keyrings/{keyringid}](#tag/Keyrings/operation/api_keyring_enable_disable_unlock_reset). **>** If the KRCO password is 17 characters or longer, the lockout counter is not incremented. Failed login attempts using 6 characters or less never increment the counter. lunash:> [keyring create](../../lunash/commands/keyring/keyring_create.htm)

GET /api/keyrings/{keyringID}

Get information about a keyring

This resource allows you to get information about a specified keyring. lunash:> [keyring show](../../lunash/commands/keyring/keyring_show.htm)

PATCH /api/keyrings/{keyringID}

Enable, disable, unlock, or reset a keyring

This resource allows you to enable or disable a keyring, reset a keyring to its initial created state, or unlock a keyring that has been locked due to reaching the consecutive failed login limit. > **NOTE:** While the Keyring Security Officer (KRSO) and Keyring Crypto Officer (KRCO) roles are separate, they are intended to be held by the same individual and they must therefore use the same password. Consider this when setting your KRSO password. The KRCO password is what your applications will specify to access the keyring and create and use objects. Thales recommends that you always use the most secure password possible. **>** If the KRCO password is 16 characters or shorter, the keyring is locked after 10 failed login attempts and must be unlocked before it can be used again: [PATCH /api/keyrings/{keyringid}](#tag/Keyrings/operation/api_keyring_enable_disable_unlock_reset). **>** If the KRCO password is 17 characters or longer, the lockout counter is not incremented. Failed login attempts using 6 characters or less never increment the counter. lunash:> [keyring enable](../../lunash/commands/keyring/keyring_enable.htm) lunash:> [keyring disable](../../lunash/commands/keyring/keyring_disable.htm) lunash:> [keyring reset](../../lunash/commands/keyring/keyring_reset.htm) lunash:> [keyring unlock](../../lunash/commands/keyring/keyring_unlock.htm)

DELETE /api/keyrings/{keyringID}

Delete a keyring

This resource allows you to delete the specified keyring. lunash:> [keyring delete](../../lunash/commands/keyring/keyring_delete.htm)