Die UMS Administrator Kommandozeilenschnittstelle ermöglicht es Ihnen, den IGEL UMS Administrator über ein Terminal zu steuern und Aktionen des UMS Administrator über Skripte zu automatisieren. Zu diesen Aktionen gehören das Erstellen und Bearbeiten von Datenbankverbindungen für den UMS-Server, das Sichern und Wiederherstellen der eingebetteten Datenbank, die Konfiguration von Kommunikationsports und Security, die Verwaltung der UMS Lizenzierungs-ID, die Konfiguration des Superusers und der Neustart des UMS-Servers.

Da diese Funktion eine vollständige Steuerung ohne grafische Desktop-Umgebung ermöglicht, kann die CLI-Anwendung auch auf Headless-Linux-Systemen ausgeführt werden.

Grundlegende Verwendung

Wie die grafische Anwendung des UMS Administrator erfordert auch die CLI erweiterte Rechte.

 Windows: Öffnen Sie eine Eingabeaufforderung (cmd.exe) als Administrator.

 Linux: Werden Sie root oder verwenden Sie sudo

Sie können das Hauptkommando umsadmin-cli von jedem Verzeichnis aus ausführen, da der Befehl auf dem PATH verfügbar ist.

 Um die globalen Optionen und die primären Unterkommandos zu sehen, geben Sie umsadmin-cli ein.


 Um alle möglichen Optionen für einen bestimmten Unterbefehl zu erhalten, geben Sie umsadmin-cli gefolgt von dem Unterbefehl ein, z.B. umsadmin-cli db create


 Um die komplette Online-Hilfe mit allen Befehlen zu erhalten, geben Sie umsadmin-cli fullhelp ein.


Bestimmte Unterbefehle haben keine Optionen und werden sofort ausgeführt. Bitte beachten Sie die Kommandoreferenz.

Globale Optionen

Wenn Sie die UMS Administrator CLI in einem Skript verwenden wollen, sollten Sie die Ausgabe nach stdout/stderr konfigurieren. Dies erleichtert die Weiterverarbeitung der Ausgabe von umsadmin-cli und die Extraktion aller relevanten Daten.

Bitte beachten Sie die unten aufgeführten Optionen.

--machine-readable

Maschinenlesbare Ausgabe mit einem Semikolon (;) als Standardtrennzeichen.

Beispiel:

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

Es wird keine Header-Zeile ausgegeben. Nicht alle Kommandos geben eine Header-Zeile aus.)

Beispiel:

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

--quiet

Alle Ausgaben in stdout/stderr werden für einige Befehle unterdrückt, deren Ausführung lange dauern kann. Dies sind z. B. db backup, db restore, db copy und server-restart.

Beispiel:

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

Es ist wetierhin möglich, alle Ausgaben mit Betriebssystemfunktionen auf das Null-Device umzuleiten. Um zum Beispiel unter Linux die Standard- und Fehlerausgabe auf das Null-Device umzuleiten, verwenden Sie:

command … >/dev/null 2>&1

--separator

Definiert ein benutzerdefiniertes Spaltentrennzeichen für die Ausgabe in stdout/stderr.

Beispiel:

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

Einige Trennzeichen, wie z. B. das Pipe-Symbol (|), müssen in Anführungszeichen gesetzt werden, da sie in Terminals besondere Funktionen haben.


Exit-Codes

Exit-CodeBedeutung
0Erfolgreiche Ausführung
1Interner Fehler. Eine Fehlernummer wird auf stderr ausgegeben; für Details, siehe Fehlernummern
2Falsche Verwendung der CLI oder ungültige Argumente

Kommandoreferenz

Allgemeine Verwendung der Passwortoptionen

Einige Befehle erfordern ein Passwort. Die Eingabe des Passworts im Klartext auf der Befehlszeile ist nicht sicher und daher nicht möglich. Daher muss eine der folgenden Passwortoptionen verwendet werden:

--password:in zur interaktiven Eingabe des Passworts (eventuell mit Bestätigung)

--password:file <FILE> für die Bereitstellung einer Datei, die das Passwort enthält

Eine Passwortdatei muss das Passwort in der ersten Zeile enthalten, und die Passwörter dürfen nicht aus reinen Leerzeichen bestehen. Zusätzliche Zeilen mit Inhalt sind erlaubt, werden aber nicht ausgewertet.

Neustart des UMS Servers erforderlich

Die meisten der Befehle in den Abschnitten "Ports", "Cipher", "Reset Certificates" und "Superuser" ändern die UMS-Konfiguration und ein Neustart des UMS-Servers ist erforderlich, damit die neuen Einstellungen wirksam werden. Dies kann auf zwei Arten geschehen:

  • Verwenden Sie die entsprechende Funktion des Betriebssystems (z. B. systemctl unter Linux)
  • Verwenden Sie das Kommando umsadmin-cli server  restart

Datenbank

AktionPrimäres Unter-kommandoSekundäres Unter-kommandoKurze Option Lange OptionWerttypBeschreibung der OptionAnmerkungen
Alle konfigurierten Datenquellen auflistendblist



Zeigt die ID der Datenquelle an, die von anderen Kommandos benötigt wird.

Die niedrigste ID ist 1.

Die IDs können sich bei der Erstellung und Löschung von Datenquellen ändern..

Es wird dringend empfohlen, die ID immer zu extrahieren, bevor sie in anderen Befehlen mit --id verwendet wird

Die ID wird wie folgt berechnet: höchste vorhandene ID + 1

Erstellen Sie eine neue Datenbankverbindung






db






create






-t--typestringDer Datenbanktyp.
Für eine Liste der möglichen Werte, geben Sie umsadmin-cli db create ein.

Typ, Benutzer und Port sind erforderlich.

Andere Optionen können je nach DB-Typ erforderlich sein oder nicht

db create aktiviert die Datenbank standardmäßig; dies kann durch die Verwendung von -A oder --no-activate verhindert werden. Eine Passwortoption kann dann nicht verwendet werden.

Wenn die Aktivierung fehlschlägt, ist der Datenquelleneintrag noch vorhanden und nicht aktiv (gleiches Verhalten wie im grafischen UMS Administrator).

'rmdb' ist ein reservierter Name für den eingebetteten Datenbanktyp und kann nicht für andere Typen verwendet werden.

-H--hoststringDatenbank-Host
-d--domainstringDatenbank-Domäne
-p--portintegerDatenbank-Port
-u--userstringBenutzer für die Datenbank
-S--schemastringSchema der Datenbank
-n--namestring

Name der Datenbank.

Freier Text, außer 'rmdb'; dieser Name ist für die eingebettete Datenbank reserviert.


-I--instancestringName der Datenbankinstanz
-A--no-activate
Die Datenbank wird nicht aktiviert.

--password:filestringDas Passwort wird aus einer Datei (Klartext) gelesen, deren Pfad nach dieser Option angegeben wird.
--password:instringDas Passwort wird von stdin gelesen; eine interaktive Eingabeaufforderung wird angezeigt.
Bearbeiten einer Datenquelledbedit-t--typestringDatenbanktyp.
Für eine Liste der möglichen Werte geben Sie umsadmin-cli db create ein.

Embedded-Datenbanken können nicht bearbeitet werden (wie im grafischen UMS Administrator).

Alle Optionen außer --id sind optional.


--hoststringDatenbank-Host
-i--idintegerID der zu bearbeitenden Datenbank
-I--instancestringName der Datenbankinstanz
-n--namestring

Der Name der Datenbank.

Freier Text, außer 'rmdb'; dieser Name ist für die Embedded-Datenbank reserviert.


-p--portintegerDatenbank-Port

--schemastringSchema der Datenbank
-u--userstringBenutzer für die Datenbank
Datenbankverbindung aktivierendbactivate

--password:filestring

Das Passwort wird aus einer Datei (Klartext) gelesen, deren Pfad nach dieser Option angegeben wird. 

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


--password:instringDas Passwort wird von stdin gelesen; eine interaktive Eingabeaufforderung wird angezeigt.
-i--idintegerID der zu aktivierenden Datenbank

Aktive Datenbankverbindung aktivieren

dbdeactivate-i--idintegerID der zu deaktivierenden Datenbank
Aktive Datenbankverbindung testendbtest
--password:filestring

Das Passwort wird aus einer Datei (Klartext) gelesen, deren Pfad nach dieser Option angegeben wird. 

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


--password:instringDas Passwort wird von stdin gelesen; eine interaktive Eingabeaufforderung wird angezeigt.
Aktive Datenbank optimierendb optimize



Dieser Befehl kann nur auf eine Embedded-Datenbank oder eine Derby-Datenbank angewendet werden.

Kopie der aktuellen Datenbank anlegen

dbcopy-t--targetinteger

ID der Ziel-Datenbank

Um die Datenbank-ID zu erhalten, geben Sie umsadmin-cli db list ein


--password:filestringDas Passwort wird aus einer Datei (Klartext) gelesen, deren Pfad nach dieser Option angegeben wird. 
--password:instringDas Passwort wird aus einer Datei (Klartext) gelesen, deren Pfad nach dieser Option angegeben wird.
Datenbankverbindung löschendbdelete-i--idintegerID der Datenbankverbindung, die gelöscht werden soll
Sicherungskopie der aktuellen Embedded-Datenbank erstellendb

backup

-o--outfile

Pfad zur Zieldatei. Die Dateiendung .pbak wird automatisch hinzugefügt. 

Vorhandene Sicherungsdateien werden nicht überschrieben.


-f--full
Vollständige Sicherung. Datenbank, Serverkonfigurationen und Übertragungsdateien sind enthalten.
-p--parent
Alle Verzeichnisse für den angegebenen Pfad werden erstellt, sofern sie nicht bereits vorhanden sind.

Sicherungskopie in die Embedded-Datenbank wiederherstellen

dbrestore-f--file
Pfad zur Sicherungsdatei

Ports

AktionPrimäres Unter-kommandoSekundäres Unter-kommandoKurze Option Lange OptionWerttypBeschreibung der Option

Alle Ports und SSL-only-Flag anzeigen

portslist



Neue Portnummern oder SSL-only-Flag setzen



ports



set



-d--dev-commintegerPort für die Kommunikation mit den Geräten. Einzelheiten siehe Geräte kontaktieren die UMS.
-j--java-webstartintegerPort für Java Web Start
-w--web-serverintegerPort für den UMS Server. Einzelheiten siehe UMS mit interner Datenbank und UMS mit externer Datenbank.
-e--embeddedintegerPort der Embedded-Datenbank

--ssl-onlybooleanNur SSL-Verbindungen erlauben

Cipher

AktionPrimäres Unter-kommandoSekundäres Unter-kommandoKurze Option Lange OptionWerttypBeschreibung der Option  
Alle Ciphers auflisten, optional gefiltertcipherlist


Alle Ciphers auflisten
-e--enabled
Nur aktivierte Ciphers auflisten
-d--disabled
Nur deaktivierte Ciphers auflisten
Ciphers aktivierencipherenable



Ciphers aktivieren. Die Ciphers werden durch Leerzeichen getrennt.

Beispiel: umsadmin-cli cipher enable CIPHER1 CIPHER 2 CIPHER3 

--all

Auf alle anwenden; einzelne Ciphernamen werden ignoriert.

Ciphers deaktivierencipherdisable



Ciphers deaktivieren. Die Ciphers werden durch Leerzeichen getrennt.

Beispiel: umsadmin-cli cipher disable CIPHER1 CIPHER 2 CIPHER3

--all

Auf alle anwenden; einzelne Ciphernamen werden ignoriert..

Web-Zertifikate zurücksetzen

AktionPrimäres Unter-kommandoKurze OptionLange OptionBeschreibung der Option
Web-Zertifikate zurücksetzenreset-certs-y--yesNur wenn Sie dies bestätigen, wird der Reset ausgeführt.

Superuser

AktionPrimäres Unter-kommandoSekundäres Unter-kommandoKurze Option Lange OptionWerttypBeschreibung der Option  
UMS Superuser anzeigensulist



UMS Superuser ändern

su

change

-u--userstringNeuer Superuser
-p--password:filestringDas Passwort wird aus einer Datei (Klartext) gelesen, deren Pfad nach dieser Option angegeben wird.

--password:instringDas Passwort wird von stdin gelesen; eine interaktive Eingabeaufforderung wird angezeigt.

UMS-Lizenz-ID

AktionPrimäres Unter-kommandoSekundäres Unter-kommandoKurze Option Lange OptionWerttypBeschreibung der Option
Aktuelle Lizenz-IDs anzeigenlicensinglist



Neue Lizenz-ID erstellenlicensingcreate



Lizenz-ID sichernlicensing

backup

-o--outfilestringPfad zur Zieldatei (Dateiendung: .ksbak)
-p--parent
Alle Verzeichnisse für den angegebenen Pfad werden erstellt, sofern sie nicht bereits vorhanden sind.

--password:filestringDas Passwort wird aus einer Datei (Klartext) gelesen, deren Pfad nach dieser Option angegeben wird.

--password:instringDas Passwort wird von stdin gelesen; eine interaktive Eingabeaufforderung wird angezeigt.
Lizenz-ID aus einem Backup wiederherstellen

licensing

restore

-f--filestringPath to the backup file

--password:filestringDas Passwort wird aus einer Datei (Klartext) gelesen, deren Pfad nach dieser Option angegeben wird.

--password:instringDas Passwort wird von stdin gelesen; eine interaktive Eingabeaufforderung wird angezeigtaus einer Datei (Klartext), deren Pfad nach dieser Option angegeben wird.

Netzwerktoken

AktionPrimäres Unter-kommandoKurze Option Lange Option WerttypBeschreibung der OptionAnmerkungen
Netzwerk-Token für den UMS Server oder einen Broker installierentoken

-f--token-filestring

Pfad zur Datei des Tokens

Dieser Befehl ist auch als eigenständiger Befehl namens umstokeninstall-cli in reinen Broker-Installationen verfügbar. Er ist äquivalent zu umsadmin-cli token.



--serverbooleanToken für UMS Server installieren
--brokerbooleanToken für Broker installieren

Server

AktionPrimäres Unter-kommandoSekundäres Unter-kommandoKurze Option Lange Option Beschreibung der Option
Lokalen UMS Server startenserverstart


Lokalen UMS Server stoppenserverstop


Lokalen UMS Server neu startenserverrestart


Update-Modus für den lokalen UMS Server beendenserverend-update-mode


Distributed-Modus der UMS Installation einstellenserverdistributed-e--enableDistributed UMS aktivieren

-d--disableDistributed UMS deaktivieren

Fehlernummern

Die Fehlernummern werden in folgendem Format ausgegeben:

<E-NNNN>: <HUMAN READABLE MESSAGE>

Einige Fehlerbeschreibungen in der folgenden Tabelle enthalten die Phrase "[param]". Diese wird zur Laufzeit durch Angaben zum jeweiligen Fehler ersetzt, z.B. den problematischen Pfad für E-1030.

FehlernummerFehlerbeschreibung
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 while optimize 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 activate 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.
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 super user credentials.
5001Internal error while writing super user credentials.
5002No username was provided for new credentials.
5003Unable to set superuser credentials. There is no active data source.
6000Unable to create new licensing 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.
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 occured: [param]
9001The provided passwords did not match. Aborted.
9002The provided password exceeds the maximium character limit ([param]) or contains only whitespace.