ucl client create - Overview

The ucl client create command provides the following options:

Common parameters

Common parameters in the ucl client create command:

--name
It is good practice to use the client appliance hostname.
Else - check Client Name Characters.
--check_ip
0-no, 1-yes
Default (not specified) - as set by the partition's --check_ip setting.
--allow_nat
0-no, 1-yes
Default (not specified) - as set by the partition's --allow_nat setting.
--ip_range
Specifies the range of IP that can use client-certificate. Default - all IPs.
Uses CIDRClosedClassless Inter-Domain Routing, an IP addressing notation format. For example:
192.168.0.96/27 identifies (32 - 2) IPs: from 192.168.0.97 to 192.168.0.126
0.0.0.0/0 identifies ALL IPs.

For the --check_ip, --allow_nat, and --ip_range parameter use, refer to Certificate Misuse Prevention.

ucl client create -m ACTIVATE

This command reserves a client name in the specified partition and generates an activation code (ACClosedActivation Code). An appliance must use the ACClosedActivation Code to complete its registration (within the specified time) by using the ucl register command.

ucl client create
-n <new client name>
-p <partition>
-m ACTIVATE

[--ac_len <number of digits>]
[--ac_validity <minutes>]
[--cert_validity <minutes>]

[--check_ip <0|1>]
[--allow_nat <0|1>]
[--ip_range <IP range>]

--ac-len
The number of digits in ACClosedActivation Code.
Default (6) may be customized in the partition's settings.
--ac_validity
ACClosedActivation Code validity in minutes.
Default (20) may be customized in the partition's settings.
--cert_validity
Certificate validity in minutes (following the ucl register command).
If omitted, the system setting's value specified by the client-exp in Certificate Validity Settings is used. Default: 3 yearsClosedFor any time interval setting in years, 1 year is converted to 365 days (1578240 minutes).
--check_ip,
--allow_nat,
--ip_range
Refer to Common parameters.

Example:

ucl client create -n client1 -p CodeSign1 -m ACTIVATE
Client created successfully; activation code is 737569

ucl client create -m Template

To facilitate the automation-ready instantiation of similar clients (called ephemeral clients),  create a template of client properties. The command registers the template name in the specified partition and returns the activation code used to authorize the use of the template.

ucl client create
-p <partition>
-n <client template name>
-m Template

[--ac_len <number of digits>]
[--ac_validity <minutes>] 
[--cert_validity <minutes>]

[--check_ip <0|1>]
[--allow_nat <0|1>]
[--ip_range <IP range>]

--ac-len
Number of digits in ACClosedActivation Code. Default: 16
--ac_validity
ACClosedActivation Code validity in minutes. Default: 30 minutes. Up to 1 year (529600 minutes).
--cert_validity
Certificate validity in minutes (following the ucl register command). Default: 30 minutes.
--check_ip,
--allow_nat,
--ip_range
Refer to Common parameters.

For example,

ucl client create -p test -n Master -m Template \
--ac_validity 129600 --cert_validity 144000 \
--ip_range 192.168.0.96/27 -w *********

This command creates a client template by name "master" with the following ACClosedActivation Code-properties:

  • --ac_len: 16 digits (default)
  • --ac_validity: the activation code is valid for 90 days (129600 minutes).
  • --cert_validity: a certificate obtained using this code is valid for 100 days (144000 minutes).
  • --ip_range: from 192.168.0.97 to 192.168.0.126

ucl client create -m FULL for CORE client

This option creates a client and its certificate ( .pfx file) in the specified directory. The certificate is protected by a secret passphrase known to the CORE client software.

ucl client create
-n <new client name>
-p <partition name to be used by the client>
-m FULL

-o <certificate file name and path>
--san <CSV list of the client's IP addresses without spaces>

[--check_ip <0|1>]
[--allow_nat <0|1>]
[--ip_range <IP range>]

--san
Spaceless CSVClosedComma Separated Values list of IP addresses and hostnames of the designated appliance. This list is stored in the certificate's SANClosedSubject Alternative Names - Certificate field with a list of IP addresses. field.
--check_ip,
--allow_nat,
--ip_range
Refer to Common parameters.

Example:

ucl client create -n client1 -p CodeSign1 -m FULL \ -o ./CodeSign1.pfx --san 192.168.0.97

ucl client create -m FULL for non-CORE Client

This option creates a client and its certificate ( .pfx file) in the specified directory. An explicit passphrase protects the certificate. It must be used to obtain the private key from the PFXClosedAn archive file format for storing cryptography objects using Base64 encoding file by applications that do not use CORE client.

ucl client create
-n <new client name>
-p <designated partition name>
-m FULL

-o <certificate file name and path>
--pfx_password <certificate file password>

[--check_ip <0|1>]
[--allow_nat <0|1>]
[--ip_range <IP range>]

Example:

ucl client create -n client1 -p CodeSign1 -m FULL -o ./CodeSign1UI.pfx --pfx_password CodeSign1UI! --check_ip 1 --ip_range 192.168.0.97/27

ucl client create -m External

This option adds a CORE client that identifies itself by using a certificate signed by an external CA.

Syntax:

ucl client create

-n <client name as specified by the CN= value in the certificate>

-p <partition name as specified by the OU= value in the certificate>

-m External

-c <path to the received certificate file in .cer format>

-n
The client name as it is specified by the CN=value in the certificate.
-p
The partition name as it is specified by the OU=value in the certificate.
-c
Path to the certificate file in the CERClosedCertificate file in PEM format format.

The certificate must be delivered in the CERClosedCertificate file in PEM format (PEMClosedBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----") format and specify the following settings:

CN
<Name of the CORE client>
OU
<Name of the CORE partition>
O
CLIENT
SANClosedSubject Alternative Names - Certificate field with a list of IP addresses.
<IP or DNS addresses of the client appliance>

For example, a client "my-name" certificate for accessing partition "test" must have the following Subject :
"CN=my-pc, OU=test, O=CLIENT"

Note that the order, character case, and commas - all are important.

ucl client list

Lists partition clients.

ucl client list -p <partition name>

ucl client update

Modifies a subset of client settings using the key-value method

ucl client update

-p <partition name>

-n <client name>

-k [ --key ] <setting's name>

-v [ --value ] <setting's value>

The supported settings (--key) are:

--check_ip
0-no, 1-yes
Refer to Common parameters.
--allow_nat
0-no, 1-yes
Refer to Common parameters.
--ip_range
Specification of the IP range in CIDRClosedClassless Inter-Domain Routing, an IP addressing notation format.
Refer to Common parameters.

Examples:

  • Set the allowed IP range from 192.168.0.97 to 192.168.0.126:
    ucl client update -p test -n ep1 -k ip_range -v 192.168.0.96/27
  • To remove IP range restrictions:
    ucl client update -p test -n ep1 -k ip_range -v 0.0.0.0/0

ucl client show

Shows the client’s properties.

ucl client show

-n <client name>

-p <partition name>

Examples:

ucl client show -n client1 -p CodeSign1

{ "name" :" client1", "partition": "CodeSign1", "Check IP is enforced": "false", "Created at": "2018-09-03T09:28:26Z", "IP range": "0.0.0.0/0" "Activation status": "Activated", "Certificate expiring": "false", "Last updated at": "2018-09-03T09:28:26Z", "Certificate renew required" : "false", "Client certificate": "MIICODCCAd ////// truncated //// I4IyM6tpus2aETT8=", "Certificate validity": "1578240", "Client template" : "N/A", "Client version" : "2.0.1904.35468", "Activation locked" : "false", "Certificate expires on" : "2022-05-20T06:41:23Z", "Activation type" : "Activation Code", "NAT impact is allowed" : "false" }

All longevity parameters ("validity", "expiry") are shown in minutes.

ucl client refresh

This command restarts the validity count-down of an ACClosedActivation Code used by a client registration command. The --keep-same-ac option has the following impact:

ucl client refresh
-n <client name>
-p <partition name>

[--keep-same-ac] // do not change the Activation Code
[--ac_validity <AC validity period in minutes>] Up to 1 year (529600 minutes)
[--cert_validity <certificate validity in minutes>]

[--ip_range <IP range>] // see Common parameters

Example:

Before the application of the refresh command, the current ACClosedActivation Code was scheduled to expire on:

ucl client show -p test -n Master

// lines deleted

"activation code valid up to": "2018-11-08 21:43:21Z",

// lines deleted

The refresh restarts the count-down and assigns a new ACClosedActivation Code:

ucl client refresh -p test -n Master -w ******

Client Master activation code refreshed successfully, client activation code is 805884457391580 it expires on 2018-11-08 23:29:56

Tip
When refreshing a template ACClosedActivation Code, consider using the --keep-same-ac option.

ucl client delete

Deletes the client.

ucl client delete -n <client name> -p <partition name>

Example:

ucl client delete -n client2 -p CodeSign1

Client deleted successfully