(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 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 Run |
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
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 |
-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.03-en) How to Set Up a Data Source in the IGEL UMS Administrator. Examples:
| ||||
-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: | ||
--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: | ||
--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 | |
--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 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.03-en) Devices Contacting UMS. |
-j | --java-webstart | integer | Java Web Start port | |||
-w | --web-server | integer | UMS server port. For details, see (12.03-en) UMS with Internal Database and (12.03-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: | ||
--all | Apply for all; individual cipher names are ignored. | ||||
Disable ciphers | cipher | disable | Disable ciphers. The ciphers are separated by whitespaces. Example: | ||
--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 |
--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. |