(12.02-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 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.

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

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 (12.02-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`	`--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`
Test the active database connection	`db`	`test`		`--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
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 (12.02-en) Devices Contacting UMS.
			`-j`	`--java-webstart`	integer	Java Web Start port
			`-w`	`--web-server`	integer	UMS server port. For details, see (12.02-en) UMS with Internal Database and (12.02-en) 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
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`
Enable ciphers	`cipher`	`enable`		`--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`
Disable ciphers	`cipher`	`disable`		`--all`	Apply for all; individual cipher names are ignored.

Reset Web Certificates

Action	Primary Subcommand	Short Option	Long Option	Option Description
Reset web certificates	`reset-certs`	`-y`	`--yes`	Only if provided as confirmation, the reset will run.

Superuser

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
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
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
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
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
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.
1014	No database is active or the active database is not of type 'Embedded' or 'Derby'.
1051	Authentication error or internal error when an attempt was made to copy the database
1052	Error Accessing credentials of source database
1020	Database could not be deleted.
1011	Test of the active data source failed.
1012	No database is activated.
1013	Cannot deactivate database.
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.
1090	A name is required for non-embedded database types.
1100	The name 'rmdb' is reserved for the Embedded database.
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.
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.