Document toolboxDocument toolbox

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

The Universal Management Suite (UMS) Administrator command-line interface (CLI) allows you to control the IGEL UMS Administrator via a terminal and to automate UMS Administrator actions via scripting. Among these actions are creating and editing database connections for the UMS Server, backing up and restoring the embedded database, configuring communication ports and security, managing the UMS ID, configuring the superuser, and restarting the UMS Server.

As this feature allows complete control without any graphical desktop environment, it is possible to run the CLI application on headless Linux systems.


Basic Usage

Like the graphical UMS Administrator application, the CLI requires elevated privileges.

→ Windows: Open a command prompt (cmd.exe) as Administrator.

→ Linux: Become root or use sudo

You can run the main command umsadmin-cli from any directory, as the command is made available on the PATH.

→ To see the global options and the primary subcommands, enter umsadmin-cli

image-20240617-120228.png

→ To get all possible options for a specific subcommand, enter umsadmin-cli followed by the subcommand, e.g. umsadmin-cli db create

image-20240617-120247.png

 

Certain subcommands have no options and run immediately. Please refer to the Command Reference.

 

→ To get the complete online help with all commands, enter umsadmin-cli fullhelp 

→ To get the list of available commands, enter umsadmin-cli help 

 

→ To display help information about any command, use help as a subcommand. For example, enter umsadmin-cli web-certs help
  

Global Options

If you intend to use the UMS Administrator CLI in a script, you may want to configure its output to stdout/stderr according to your needs. This makes it easy to further process the output of umsadmin-cli and extract any relevant data.

Please see the available options below. 

--machine-readable

Prints output machine-readable with a semi-colon (;) as default separator.

Example:

root@machine:/home/locadmin# umsadmin-cli --machine-readable db list
ACTIVE;DATABASE;HOST;USER;DB-TYPE;ID
true;rmdb;localhost;root;Embedded DB;1

--no-header

No header line is printed. (Not all commands print a header.)

Example:

root@machine:/home/locadmin# umsadmin-cli --machine-readable --no-header db list
true;rmdb;localhost;root;Embedded DB;1

--quiet

All output to stdout/stderr is suppressed for some commands which might take a long time to execute. These are, for instance, db backup, db restore, db copy, and server-restart.

Example:

root@machine:/home/locadmin# umsadmin-cli --quiet db backup -o /tmp/mybackup02.pbak --full
root@machine:/home/locadmin#

It is still possible to redirect all output to a null device using operating system functions. For example, to redirect standard output and error output to the null device on Linux, use:

command … >/dev/null 2>&1

--separator

Defines a custom column separator for output to stdout/stderr.

Example:

root@machine:/home/locadmin# umsadmin-cli --machine-readable --no-header --separator "||" db list
true||rmdb||localhost||root||Embedded DB||1

Some separator characters, such as the pipe symbol (|), require quotes because they have special functions in terminals.

Exit Codes

Exit Code

Meaning

Exit Code

Meaning

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

Command Reference

General Usage of Password Options

Some commands require a password. Entering the password in plain text on the command line is not secure and therefore not possible. Therefore, one of the following password options must be used:

--password:in for interactively entering the password (possibly with confirmation)

--password:file <FILE> for providing a file containing the password

A password file must have the password as the first line and the passwords must not be pure whitespace. Additional lines with content are allowed but will not be evaluated.



Database

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Value Type

Option Description 

Remarks

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Value Type

Option Description 

Remarks

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



Ports

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Value 

Option Description 

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Value 

Option Description 

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

Cipher

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Option Description 

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Option Description 

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.

Manage Web Certificates

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Option Description 

Remarks

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Option Description 

Remarks

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



Superuser

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Value 

Option Description 

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Value 

Option Description 

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.

UMS ID

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Value 

Option Description 

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Value 

Option Description 

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.

Network Token

Action

Primary Subcommand

Short Option 

Long Option 

Value 

Option Description 

Remarks

Action

Primary Subcommand

Short Option 

Long Option 

Value 

Option Description 

Remarks

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



UMS Cluster

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Option Description 

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Option Description 

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







Server

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Option Description 

Action

Primary Subcommand

Secondary Subcommand

Short Option 

Long Option 

Option Description 

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

Error Numbers

The error numbers are printed in the following format:

<E-NNNN>: <HUMAN READABLE MESSAGE>

Some error descriptions in the following table contain the phrase „[param]“. These will be replaced during runtime with details for the relevant error, e.g. the problematic path for E-1030.

Error number

Error description

Error number

Error description

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.

Â