(12.06.110-en) IGEL UMS Administrator Command-Line Interface

0

Successful execution

1

Internal error. An error number is outputted to stderr; for details, see Error Numbers. 

2

Wrong usage of the CLI or invalid arguments

List all configured data sources

db

list

Shows the ID of the data source, which is required by other commands.

The lowest ID is 1.

IDs may change upon the creation and deletion of data sources.

It is strongly recommended to always extract the ID before using it in other commands with --id

The ID is calculated like this: highest existing ID + 1

Show all details of a database

db

show

-i

--id

integer

The ID of the database to show

Run umsadmin-cli db list to get a list of current data sources and select the ID of a data source.

Run umsadmin-cli db show --id <ID>  with that ID.

Create a new database connection

db

create

-t

--type

string

The database type.
For a list of the possible values, type umsadmin-cli db create

Type, user, and port are required.

Other options may or may not be required depending on the DB type

db create will activate the database by default; this can be prevented by using -A or --no-activate. A password option cannot be used then.

If activation fails, the data source entry will still be present and is not active (same behavior as in the graphical UMS Administrator).

'rmdb' is a reserved name for the embedded database type and cannot be used for other types.

-H

--host

string

The database host

-d

--domain

string

The database domain

-p

--port

integer

The database port

-u

--user

string

The database username

-S

--schema

string

The database schema

-n

--name

string

The database name.

Free text, except 'rmdb'; this name is reserved for the embedded database.

-I

--instance

string

The name of the database instance

-A

--no-activate

The database will not be activated.

--password:file

string

The password is read from a file (plain text) whose path is provided after this option.

--password:in

string

The password is read from stdin; an interactive prompt is shown.

Edit a data source

db

edit

-t

--type

string

The database type.
For a list of the possible values, type umsadmin-cli db create

Embedded databases cannot be edited (as in the graphical UMS Administrator).

All options are optional, except --id

-H

--host

string

The database host

-d

--domain

string

The database domain

-i

--id

integer

The identifier of the database to be edited

-I

--instance

string

The name of the database instance

--jdbc-params

string

Additional JDBC parameter. 

For details on the JDBC parameters, see How to Set Up a Data Source in the IGEL UMS Administrator.

Examples:

• rmadmin\umsadmin-cli.exe db create --type=mssql --name=rmdb12_00 --host=122.30.229.1 --port=1433 --user=rmdb --password:in --jdbc-params sendStringParametersAsUnicode=false;

• rmadmin/umsadmin-cli.bin db edit -i 1 --jdbc-params sendStringParametersAsUnicode=false;

-n

--name

string

The database name.

Free text, except 'rmdb'; this name is reserved for the embedded database.

-p

--port

integer

The database port

-S

--schema

string

The database schema

-u

--user

string

The database username

Activate a database connection

db

activate

--password:file

string

The password is read from a file (plain text) whose path is provided after this option. 

Example: umsadmin-cli db activate --password:file /home/ike/password.txt

--password:in

string

The password is read from stdin; an interactive prompt is shown.

-i

--id

integer

The identifier of the database to be activated

Deactivate the active database connection

db

deactivate

-i

--id

integer

The identifier of the database to be deactivated

Test the active database connection

db

test

--password:file

string

The password is read from a file (plain text) whose path is provided after this option. 

Example: umsadmin-cli db test --password:file /home/ike/password.txt

--password:in

string

The password is read from stdin; an interactive prompt is shown.

Optimize the active database

db 

optimize

This command can only be applied to an embedded database or a Derby database.

Create a copy of the current database

db

copy

-t

--target

integer

The ID of the target database

To get the database ID, enter umsadmin-cli db list

--password:file

string

The password is read from a file (plain text) whose path is provided after this option. 

--password:in

string

The password is read from stdin; an interactive prompt is shown.

Delete a database connection

db

delete

-i

--id

integer

The ID of the database connection that is to be deleted

Create a backup of the current embedded database

db

backup

-o

--outfile

Path to the target file. The file suffix .pbak is automatically added. 

Existing backup files are not overwritten.

-f

--full

Full backup. Database, server configurations, and transfer files are included.

-p

--parent

All directories for the specified path will be created if they are not already existing.

Restore a backup into the embedded database

db

restore

-f

--file

Path to the backup file

List all ports and SSL flag

ports

list

Set new port numbers or SSL-only flag

ports

set

-d

--dev-comm

integer

Device communication port. For details, see Devices Contacting UMS.

-j

--java-webstart

integer

Java Web Start port

-w

--web-server

integer

UMS server port. For details, see UMS with Internal Database and UMS with External Database.

-e

--embedded

integer

Embedded database port

--ssl-only

boolean

Allow SSL connections only

List all ciphers, optionally filtered

cipher

list

List all ciphers

-e

--enabled

List only enabled ciphers

-d

--disabled

List only disabled ciphers

Enable ciphers

cipher

enable

Enable ciphers. The ciphers are separated by whitespaces.

Example: umsadmin-cli cipher enable CIPHER1 CIPHER 2 CIPHER3 

--all

Apply for all; individual cipher names are ignored.

Disable ciphers

cipher

disable

Disable ciphers. The ciphers are separated by whitespaces.

Example: umsadmin-cli cipher disable CIPHER1 CIPHER 2 CIPHER3

--all

Apply for all; individual cipher names are ignored.

Reset web certificates

reset-certs

-y

--yes

The reset is only executed after confirmation

Assign certificate to current or all servers

web-certs

assign-cert

-f

--fingerprint-sha1

SHA1 fingerprint of certificate

-s

--server

Server to which the certificate is assigned. Possible values:

• ALL_SERVER

• CURRENT_SERVER (default)

Create a root certificate

web-certs

create-root-cert

-a

--algorithm

Key pair algorithm; rsa or ec (default: rsa)

-c

--country

Country code (two letters)

-d

--expiration-date

Expiration date (YYYY-MM-DD)

(Current date plus 20 years if not specified.)

--key-size

Key size (4096, 8192, ... bits). Valid values :

• 4k (default)

• 8k

• 12k

• 16k 

-l

--locality

Locality

(If not specified, the hash code of a random uuid is used.)

-n

--name

Certificate name
(default: Root certificate)

--named-curve

Named curve.
Valid values:

• nist-p-384 (default)

• nist-p-256

• nist-p-521 

-o

--organization

Organization

(Mandatory option)

Create signed certificate

web-certs

create-signed-cert

-f

--fingerprint-sha1

SHA1 fingerprint of parent CA certificate

The parent CA certificate is specified by the SHA1 fingerprint. It doesn’t matter whether you use no delimiter, ‘-’ or ‘:’ as the delimiter for the fingerprint.

-n

--name

Certificate name
(default: Certificate)

--cn

Common name

-c

--country

Country code (two letters)

-o

--organization

Organization

-l

--locality

Locality

(If not specified, the hash code of a random uuid is used.)

-d

--expiration-date

Expiration date (YYYY-MM-DD)

(Current date plus 1 year if not specified.)

--ca

Certificate type:

• true = CA certificate

• false = End entity (default)

-h

--hostname

Hostname (hostname or one of these values:

• ALL_SERVER

• CURRENT_SERVER (default)

You can specify a list of hostnames for the subject alternative names (SAN) or you can specify, whether the current server (CURRENT_SERVER) or all servers (ALL_SERVER) should be listed in the SAN list.

Delete a certificate

web-certs

delete

-f

--fingerprint-sha1

SHA1 fingerprint of certificate

Export certificate

web-certs

export-cert

-c

--cert-file

Path to which the certificate should be exported
(Name cert.cert is used when only a directory is specified.)

-f

--fingerprint-sha1

SHA1 fingerprint of certificate

Export certificate chain to keystore (JKS)

web-certs

export-cert-chain

-f

--fingerprint-sha1

SHA1 fingerprint of certificate

-k

--keystore-file

Path to keystore to which certificate chain should be exported

--password:file

Path to a file containing the password

--password:in

Shows an interactive prompt to enter the password

Import certificate chain from keystore

web-certs

import-cert-chain

-k

--keystore-file

The keystore file

--password:file

Path to a file containing the password

--password:in

Shows an interactive prompt to enter the password

Import decrypted private key

web-certs

import-private-key

-f

--fingerprint-sha1

SHA1 fingerprint of parent CA certificate

-p

--private-key-file

The file containing the private key

Import root certificate

web-certs

import-root-cert

-c

--cert-file

The root certificate (CERT, CER, CRT, PEM)

Import signed certificate

web-certs

import-signed-cert

-c

--cert-file

The root certificate (CERT, CER, CRT, PEM)

A certificate can only be imported when no other certificate with the same fingerprint already exists; otherwise, you will get an error message.

-f

--fingerprint-sha1

SHA1 fingerprint of parent CA certificate

List the assigned server of a certificate

web-certs

list-assigned-server

-f

--fingerprint-sha1

SHA1 fingerprint of certificate

List all web certificates or details of a certificate

web-certs

list

-f

--fingerprint-sha1

SHA1 fingerprint of certificate

When you specify a fingerprint, the details of the certificate with that fingerprint are shown.

Renew certificate

web-certs

renew-cert

-f

--fingerprint-sha1

SHA1 fingerprint of certificate

You only have to specify the fingerprint of the certificate that should be renewed. If the other parameters are not specified, the values from the old certificate are used (with a new expiration date).

-n

--name

Certificate name 

--cn

Common name

-c

--country

Country code (two letters)

-o

--organization

Organization

-l

--locality

Locality

-d

--expiration-date

Expiration date (YYYY-MM-DD)
(Current date plus 1 year if not specified)

-h

--hostname

Hostname (hostname or one of these values:

• ALL_SERVER

• CURRENT_SERVER

Show UMS superuser

su

list

Change UMS superuser

su

change

-u

--user

string

New superuser

-p

--password:file

string

The password is read from a file (plain text) whose path is provided after this option.

--password:in

string

The password is read from stdin; an interactive prompt is shown.

Show the current UMS IDs

licensing

list

Create a new UMS ID

licensing

create

Backup the UMS ID

licensing

backup

-o

--outfile

string

Path to the target file (file suffix: .ksbak)

-p

--parent

All directories for the specified path will be created if they are not already existing.

--password:file

string

The password is read from a file (plain text) whose path is provided after this option.

--password:in

string

The password is read from stdin; an interactive prompt is shown.

Restore a UMS ID from a backup

licensing

restore

-f

--file

string

Path to the backup file

--password:file

string

The password is read from a file (plain text) whose path is provided after this option.

--password:in

string

The password is read from stdin; an interactive prompt is shown.

Install a network token for the UMS Server or a broker (UMS HA)

token

-f

--token-file

string

Path to token file

This command is also available as a standalone command named umstokeninstall-cli in broker-only installations. It is equivalent to umsadmin-cli token.

--server

boolean

Install token for UMS Server

--broker

boolean

Install token for broker

Show the current UMS cluster FQDN

ums-cluster

list

Set a new UMS cluster FQDN

ums-cluster

create

-n

--name

Name for the new UMS cluster FQDN

Delete the current UMS cluster FQDN

ums-cluster

remove

Start the local UMS Server

server

start

Stop the local UMS Server

server

stop

Restart the local UMS Server

server

restart

End the update mode of the local UMS Server

server

end-update-mode

Set the distributed mode of the UMS installation

server

distributed

-e

--enable

Enable Distributed UMS

-d

--disable

Disable Distributed UMS

1000

Unable to connect to database. UMS server may be down.

1001

Cannot get database configurations.

1002

Cannot create database.

1003

Cannot activate database. [param]

1004

Internal error while activating database.

1005

Database already exists in this configuration.

1006

Database type is unknown.

1007

Database is already activated.

1008

Cannot edit database configurations.

1009

Internal error while optimizing database.

1010

The active data source type is not Embedded or Derby and does not support optimization.

1011

Test of the active data source failed.

1012

No database is activated.

1013

Cannot deactivate database.

1014

No database is active or the active database is not of type 'Embedded' or 'Derby'.

1020

Database could not be deleted.

1030

The specified directory for the backup does not exist: [param]

1031

Internal error while attempting database backup.

1040

The specified backup file was not found.

1041

The specified backup file has an invalid file type.

1042

Unable to read the specified backup file.

1043

Internal error while activating data source after restore.

1044

Internal error while attempting to restore database.

1045

The active data source is not embedded or there is no active data source.

1051

Authentication error or internal error when an attempt was made to copy the database

1052

Error Accessing credentials of source database

1090

A name is required for non-embedded database types.

1091

Activation failed, incorrect password provided.

1092

Backup failed, the specified file already exists.

1093

Port number is required for non-Embedded database.

1094

A data source of the Embedded type cannot be edited.

1095

No such data source with this ID.

1100

The name 'rmdb' is reserved for the Embedded database.

2000

Internal error while reading port configuration.

2001

Internal error while setting port configuration.

2002

Internal error while restarting UMS server.

2003

Invalid port number provided.

2004

Port number [param] already configured.

3000

Internal error while reading cipher data.

3001

Internal error while changing cipher configuration.

3002

Invalid ciphers provided: [param]

4000

Resetting web certificates requires '--yes' option for confirmation.

4001

Internal error while resetting web certificates.

5000

Internal error while reading superuser credentials.

5001

Internal error while writing superuser credentials.

5002

No username was provided for new credentials.

5003

Unable to set superuser credentials. There is no active data source.

6000

Unable to create a new UMS ID.

6001

The specified file for the license key backup already exists.

6002

No internal license keystore found.

6003

Internal error while creating license key backup.

6004

Internal error while restoring license key backup.

6005

The specified file for the license key backup does not exist.

6006

The specified password for the license key backup is incorrect.

6007

The specified path for the license key backup does not exist: [param]

7000

Token file was not found.

7001

Setup type not defined, token not installed.

7501

Unable to set UMS cluster FQDN.

7502

Unable to show UMS cluster FQDN.

7503

Unable to delete the cluster FQDN.

8000

Internal error while restarting the UMS server.

8001

Internal error while starting the UMS server.

8002

Internal error while stopping the UMS server.

8003

Internal error while ending the update mode of the UMS Server.

8004

Internal error while setting the distributed mode of the UMS installation.

8005

Either --enable or --disable must be provided in the options.

8006

Distributed UMS not recommended for Derby Embedded Database.

9000

An error with the password file occurred: [param]

9001

The provided passwords did not match. Aborted.

9002

The provided password exceeds the maximum character limit ([param]) or contains only whitespace.

9700

File [param] doesn't exist!

9701

Keystore contains no certificate entries!

9702

Keystore password is invalid!

9703

Keystore couldn't be read!

9704

Could not import certificate chain!

9705

Internal error while importing certificate chain!

9706

No SHA1 fingerprint specified!

9707

Could not delete certificate(s) with SHA1 fingerprint [param]!

9708

Certificate must not be deleted because it is currently in use!

9709

Root certificate creation failed!

9710

Certificate could not be created! Private key of CA certificate is not known.

9711

Certificate could not be created! CA certificate is not valid.

9712

Could not find CA certificate with specified fingerprint.

9713

Certificate could not be created! CA certificate does not meet the requirements.

9714

Certificate could not be created! Requirements for CA certificate creation are not met.

9715

Creation of signed certificate failed!

9716

Certificate could not be created! Certificate name too long (only 200 characters are allowed)!

9717

Could not find certificate with specified fingerprint!

9718

Certificate could not be renewed! Certificate has no CA parent.

9719

Certificate file [param] doesn't exist!

9720

Certificate is invalid!

9721

Import of certificate failed! No CA certificate.

9722

Import of certificate failed!

9723

Import of certificate failed! Certificate is not valid.

9724

Import failed! Certificate doesn't contain any subject alternative names.

9725

Import of private key failed! File [param] doesn't exist.

9726

Import of private key failed! Private key is encrypted. Decrypt it before importing it.

9727

Import of private key failed!

9728

Certificate already has private key!

9729

Import of private key failed! Private key does not match the specified certificate.

9730

Export of certificate failed! Directory [param] doesn't exist.

9731

Export of certificate failed!

9732

Export of certificate chain failed! Directory [param] doesn't exist.

9733

Certificate must not be a root or CA certificate!

9734

Export of certificate chain failed!

9735

Password must be at least 6 characters long!

9736

Assignment of certificate failed!

9737

Private key is not known!

9738

Could not read certificate info!

9739

Import failed! Certificate with same fingerprint already exists.

9740

Import failed! No valid root certificate.

9741

Import failed! Verification of signature failed.

9742

Import failed! No valid CA certificate available.

9743

Could not read assigned server info!

9744

Could not find certificate with specified fingerprint or no server is assigned to certificate!

9745

Common name is invalid! Only A-Z, a-z, 0-9, - and . are allowed.