Administration of VCMs

nShield VCMs are administered through the unified utility vcmadmin, which directs the command to the service that implements the command.

Some commands require elevated privileges by default because both the permissions and the protection settings have an impact on the usability of the keys by non-administrative users. Commands that create keys or modify configuration always require elevated privileges. Elevated privileges mean root on Linux, and the built-in local Administrators group (running in an elevated shell) on Windows. If a command requires elevated privileges, this is indicated in the command description.

You can modify the permissions and protection options on service keys to allow particular groups of users to execute commands that require the private key for a given service. See Permissions on SSH keys and Setting protection on SSH keys.

vcmadmin

The vcmadmin utility manages the administration of VCMs using different subcommands.

vcmadmin <subcommand>

You can use one of the following subcommands each time you run vcmadmin:

vcmadmin create

This command creates a VCM and sets the initial sshadmin public key to the one provided by the tenant. An IP address and UUID will be returned which should be sent to the tenant who requested the VCM.

vcmadmin create --request REQUESTFILE [-h] [--timeout <TIMEOUT>] [--esn <ESN>] [--verbose] [--json] [--serial-cardreader] [--autostart] [--ip-address IP_ADDDRESS] [--features FEATURES] [--outdir DIR] NAME

This command takes the following parameters:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--esn

ESN of module on which to create the VCM

--verbose

Prints verbose logs.

--request

File containing the signed tenant request

--features

Features set for the VCM

--serial-cardreader

This VCM has access to the HSM card-reader

--autostart

This VCM will automatically start after a reboot of the HSM

--ip-address

IP address to be allocated to the VCM

--outdir

Directory into which the VCM configuration file will be written

vcmadmin start

This command starts the specified VCM.

vcmadmin start [-h] [--esn <ESN>] [--timeout <TIMEOUT>] [--verbose] [--json] [--request <REQUESTFILE>] UUID

If the VCM was created with the restrict-startup option, a valid tenant request file will be needed to use this command.

This command takes the following parameters:

Parameter Description

--verbose

Prints verbose logs.

--json

Prints the HSM firmware version and image version in JSON format.

--esn

ESN of the HSM on which to start the VCM

--request

File containing the signed tenant request

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

UUID

Identifier of the VCM to be started.

vcmadmin stop

This command stops the specified VCM.

It is not possible to stop a VCM in the following situations:

  • It has an ncoreapi service running

In this case you should contact the tenant that is using the VCM and ask them to put the module in maintenance mode by following the instructions at Check and change the mode of operation.

Alternatively you can force the VCM to stop by using the command with the --force option.

Forcing a VCM to stop may cause problems for the tenant. You should only do this if you have authority to do so. 
vcmadmin stop [-h] [--esn <ESN>] [--timeout <TIMEOUT>] [--force] [--verbose] [--json] UUID

This command takes the following parameters:

Parameter Description

--verbose

Prints verbose logs.

--json

Prints the HSM firmware version and image version in JSON format.

--esn

ESN of the HSM on which to start the VCM.

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--force

Ignore warnings and force VCM to stop.

UUID

Identifier of the VCM to be stopped.

vcmadmin list

This command lists VCMs that have been created.

vcmadmin list [-h] --esn <ESN> [--timeout <TIMEOUT>] [--verbose] [--json] [--active]

This command takes the following parameters:

Parameter Description

--verbose

Prints verbose logs.

--json

Prints metadata in JSON format.

--esn

Lists only VCMs created on the ESN specified. If omitted all VCMs on all ESNs will be listed.

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--active

Lists only those VCMs that are currently running.

vcmadmin show

This command shows the properties of VCMs

vcmadmin show [-h] --esn <ESN> [--timeout <TIMEOUT>] [--verbose] [--json] uuid <UUID>

This command takes the following parameters:

Parameter Description

--verbose

Prints verbose logs.

--json

Prints metadata in JSON format.

--esn

Shows only VCMs created on the ESN specified. If omitted all VCMs on all ESNs will be shown.

UUID

Identifier of the VCM to be shown.

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

vcmadmin delete

This command deletes the VCM specified.

It is not possible to delete a VCM that is currently running. You must first stop the VCM using vcmadmin stop.

It is not possible to delete a VCM in the following situations:

  • It has an unfinalized audit log running

In this case you should contact the tenant that is using the VCM and ask them to finalize the audit log as described at disabling audit logging.

Alternatively you can force the VCM to delete by using the command with the --force option.

vcmadmin delete [-h] [--esn <ESN>] [--timeout <TIMEOUT>] [--verbose] [--json] [--force] UUID

This command takes the following parameters:

Parameter Description

--verbose

Prints verbose logs.

--json

Prints metadata in JSON format.

--force

Forces the VCM to delete even with an unfinalized audit log.

--esn

Deletes only VCMs from the ESN specified. If omitted the VCMs will be deleted regardless of ESN.

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

UUID

Identifier of the VCM to be deleted.

vcmadmin stats

This command prints statistics about VCM resource usage.

VCM statistics are gathered by a background process and may reflect the usage up to 90s ago.

vcmadmin stats [--timeout <TIMEOUT>] [--esn <ESN>] [--uuid <UUID>] [--json]

This command takes the following parameter:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--json

Prints metadata in JSON format.

--esn

Prints statistics only for VCMs from the ESN specified. If omitted statistics for all VCMs will be printed.

UUID

Prints statistics only for the VCM specified by this identifier.

vcmadmin properties

This command manages the properties of VCMs.

vcmadmin properties <subcommand>

You can use one of the following subcommands with this command:

vcmadmin properties set

This subcommand sets properties for a VCM.

vcmadmin properties set [-h] --request <REQUESTFILE> UUID PROPERTY VALUE

This subcommand takes the following parameters:

Parameter Description

request

File containing the tenant request

UUID

Identifier of the VCM.

PROPERTY

VCM property to be set

VALUE

Value to be set for PROPERTY

vcmadmin properties list

This subcommand lists the VCM properties that can be set by the set command. To see values currently set on a given VCM use the show command or the list command using the --json option.

vcmadmin properties list [-h]