Menu
AWS CloudHSM
User Guide

Configure Tool

AWS CloudHSM automatically synchronizes data among all HSMs in a cluster. The Configure tool updates the HSM data in the configuration files that the synchronization mechanisms use. Use Configure to refresh the HSM data before you use the command line tools, especially when the HSMs in the cluster have changed.

Before using the key_mgmt_util tool, run configure -a. Before using the cloudhsm_mgmt_util tool, run configure -a and then run configure -m. You can also run configure --ssl to update SSL keys and certificates.

You can also use the Configure tool to update SSL keys and certificates.

Syntax

configure -h | --help configure -a <ENI IP address> configure -m [-i <daemon_id>] configure --ssl --pkey <private key file> --cert <certificate file>

Examples

These examples show how to use the Configure tool.

Example : Update the HSM Data for the AWS CloudHSM Client and key_mgmt_util

This example uses the configure -a command to update the HSM data for the AWS CloudHSM client and key_mgmt_util. This command is also the first step in updating the cloudhsm_mgmt_util configuration file.

Before running configure -a, stop the AWS CloudHSM client. This prevents conflicts that might occur while Configure edits the client's configuration file. If the client is already stopped, this command has no ill effects, so you can use it in a script.

$ sudo stop cloudhsm-client cloudhsm-client stop/waiting

Next, get the ENI IP address of any one of the HSMs in your cluster. This command uses the describe-clusters command in the AWS CLI, but you can also use the DescribeClusters operation or the Get-HSM2Cluster PowerShell cmdlet.

This excerpt of the output shows the ENI IP addresses of the HSMs in a sample cluster. We can use either of the IP addresses in the next command.

$ aws cloudhsmv2 describe-clusters { "Clusters": [ { ... } "Hsms": [ { ... "EniIp": "10.0.0.9", ... }, { ... "EniIp": "10.0.1.6", ...

This step uses configure -a to add the 10.0.0.9 ENI IP address to the configurations files.

The output shows that Configure added 10.0.0.9 to the cloudhsm_client.cfg and cloudhsm_mgmt_util.cfg files.

$ sudo /opt/cloudhsm/bin/configure -a 10.0.0.9 Updating server config in /opt/cloudhsm/etc/cloudhsm_client.cfg Updating server config in /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg

Next, restart the AWS CloudHSM client. When the client starts, it uses the ENI IP address in its configuration file to query the cluster. Then, it writes the ENI IP addresses of all HSMs in the cluster to the cluster.info file.

$ sudo start cloudhsm-client cloudhsm-client start/running, process 2747

When the command completes, the HSM data that the AWS CloudHSM client and key_mgmt_util use is complete and accurate. Before using cloudhsm_mgmt_util, run the configure -m command, as shown in the following example.

Example : Update the HSM Data for cloudhsm_mgmt_util

This example uses the configure -m command to copy the update the updated HSM data from the cluster.info file to the cloudhsm_mgmt_util.cfg file that cloudhsm_mgmt_util uses.

Before running configure -m, stop the AWS CloudHSM client, run configure -a, and then restart the AWS CloudHSM client, as shown in the previous example. This ensures that the data copied into the cloudhsm_mgmt_util.cfg file from the cluster.info file is complete and accurate.

$ sudo /opt/cloudhsm/bin/configure -m Updating '/opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg' from cluster state

Parameters

-h | --help

Displays command syntax.

Required: Yes

-a <ENI IP address>

Adds the specified HSM elastic network interface (ENI) IP address to AWS CloudHSM configuration files. Enter the ENI IP address of any one of the HSMs in the cluster. It does not matter which one you select.

To get the ENI IP addresses of the HSMs in your cluster, use the DescribeClusters operation, the describe-clusters AWS CLI command, or the Get-HSM2Cluster PowerShell cmdlet.

Note

Before running configure -a, stop the AWS CloudHSM client. Then, when configure -a completes, restart the AWS CloudHSM client. For details, see the examples.

This parameter edits the following configuration files:

  • /opt/cloudhsm/etc/cloudhsm_client.cfg: Used by AWS CloudHSM client and key_mgmt_util.

  • /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg: Used by cloudhsm_mgmt_util.

When the AWS CloudHSM client starts, it uses the ENI IP address in its configuration file to query the cluster and update the cluster.info file (/opt/cloudhsm/daemon/1/cluster.info) with the correct ENI IP addresses for all HSMs in the cluster.

Required: Yes

-m

Updates the HSM ENI IP addresses in the configuration file that cloudhsm_mgmt_util uses.

When you run configure -a and then start the AWS CloudHSM client, the client daemon queries the cluster and updates the cluster.info files with the correct HSM IP addresses for all HSMs in the cluster. Running configure -m completes the update by copying the HSM IP addresses from the cluster.info to the cloudhsm_mgmt_util.cfg configuration file that cloudhsm_mgmt_util uses.

Be sure to run configure -a and restart the AWS CloudHSM client before running configure -m. This ensures that the data copied into cloudhsm_mgmt_util.cfg from cluster.info is complete and accurate.

Required: Yes

-i

Specifies an alternate client daemon. The default value represents the AWS CloudHSM client.

Default: 1

Required: No

--ssl

Replaces the SSL key and certificate for the cluster with the specified private key and certificate. When you use this parameter, the --pkey and --cert parameters are required.

Required: No

--pkey

Specifies the new private key. Enter the path and file name of the file that contains the private key.

Required: Yes if --ssl is specified. Otherwise, this should not be used.

--cert

Specifies the new certificate. Enter the path and file name of the file that contains the certificate. The certificate should chain up to the customerCA.crt certificate, the self-signed certificate used to initialize the cluster. For more information, see Initialize the Cluster.

Required: Yes if --ssl is specified. Otherwise, this should not be used.

Related Topics