Root SO Commands

ucl system-settings get

Lists the specified (or all) system settings.

For example, to list all system settings use:

ucl system-settings get

ucl system-settings set

Modify a system setting.

ucl system-settings set
-k <setting's tag or alias> // refer to System Settings and Static Properties
-v <value>

Examples:

ucl server create

This command adds CORE servers to the cluster. It has two options:

• Add an auxiliary server.
ucl server create -a <hostname/IP of an additional server>:[port]
• Add a Server Pair.
ucl server create -e <hostname/IP of an additional server>:[port] // designated to become EP -p <hostname/IP of an additional server>:[port] // designated to become Partner
• Add a Server Triplet.
ucl server create -e <hostname/IP of an additional server>:[port] // designated to become EP -p <hostname/IP of an additional server>:[port] // designated to become Partner -a <hostname/IP of an additional server>:[port] // designated to become Auxiliary

Note
The <hostname/IP of an additional server>:[port] argument must be as specified by the -s (self) parameter in the Add Additional Server script. See Cluster Scale-out.

Important
To activate the new servers, restart the EKMEnterprise Key Management - previous name of the product. service on the new servers. Refer to EKM Service Management.

ucl server delete

This command allows the following:

• Delete an auxiliary server:
ucl server delete -a <IP or hostname of Aux server>[:<its bootstrap port>]

• Delete an EP-Partner server pair:
ucl server delete -e <IP or hostname of EP server>[:<its bootstrap port>] -p <IP or hostname of its Partner server>

• In an EP-Partner-Aux server triplet:
ucl server delete -e <IP or hostname of EP server>[:<its bootstrap port>] -p <IP or hostname of its Partner server> -a <IP or hostname of its Auxiliary server>

Important
The EKMEnterprise Key Management - previous name of the product. Service Restart is required on all the remaining servers in the cluster. Refer to EKM Service Management.

ucl server test

This command tests readiness of all servers recorded in the CORE database to perform crypto operations. The output format is JSON. Its internal structure depends on the system's operation mode:

• In FIPS modeUKC system mode that allows processing FIPS-certified and not-certified keys - servers are grouped in triplets. The test is done in each triplet separately.
• In non-FIPS modeUKC system advanced execution mode that hasn't yet received the FIPS certification - EPs and Partners are grouped in pairs. All Auxiliary servers are presented as a pool of servers. The test is done in each pair, and each pair tests interworking with all Aux servers.

ucl server test [-full]

• engineStatus is presented in the EP info block. OK indicates that MPCMultiparty computation - A methodology for parties to jointly compute a function of their inputs while keeping those inputs private. engines of EP, its Partner, and Aux are interconnected and functioning.
• requireRestart is presented in the EP info block. Yes indicates that changes made on EP require the EKMEnterprise Key Management - previous name of the product. service restart.
• resolvedIp - the IP of the server as resolved by the server that runs this command.
• duration is the number of milliseconds that took to complete the test.
• serverVersionMatch compares the software versions of the other servers with the software version of the server that runs this command.

The --full option enhances the output and adds the following:

• certificateExpiring indicates that the certificate enters the "pre-expiry" period as defined by the system settings.
• lastStart specifies the EKMEnterprise Key Management - previous name of the product. service restart date.

ucl partition create

Besides creating a new partition, this command also creates the following:

• The partition's default users: SOSecurity officer - UKC partition administrator role. and USER.
• The partition's first client. Its name is set to the hostname where the command was executed.
• The first client's certificate (<partition-name>.pfx file in the KMIP Trust Keystore folder).

• [-d --default_client <0 | 1>] - see Allow default-client.
• [--allow_keystores] - see Keys in External Keystores.
• -i --inheritance - see Part-inherit.
• -c --certificate - see Cert-propagation.
• [-f --fips <FIPSFederal Information Processing Standards - standards developed by the United States federal government for use in computer systems by non-military government agencies and government contractors policy>] - see FIPS Processing Policy .

Note
To use the -c option, you must specify the -i option as well.

Example:

ucl partition list

This command has two options:

• ucl partition list

It lists partitions that are accessible from this appliance.

Note
More precisely, this command scans all certificate files in the CORE Client Certificate folder and attempts to decrypt each certificate using the appliance-specific password. Once the file is decrypted, it presents the partition name from the certificate's OU field (see CORE Client Certificate). If the decryption fails, the certificate is silently ignored.

Troubleshooting:
If the <partition-name>.pfx appears in the client's CORE Client Certificate folder, but the ucl partition list command fails to list it - renew its registration using the following steps:


1. On the client's appliance - delete the file.
   
2. On the EP server - delete the client from the partition.
   
3. Repeat the client registration procedure - see Registered Clients .
• ucl partition list --all

This command is available to a Root SOSecurity officer - UKC partition administrator role. (the calling appliance must be registered with the root partition). It lists all partitions from the CORE database.

ucl partition show

This command presents the partition's settings.

Note
A partition SOSecurity officer - UKC partition administrator role. can review a subset of these settings using the ucl settings get command.

ucl partition delete

Deletes the partition if it has no keys, no non-default users, and no clients.

ucl partition recover

Use this command if and only if partition clients can't use anymore their certificate. This command:

• Clears the partition client list.
• Creates new client and stores its certificate in the local CORE Client Certificates Folder.

Note
To reset the partition's SOSecurity officer - UKC partition administrator role. password, when no other SOSecurity officer - UKC partition administrator role. in the partition can do it, the Root SOSecurity officer - UKC partition administrator role. may use the ucl user recover-pwd command.