Document toolboxDocument toolbox

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

The Universal Management Suite (UMS) Administrator command-line interface 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

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

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


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

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 CodeMeaning
0Successful execution
1Internal error. An error number is outputted to stderr; for details, see Error Numbers
2Wrong 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.

UMS Server Restart Required

Most of the commands in the sections "Ports", "Cipher", "Reset Certificates", and "Superuser" change the UMS configuration and a restart of the UMS server is required to make the new settings take effect. This can be done in two ways:

  • Use the appropriate function of the OS (e.g. systemctl on Linux)
  • Use the command umsadmin-cli server restart

Database

ActionPrimary SubcommandSecondary SubcommandShort Option Long Option Value TypeOption Description Remarks

List all configured data sources

dblist



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 databasedbshow-i--idintegerThe 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--typestringThe 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--hoststringThe database host
-d--domainstringThe database domain
-p--portintegerThe database port
-u--userstringThe database username
-S--schemastringThe database schema
-n--namestring

The database name.

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


-I--instancestringThe name of the database instance
-A--no-activate
The database will not be activated.

--password:filestringThe password is read from a file (plain text) whose path is provided after this option.
--password:instringThe password is read from stdin; an interactive prompt is shown.
Edit a data sourcedbedit-t--typestringThe 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--hoststringThe database host
-d--domainstringThe database domain
-i--idintegerThe identifier of the database to be edited
-I--instancestringThe name of the database instance

--jdbc-paramsstringAdditional JDBC parameter. 

For details on the JDBC parameters, see (12.03-en) 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--namestring

The database name.

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


-p--portintegerThe database port
-S--schemastringThe database schema
-u--userstringThe database username
Activate a database connectiondbactivate

--password:filestring

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:instringThe password is read from stdin; an interactive prompt is shown.
-i--idintegerThe identifier of the database to be activated
Deactivate the active database connectiondbdeactivate-i--idintegerThe identifier of the database to be deactivated
Test the active database connectiondbtest
--password:filestring

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:instringThe password is read from stdin; an interactive prompt is shown.
Optimize the active databasedb optimize



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

Create a copy of the current databasedbcopy-t--targetinteger

The ID of the target database

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


--password:filestringThe password is read from a file (plain text) whose path is provided after this option. 
--password:instringThe password is read from stdin; an interactive prompt is shown.
Delete a database connectiondbdelete-i--idintegerThe 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 databasedbrestore-f--file
Path to the backup file

Ports

ActionPrimary SubcommandSecondary SubcommandShort Option Long Option Value Option Description 
List all ports and SSL flagportslist



Set new port numbers or SSL-only flag



ports



set



-d--dev-commintegerDevice communication port. For details, see (12.03-en) Devices Contacting UMS.
-j--java-webstartintegerJava Web Start port
-w--web-serverintegerUMS server port. For details, see (12.03-en) UMS with Internal Database and (12.03-en) UMS with External Database.
-e--embeddedintegerEmbedded database port

--ssl-onlybooleanAllow SSL connections only

Cipher

ActionPrimary SubcommandSecondary SubcommandShort Option Long Option Option Description 
List all ciphers, optionally filteredcipherlist

List all ciphers
-e--enabledList only enabled ciphers
-d--disabledList only disabled ciphers
Enable cipherscipherenable


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 cipherscipherdisable


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

ActionPrimary SubcommandShort Option Long Option Option Description 
Reset web certificatesreset-certs-y--yesOnly if provided as confirmation, the reset will run.

Superuser

ActionPrimary SubcommandSecondary SubcommandShort Option Long Option Value Option Description 
Show UMS superusersulist



Change UMS superuser

su

change

-u--userstringNew superuser
-p--password:filestringThe password is read from a file (plain text) whose path is provided after this option.

--password:instringThe password is read from stdin; an interactive prompt is shown.

UMS ID

ActionPrimary SubcommandSecondary SubcommandShort Option Long Option Value Option Description 
Show the current UMS IDslicensinglist



Create a new UMS IDlicensingcreate



Backup the UMS IDlicensing

backup

-o--outfilestringPath 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:filestringThe password is read from a file (plain text) whose path is provided after this option.

--password:instringThe password is read from stdin; an interactive prompt is shown.
Restore a UMS ID from a backup

licensing

restore

-f--filestringPath to the backup file

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

--password:instringThe password is read from stdin; an interactive prompt is shown.

Network Token

ActionPrimary SubcommandShort Option Long Option Value Option Description Remarks
Install a network token for the UMS Server or a broker (UMS HA)

token

-f--token-filestringPath 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.



--serverbooleanInstall token for UMS Server
--brokerbooleanInstall token for broker

UMS Cluster

ActionPrimary SubcommandSecondary SubcommandShort Option Long Option Option Description 
Show the current UMS cluster FQDNums-clusterlist


Set a new UMS cluster FQDNums-clustercreate-n--nameName for the new UMS cluster FQDN
Delete the current UMS cluster FQDNums-clusterremove


Server

ActionPrimary SubcommandSecondary SubcommandShort Option Long Option Option Description 
Start the local UMS Serverserverstart


Stop the local UMS Serverserverstop


Restart the local UMS Serverserverrestart


End the update mode of the local UMS Serverserverend-update-mode


Set the distributed mode of the UMS installationserverdistributed-e--enableEnable Distributed UMS

-d--disableDisable 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 numberError description
1000Unable to connect to database. UMS server may be down.
1001Cannot get database configurations.
1002Cannot create database.
1003Cannot activate database. [param]
1004Internal error while activating database.
1005Database already exists in this configuration.
1006Database type is unknown.
1007Database is already activated.
1008Cannot edit database configurations.
1009Internal error while optimizing database.
1010The active data source type is not Embedded or Derby and does not support optimization.
1014No database is active or the active database is not of type 'Embedded' or 'Derby'.
1051Authentication error or internal error when an attempt was made to copy the database
1052Error Accessing credentials of source database
1020Database could not be deleted.
1011Test of the active data source failed.
1012No database is activated.
1013Cannot deactivate database.
1030The specified directory for the backup does not exist: [param]
1031Internal error while attempting database backup.
1040The specified backup file was not found.
1041The specified backup file has an invalid file type.
1042Unable to read the specified backup file.
1043Internal error while activating data source after restore.
1044Internal error while attempting to restore database.
1045The active data source is not embedded or there is no active data source.
1090A name is required for non-embedded database types.
1100The name 'rmdb' is reserved for the Embedded database.
1091Activation failed, incorrect password provided.
1092Backup failed, the specified file already exists.
1093Port number is required for non-Embedded database.
1094A data source of the Embedded type cannot be edited.
1095No such data source with this ID.
2000Internal error while reading port configuration.
2001Internal error while setting port configuration.
2002Internal error while restarting UMS server.
2003Invalid port number provided.
2004Port number [param] already configured.
3000Internal error while reading cipher data.
3001Internal error while changing cipher configuration.
3002Invalid ciphers provided: [param]
4000Resetting web certificates requires '--yes' option for confirmation.
4001Internal error while resetting web certificates.
5000Internal error while reading superuser credentials.
5001Internal error while writing superuser credentials.
5002No username was provided for new credentials.
5003Unable to set superuser credentials. There is no active data source.
6000Unable to create a new UMS ID.
6001The specified file for the license key backup already exists.
6002No internal license keystore found.
6003Internal error while creating license key backup.
6004Internal error while restoring license key backup.
6005The specified file for the license key backup does not exist.
6006The specified password for the license key backup is incorrect.
6007The specified path for the license key backup does not exist: [param]
7000Token file was not found.
7001Setup type not defined, token not installed.
7501Unable to set UMS cluster FQDN.
7502Unable to show UMS cluster FQDN.
7503Unable to delete the cluster FQDN.
8000Internal error while restarting the UMS server.
8001Internal error while starting the UMS server.
8002Internal error while stopping the UMS server.
8003Internal error while ending the update mode of the UMS Server.
8004Internal error while setting the distributed mode of the UMS installation.
8005Either --enable or --disable must be provided in the options.
8006Distributed UMS not recommended for Derby Embedded Database.
9000An error with the password file occurred: [param]
9001The provided passwords did not match. Aborted.
9002The provided password exceeds the maximum character limit ([param]) or contains only whitespace.